© Ribose Asia Limited 2026
This document is not a Ribose Standard. It is distributed for review and comment, and is subject to change without notice and may not be referred to as a Standard. Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission. Permission can be requested from the address below.
Ribose Asia Limited
Suite 1, 8/F, New Henry House
10 Ice House Street
Central
Hong Kong
www.ribose.com
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.
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.
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.
No terms and definitions are listed in this document.
the UnitsDB dataset: the seven collections of Clause 5 at one uniform schema_version.
one of the register’s YAML files and its validated content.
a currency code: a unit of account that is its own base and admits no conversion factor.
the quantity_reference entry flagged primary: true for a unit — the kind the unit denotes when none is asserted.
an L1 grouping declared on quantities; kinds in one class are interchangeable for addition and subtraction.
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.
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.
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.
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).
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).
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.
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).
scales.yaml classifies scales and lists the operations each permits; consumers take operation legality from this data (CalConnect 36815).
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.
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.
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.
Expected outcome. work + energy conforms (same class); energy + torque is a specified error naming both kinds; torque is deliberately outside the energy class.
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.
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.
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.
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.
Enforced by the register’s own 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).
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.
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.
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.
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.