Foreword
UnitsDB is the single source of truth of the series: every unit identity, prefix, dimension, quantity kind, scale class, conversion factor and currency in the ecosystem resolves from this register, and no implementation hardcodes any of it. This part specifies the register’s collections, its schema versioning policy, and the content rules introduced with schema 2.2.0.
Introduction
A register earns its role by being the only place a fact lives. When the joule’s primary quantity lived in positional YAML order, consumers rendered “Lagrange function” — an artifact of line order, not of metrology. Every content rule in this part exists to move such facts out of accident and into declared, validated data.
1 Scope
This document specifies the collections of the register and their interreferences; the schema versioning policy; and the content rules for canonical conversions, scale operation legality, primary quantity references, L1 equivalence classes, and currencies.
The semantics of consuming this data — resolution, gating, conversion application — are specified in CalConnect 36815 and CalConnect 36816.
2 Normative references
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
ISO 4217, INTERNATIONAL ORGANIZATION FOR STANDARDIZATION (ISO). Codes for the representation of currencies. Report no. 4217. Eighth edition. Geneva: International Organization for Standardization, Available from: https://www.iso.org/standard/64758.html.
IEC 62720, (units dictionary; source corpus only — no IEC backing of this register is implied)
CalConnect 36811, UnitsML — UnitsDB specification (v1 base standard, frozen 2025-03; historical)
3 Terms and definitions
No terms and definitions are listed in this document.
register
the UnitsDB dataset: the seven collections of Clause 5 at one uniform schema_version.
collection
one of the register’s YAML files and its validated content.
denomination
a currency code: a unit of account that is its own base and admits no conversion factor.
primary quantity reference
the quantity_reference entry flagged primary: true for a unit — the kind the unit denotes when none is asserted.
equivalence class
an L1 grouping declared on quantities; kinds in one class are interchangeable for addition and subtraction.
4 Conventions
Requirement language per CalConnect 36812. Identifier pairs are written (type, id); NIST identifiers are primary for cross-collection references; unitsml: identifiers (u:, q:, cur:, d:, us:) are the series’ own namespace.
5 Collections and identifiers
The register comprises units.yaml, prefixes.yaml, dimensions.yaml, quantities.yaml, scales.yaml, unit_systems.yaml, currencies.yaml. All collections in one release carry the SAME schema_version, quoted. Loaders treat units, prefixes, dimensions, quantities and unit systems as required and currencies as optional-if-absent; any collection that is present matches the uniform version.
EXAMPLE
Expected outcome. A loader presented with units at 2.2.0 and currencies at 2.1.0 rejects the register with a version-mismatch error naming both files. A loader presented with no currencies file at all loads the five required collections and exposes an empty currency collection.
6 Schema versioning policy
The schema version moves only by maintainer decision. Additive optional fields move the minor component; removals or semantic changes move the major component. A schema version is supported by the register loader before a data release can adopt it (unitsdb-ruby ≥ 2.2.12 supports 2.2.0).
EXAMPLE
Expected outcome. Schema 2.2.0 added exactly two optional fields — primary on unit quantity references and equivalence_class on quantities — and every collection moved 2.1.0 → 2.2.0 in one release, with the loader support released first (unitsdb-ruby 2.2.12).
7 Content rules
7.1 Canonical conversions
A unit whose derivation is mechanical carries canonical_conversion: an exact rational factor (decimal or p/q string), an offset where the unit is affine, and the root_units decomposition the factor was computed over (present in every such record). Units at powers other than 1, affine units inside composites, logarithmic units, and prefix-level units do not carry canonical data; the coverage report itemizes every unit as generated, derived-by-design, or source-needed with a reason.
EXAMPLE
Expected outcome. foot per minute carries factor: 127/25000 with root_units = foot × minute⁻¹; gram-force carries none and is reported “self-referential root_units — needs a sourced definition” (its 9.80665 value is source-needed, not derivable).
7.2 Scale operation legality
scales.yaml classifies scales and lists the operations each permits; consumers take operation legality from this data (CalConnect 36815).
7.3 Primary quantity reference
A unit with more than one quantity_reference designates exactly one entry primary: true. Selection rule: the quantity in the SI Brochure definition where the unit has an SI special name (joule → energy, weber → magnetic flux, …); the explicitly curated first entry otherwise. The current register flags 96 units.
EXAMPLE
Expected outcome. The joule’s references list NISTq17 with primary: true; every other entry is unflagged. A consumer rendering without an asserted kind emits “energy” — never “Lagrange function”, which is merely a member of the reference list.
7.4 L1 equivalence classes
A quantity MAY declare equivalence_class: quantities in the same class are interchangeable for addition and subtraction. The energy class is landed (energy, work, kinetic energy, mechanical energy, amount of heat, potential energy); all other quantities gate identity-only. Classes are curated from ISO 80000 usage; never inferred in code.
EXAMPLE
Expected outcome. work + energy conforms (same class); energy + torque is a specified error naming both kinds; torque is deliberately outside the energy class.
8 Currencies
Each ISO 4217 code is its own base: no root units, no cross-currency factors, ever — floating exchange rates would make any stored factor silently wrong. The register carries the 178 active List One codes with ISO numeric identifiers. Minor units: ISO’s “N.A.” is recorded as ABSENT, never 0; KMF and XDR carry the real value 0.
EXAMPLE
Expected outcome. cur:EUR resolves with ISO numeric 978, symbol €, minor_unit_exponent: 2; cur:KMF carries minor_unit_exponent: 0; the 13 precious-metal and fund codes carry NO minor_unit_exponent key at all. A dataset conflating absent with 0 is non-conforming.
9 Provenance and licensing
Imported data records its source corpus, snapshot identity and license. The IEC 62720 import carries an informative reference per unit and implies no IEC endorsement. Source defects in imported corpora are counted and reported, never silently corrected.
EXAMPLE
Expected outcome. The IEC 62720 coverage report enumerates every resolvable conversion as agreed (metre, kelvin, degree Celsius anchors) with zero disagreements, counts the duplicate lowercase finaladdend attribute as a source defect, and itemizes the 3 824 IEC-specific composites that have no register counterpart.
10 Conformance
Enforced by the register’s own validation suite (Annex A) and by the conversion and scale vectors of CalConnect 36819, Annex B. Conformance classes: quantity-conversion requires this part. Additional test-suite examples are given in Annex B.
Annex A
(normative)
Annex A (normative): validation suite
The register passes, per release:
JSON-schema validation of every collection against schemas/*-schema.yaml;
identifier uniqueness (unitsdb validate identifiers);
reference integrity (unitsdb validate references);
SI-reference integrity (unitsdb validate si_references);
numeric-uniqueness and lockstep checks for currencies.
The schema validation step runs in the PR lane; a silent landing is a process defect (it happened once — the post-#138 factor quoting — and the gate was added).
Annex B
(normative)
Annex B (informative): additional test-suite examples
EXAMPLE 1
Primary-reference red/green. Render the joule without an asserted kind. Red: Quantity id="NISTq152" name="Lagrange function". Green: name="energy" via NISTq17, primary: true.
EXAMPLE 2
Coverage report shape. Every register unit appears exactly once in the conversion coverage report as generated, derived-by-design (SI base, prefix-level), or source-needed with a reason string; no unit is unlisted.
EXAMPLE 3
Equivalence gate. unit(J::work) + unit(J::energy) evaluates; unit(J::energy) + unit(N·m::torque) raises naming both kinds; both vectors are frozen in CalConnect 36819 Annex B.
Bibliography
[1] NIST SP 811:2008, Guide for the Use of the International System of Units (SI)
[2] unitsml/unitsdb content rules, — issues #130, #134, #135, #136, #137, #138, #139 (content-rule provenance)
[3] isq-smart concept-system methodology, ; Pendrill 2024