diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 68d5da4cd0..bb22c700cd 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -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: @@ -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