Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[FIX] Clarify requirement levels for TSV metadata fields #555

Merged
merged 3 commits into from
Aug 11, 2020
Merged

[FIX] Clarify requirement levels for TSV metadata fields #555

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
760ee1a
clarify requirement levels for TSV sidecar JSONs
sappelhoff Aug 2, 2020
20500a8
Update src/02-common-principles.md
sappelhoff Aug 3, 2020
7a64fc8
clarify levels+units both recommended
sappelhoff Aug 8, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 18 additions & 16 deletions src/02-common-principles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -414,21 +414,23 @@ in the form of a [JSON object](https://www.w3schools.com/js/js_json_objects.asp)
within a JSON file.
The JSON files containing the data dictionaries MUST have the same name as
their corresponding tabular files but with `.json` extensions.
If a data dictionary
is provided, it MAY contain one or more fields describing the columns found in
the TSV file (in addition to any other metadata one wishes to include that
describe the file as a whole). Note that if a field name included in the data
dictionary matches a column name in the TSV file, then that field MUST contain a
description of the corresponding column, using an object containing the following
fields:

| Field name | Definition |
| :---------- | :-------------------------------------------------------------------------------------------------------------- |
| LongName | Long (unabbreviated) name of the column. |
| Description | Description of the column. |
| Levels | For categorical variables: a dictionary of possible values (keys) and their descriptions (values). |
| Units | Measurement units. SI units in CMIXF formatting are RECOMMENDED (see [Units](./02-common-principles.md#units)). |
| TermURL | URL pointing to a formal definition of this type of data in an ontology available on the web. |
If a data dictionary is provided,
it MAY contain one or more fields describing the columns found in the TSV file
(in addition to any other metadata one wishes to include that describe the file as a whole).
Note that if a field name included in the data dictionary matches a column name in the TSV file,
then that field MUST contain a description of the corresponding column,
using an object containing the following fields:

| Field name | Definition |
| :---------- | :--------------------------------------------------------------------------------------------------------------------------- |
| LongName | OPTIONAL. Long (unabbreviated) name of the column. |
| Description | RECOMMENDED. Description of the column. |
| Levels | RECOMMENDED. For categorical variables: a dictionary of possible values (keys) and their descriptions (values). |
| Units | RECOMMENDED. Measurement units. SI units in CMIXF formatting are RECOMMENDED (see [Units](./02-common-principles.md#units)). |
| TermURL | RECOMMENDED. URL pointing to a formal definition of this type of data in an ontology available on the web. |

Please note that while both `Units` and `Levels` are RECOMMENDED, typically only one
of these two fields would be specified for describing a single TSV file column.

Example:

Expand Down Expand Up @@ -459,7 +461,7 @@ pairs. JSON files MUST be in UTF-8 encoding. Extensive documentation of the
format can be found here: [http://json.org/](http://json.org/). Several editors
have built-in support for JSON syntax highlighting that aids manual creation of
such files. An online editor for JSON with built-in validation is available at:
[http://jsoneditoronline.org](http://jsoneditoronline.org).
[http://jsoneditoronline.org](http://jsoneditoronline.org).
It is RECOMMENDED that keys in a JSON file are written in [CamelCase](https://en.wikipedia.org/wiki/Camel_case)
with the first letter in upper case (e.g., `SamplingFrequency`, not
`samplingFrequency`). Note however, when a JSON file is used as an accompanying
Expand Down