Field Naming

Name fields for the reader, and preserve the vendor’s vocabulary. A schema is understandable when someone familiar with the experiment, instrument technique, or the source data can traverse it and know what each field means — aided by the documentation and example files, without guessing. Ambiguity in names or structure is a defect.

• Use clear, consistent names (snake_case; singular for scalars, plural for arrays (follows English grammar); an _id suffix for identifiers).

• Do not encode units, types, or values into field names — units belong in the data as a sibling of the value (see Units). Prefer { "value": 2.5, "unit": "NanoMole" } over concentration_nM: 2.5.

• Preserve the instrument software’s own terminology where it aids recognition, in the field name or in the field’s description. When the IDS name must differ for cross-vendor harmonization, record the original vendor term in the description so the mapping is traceable.

• Every field should be understandable from its name plus its description inside schema.json and the schema’s README. If understanding a field requires reading the task script source code, the schema is under-documented.