Revises the singular field of the tag table to 'label' to remove double speak from implementations (e.g. tag.tag)

This commit is contained in:
aewens 2020-12-29 17:16:39 +00:00
parent a4d7018c62
commit fecc1b1e1c

View File

@ -106,7 +106,7 @@ While the refined data table could technically just be a typed version of raw da
### Tagging Tables
Due to the limitations of relational databases, the tagging table actually needs to be two tables: the table for the actual tags and another to map the tags to the other two tables. However, these two will be referred to as a single component here since individually they are useless without the other. The unique field provided by the former of the two tables is simply:
- Tag: the descriptive name of the tag, represented as a string up to 128 characters
- Label: the descriptive label of the tag, represented as a string up to 128 characters
The latter table will actually not share the common fields mentioned above, but will simply be composed of the following fields:
- ID: the database index, this will be the auto-incremented unsigned integer primary key
@ -114,7 +114,7 @@ The latter table will actually not share the common fields mentioned above, but
- Raw ID: points to a raw data entry, done with a foreign key the the _id_ field (optional)
- Refined ID: points to a refined data entry, done with a foreign key the the _id_ field (optional)
Individually each table ID field is optional, but at least two are required. The purpose of this table is to create a one-to-one or one-to-many relationship between two entities from different tables. The intended purpose is to use this for making links between a tag an some other entity, but this can just as easily be used for making a link between a raw date entry and refined data entry. One may notice a lack of ability to trivially link an entry to another member of its own table (e.g. a refined data entry to another refined data entry), but role is accomplished by the tags. While a tag entry (ignoring its common fields) consists of only the humble _tag_ field, there is still a lot of power and versatility offered here. A tag can be used to represent **any** kind of relationship between two entities. For example, a refined data entry (called "A") can be linked to three other refined data entries (called "B", "C", and "D") can by creating a single tag with the _tag_ field assigned the same _uuid_ as the "A" field tag maps to the other three entries. Then the service can simply do a query for tags that's _tag_ field match a refined entry's _uuid_, and any entries matched to that tag in the associative table will provide the linked entries (e.g. "B", "C", and "D" from our examples). This is just one of many ways the tags can be utilized, other uses include:
Individually each table ID field is optional, but at least two are required. The purpose of this table is to create a one-to-one or one-to-many relationship between two entities from different tables. The intended purpose is to use this for making links between a tag an some other entity, but this can just as easily be used for making a link between a raw date entry and refined data entry. One may notice a lack of ability to trivially link an entry to another member of its own table (e.g. a refined data entry to another refined data entry), but role is accomplished by the tags. While a tag entry (ignoring its common fields) consists of only the humble _label_ field, there is still a lot of power and versatility offered here. A tag can be used to represent **any** kind of relationship between two entities. For example, a refined data entry (called "A") can be linked to three other refined data entries (called "B", "C", and "D") can by creating a single tag with the _label_ field assigned the same _uuid_ as the "A" field tag maps to the other three entries. Then the service can simply do a query for tags that's _label_ field match a refined entry's _uuid_, and any entries matched to that tag in the associative table will provide the linked entries (e.g. "B", "C", and "D" from our examples). This is just one of many ways the tags can be utilized, other uses include:
- Marking fields as "favorite" for a specific user
- Assigned a rating to an entry
- Supplying a means to define a hierarchical structure to entries
@ -122,7 +122,7 @@ Individually each table ID field is optional, but at least two are required. The
#### Convention
An important note for the _tag_ field is that, unlike the other string-based fields, it caps at 128 characters as opposed to 64 like the others. This allows for the value of _tag_ to be a combination of two _uuid_ fields, which can be useful in some trivial usages of the tags (e.g. for the example of a "favorite" tag for a user, the value of _tag_ can be the _uuid_ of the user plus some suffix). The restriction of 64 characters on every other field prevents trivial implementation like this for other entries since it is only appropriate for a tag entry.
An important note for the _label_ field is that, unlike the other string-based fields, it caps at 128 characters as opposed to 64 like the others. This allows for the value of _label_ to be a combination of two _uuid_ fields, which can be useful in some trivial usages of the tags (e.g. for the example of a "favorite" tag for a user, the value of _label_ can be the _uuid_ of the user plus some suffix). The restriction of 64 characters on every other field prevents trivial implementation like this for other entries since it is only appropriate for a tag entry.
#### Rationale
@ -162,7 +162,7 @@ The following template is the valid JSON structure for entries from the data tab
}
```
Transmitting the tagging data is special, as the SQL representation of the relationships does not carry over well into JSON. Instead, an optional _tags_ field can be included in either of the data table entries with a list of the _tag_ field values that are associated with the entry. A tagged version of the two examples above would be:
Transmitting the tagging data is special, as the SQL representation of the relationships does not carry over well into JSON. Instead, an optional _tags_ field can be included in either of the data table entries with a list of the _label_ field values that are associated with the entry. A tagged version of the two examples above would be:
```json
{