Representing physical quantities in JSON: value, unit and precision as separate fields

Goal

Exchange measured or computed quantities in JSON so that a consumer can tell the number, the unit and how much of the number is meaningful without guessing from a field name.

Prerequisites

A list of the quantity kinds the interface carries (length, mass, duration, temperature; money is handled separately), a decision on a unit vocabulary, and agreement on whether each field is fixed-unit (every producer uses the same unit) or mixed-unit (the producer chooses).

Steps

1. For each quantity kind pick one canonical unit for storage and computation, preferably the SI unit or a coherent derived unit (metres, kilograms, seconds), and convert at the boundary.
2. Fixed-unit fields: put the unit in the field name (duration_ms, distance_m) and use a plain JSON number. This is compact and hard to misread.
3. Mixed-unit fields (user-entered values, instruments with their own units): use an object {"value": 12.5, "unit": "kg"} with unit taken from a controlled vocabulary. UCUM (cited) provides machine-readable unit codes in ASCII; it defines case-sensitive symbols (kg, Cel, [in_i]) and a separate case-insensitive variant, so state which variant the interface uses.
4. Carry precision explicitly when it matters: a separate uncertainty or resolution field, not trailing zeros. RFC 7946 (cited) makes this rule for coordinates, stating that the number of digits must not be interpreted as an indication of uncertainty; parsers do not preserve digit counts, so the rule holds for any quantity.
5. Use a string holding a decimal representation when the exact decimal value matters (a reading copied from a display, a regulatory limit); use JSON numbers for values that are approximate by nature.
6. Validate in the schema: an enumeration for unit, a numeric range per unit, and a rule that value and unit appear together or not at all.
7. Treat temperature specially: UCUM classes the degree Celsius as a special unit on a non-ratio scale, converted with an offset rather than a factor and excluded from multiplication and exponentiation; store kelvin or Celsius and say which.

Expected result

A consumer can convert any value to its canonical unit mechanically, unit mismatches are caught by schema validation instead of surfacing as wrong results, and precision claims are explicit rather than inferred from formatting.

Limits and test basis

The procedure is a proposal derived from the cited specifications; no measurement of its effect is claimed. It does not cover currency amounts, which have their own rules (minor units per currency), nor compound units whose codes must be composed (kg.m/s2 in UCUM syntax). Unit vocabularies differ (UCUM, UN/CEFACT codes, ontologies); mixing them in one interface defeats the purpose, so choose one and record the choice in the schema.