The schema's tables and fields are listed in flat tables.
tables.tsv
Provides details at the table-level, one record per table:
| Name | A machine-readable identifier token. Preferably lower snakecase. |
| Label | A UI-displayable label. |
| Filename | A conventional file basename for when this table is serialized to file. Typically this should just be the Name plus .tsv. |
| Entity | The Name or Label of the type of the entities that the records of this table will be about. Should match a record in entities.tsv. |
fields.tsv
A field is one of the slots for entries in the records of a given table, i.e. a table column. Recall that each record corresponds to some particular entity; each field should be associated with a property that such an entity has. We allow the field itself to have its own name and label, apart from the name of the associated property (property type), in order to account for the particular context provided by the given table. Such field names, often abbreviations, may be more convenient in some contexts.
fields.tsv provides the list of fields of a given table.
| Name | A machine-readable identifier token, preferably lower snakecase, to appear as a column header when a machine-readable normalized name is needed. |
| Label | A UI-displayable label for the column. |
| Table | The Name or Label of the table to which the field belongs. Must match a record in tables.tsv. |
| Property | The Name or Label of a property. Must match a record in properties.tsv. |
| Primary key group | If the values of this field, possibly together with those of a group including some other fields, are intended to provide unique identifiers for the entities within the scope of the table, then the value here should be a name for the group of fields which together serve as a primary key. The group can be a singleton. |
| Foreign table | If the property for the field is of relation type, this is the Name or Label of the table in which a record of the target entity can be found. |
| Foreign key | If the property for the field is of relation type, as above, this is the Name or Label of the field in the foreign table in which to search for an identifier of the foreign/target entity. This may be left blank if this information can be inferred, for example if there is only one primary key in the foreign table. |
| Ordinality | When a record occurs as a list without named elements, i.e. when the header is not explicitly provided, the correct assignment to fields can be inferred from the ordinality information provided here. This should be an integer, starting with 1, 2, 3, … . |
Note: In many cases it is convenient to work with header values that are data-dependent, parameterized by data values at runtime. For example, for a ‘cell’ table, ‘CD20 protein expression’ as the general field ‘– protein expression’ instantiated with the name of a gene, ‘CD20’. However, to avoid the complexity that such a structure presents to a formal schema, for the purposes of the ADI we recommend refactoring such occurrences into a new table, e.g. a ‘cell protein expression’ table with fields ‘cell’, ‘protein’, and ‘protein expression’. Applying this general pattern tends to result in ‘narrower and taller’ data tables, i.e. with fewer columns but more records.
Note: By convention each Label value should be maximally derivative of the corresponding Name value, and vice-versa. This convention may occasionally be broken for clarity, as when acronymic capitalization information is important in the Label.