Foreword
This part of the UnitsML specification series establishes the register procedures, the normative vocabulary, the artifact discipline and the release procedures that every other part assumes. It is the root of the series: every other part cites it for requirement language and procedures and carries no duplicate of that content.
The series is developed within the UnitsML program. The program dependency graph and stage gates are tracked in unitsml/unitsml-ruby#95. The series is specified in the ribose document flavor: each part states its model normatively (LML where the content is a data model, PARG where it is a grammar), carries worked examples with expected outcomes, and is gated by the register validator and the frozen corpora.
Introduction
The UnitsML stack expresses measurement — values, units, quantity kinds, uncertainty — across a data register (UnitsDB), expression languages and multiple output formats, with implementations in Ruby, TypeScript and Rust. The architecture principle of the series is that artifacts are the product and engines are interchangeable: everything shareable is compiled to a checksummed artifact, every runtime replays the same conformance corpora, and byte-identity across languages is enforced by contract testing rather than by shared binaries.
Implementations follow a reference-first rule: the Ruby implementation lands every semantic layer first and its outputs are frozen as the oracle corpora; implementations in other languages are generated from schema declarations or verified against those corpora, never re-derived independently.
1 Scope
This document specifies:
the procedures of the UnitsML specification register: document numbering, types, lifecycle and amendment rules;
the normative vocabulary of the series and the binding of statements to conformance classes;
the artifact discipline: checksums, editions, and the binding between normative parts and their conformance corpora;
the release and distribution procedures for the data register and its downstream packages.
This document does not specify any behavior of units, quantities, conversions, expressions or evaluation; those are specified in Parts 2 to 8 and in the companion Plurimath series.
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.
JCGM 200:2012, INTERNATIONAL ORGANIZATION FOR STANDARDIZATION, ORGANISATION INTERNATIONALE DE NORMALISATION (ISO), INTERNATIONAL ELECTROTECHNICAL COMMISSION, COMMISSION ÉLECTROTECHNIQUE INTERNATIONALE (IEC), INTERNATIONAL ORGANIZATION OF LEGAL METROLOGY, ORGANISATION INTERNATIONALE DE MÉTROLOGIE LÉGALE (OIML), INTERNATIONAL UNION OF PURE AND APPLIED CHEMISTRY, UNION INTERNATIONALE DE CHIMIE PURE ET APPLIQUÉE (IUPAC), INTERNATIONAL UNION OF PURE AND APPLIED PHYSICS, UNION INTERNATIONALE DE PHYSIQUE PURE ET APPLIQUÉE (IUPAP), INTERNATIONAL FEDERATION OF CLINICAL CHEMISTRY AND LABORATORY MEDICINE, FÉDÉRATION INTERNATIONALE DE CHIMIE CLINIQUE ET DE BIOLOGIE MOLÉCULAIRE (IFCC), INTERNATIONAL LABORATORY ACCREDITATION COOPERATION, COOPÉRATION INTERNATIONALE D’ACCRÉDITATION DES LABORATOIRES (ILAC), and BUREAU INTERNATIONAL DES POIDS ET MESURES (BIPM). International vocabulary of metrology – Basic and general concepts and associated terms (VIM). Report no. JCGM 200:2012. Third edition. Paris: International Bureau of Weights and Measures, Bureau international des poids et mesures; International Organization for Standardization, Organisation internationale de normalisation; International Organization for Standardization, Organisation internationale de normalisation; International Electrotechnical Commission, Commission électrotechnique internationale, 2012. Available from: https://www.bipm.org/documents/20126/2071204/JCGM_200_2012.pdf/f0e1ad45-d337-bbeb-53a6-15fe649d0ff1.
JCGM 100:2008, INTERNATIONAL ORGANIZATION FOR STANDARDIZATION, ORGANISATION INTERNATIONALE DE NORMALISATION (ISO), INTERNATIONAL ELECTROTECHNICAL COMMISSION, COMMISSION ÉLECTROTECHNIQUE INTERNATIONALE (IEC), INTERNATIONAL ORGANIZATION OF LEGAL METROLOGY, ORGANISATION INTERNATIONALE DE MÉTROLOGIE LÉGALE (OIML), INTERNATIONAL UNION OF PURE AND APPLIED CHEMISTRY, UNION INTERNATIONALE DE CHIMIE PURE ET APPLIQUÉE (IUPAC), INTERNATIONAL UNION OF PURE AND APPLIED PHYSICS, UNION INTERNATIONALE DE PHYSIQUE PURE ET APPLIQUÉE (IUPAP), INTERNATIONAL FEDERATION OF CLINICAL CHEMISTRY AND LABORATORY MEDICINE, FÉDÉRATION INTERNATIONALE DE CHIMIE CLINIQUE ET DE BIOLOGIE MOLÉCULAIRE (IFCC), INTERNATIONAL LABORATORY ACCREDITATION COOPERATION, COOPÉRATION INTERNATIONALE D’ACCRÉDITATION DES LABORATOIRES (ILAC), and BUREAU INTERNATIONAL DES POIDS ET MESURES (BIPM). Guide to the expression of uncertainty in measurement. Report no. JCGM 100:2008. First edition. Paris: International Bureau of Weights and Measures, Bureau international des poids et mesures; International Organization for Standardization, Organisation internationale de normalisation; International Electrotechnical Commission, Commission électrotechnique internationale, 2008. Available from: https://www.bipm.org/documents/20126/2071204/JCGM_100_2008_E.pdf/cb0ef43f-baa5-11cf-3f85-4dcd86f77bd6.
3 Terms and definitions
No terms and definitions are listed in this document.
For the purposes of this document, the following terms and definitions apply.
artifact
versioned, checksummed, language-independent file produced from a normative source (grammar, register, schema, corpus) and consumed by implementations without modification. Artifact bytes are authoritative; consumers verify checksums before use.
corpus
a versioned collection of test vectors owned by CalConnect 36819. A corpus entry names its normative source clause and the tolerance convention that applies.
oracle
an implementation whose output is frozen into a corpus. The reference implementation of the series is the Ruby one; corpora are frozen from it.
edition
a recorded revision of an artifact or register, identified by checksum and version string.
conformance class
the set of vector classes an implementation replays, licensing specific claims (CalConnect 36819).
dialect L
the legacy AsciiMath compatibility dialect (Plurimath series, asciimath Part 1); not extended by this series.
dialect P (pma)
the featureful strict input language (Plurimath series, pma Part 1).
SP 811
NIST Special Publication 811, Guide for the Use of the International System of Units (SI).
VIM
JCGM 200, International vocabulary of metrology.
4 Conventions
Normative statements are declarative: the document states what implementations do and what invariants hold, and an implementation that does otherwise does not conform. A statement binds an implementation only within the conformance class it claims (CalConnect 36819).
EXAMPLE
A TypeScript runtime that replays the parse/render and conversion corpora but no evaluator vectors claims class quantity-conversion; it does not advertise evaluation.
Single-source normativity: a normative rule is stated in exactly one part of the series; other parts cite it. Restating a rule from another part is an editorial defect corrected on sight.
5 Register procedures
5.1 Document types
Register documents are classified as in Table 1.
| Type | Meaning |
|---|---|
| Standards Track | normative specifications of behavior, data or syntax; enforced by corpora |
| Informational | orientation, glossaries, research notes; never cited as a requirement source |
| Process | this document and its amendments |
5.2 Lifecycle
Idea → Draft (docstage 20) → Committee Draft (30) → Final Draft (50) → Published (60).
EXAMPLE
Expected outcome. A part moved to docstage 60 without its Annex test vectors frozen in CalConnect 36819 is mis-published; the register procedure rejects the move.
5.3 Numbering
Part numbers are permanent and never reused. Informational documents share the numbering space with an explicit type marker.
5.4 Amendments
A Published document changes only by a numbered Amendment; corrections that would alter normative content require an Amendment entry, never silent edits.
EXAMPLE
Expected outcome. Correcting “Lagrange function” to “energy” in a rendered example is an editorial fix; changing the primary-reference selection rule of CalConnect 36814 requires “CalConnect 36814/Amd.1”.
6 Conformance language
Statements are declarative; requirement strength comes from precision and from the corpus vectors that test them.
EXAMPLE
Interpretation. “Conversions with exact="true" are computed in exact rational arithmetic” (CalConnect 36816: an implementation returning 0.1 as a binary float for a declared-exact tenth is non-conforming, and the violation is detectable by byte comparison of the serialized decimal string.
7 Artifact discipline
Every artifact carries a checksum; consumers verify it before load. Every artifact records its edition (source revision and generation date). Grammars, the register dataset, model schemas and corpora are artifacts; per-language engines are not. A change to artifact content regenerates the artifact and its conformance corpus in the same change.
EXAMPLE
Expected outcome. The asciiunits artifact ships artifacts/unitsml.json with a checksum file. A consumer loading the artifact with a stale checksum aborts with a typed load error — not a warning — because grammar and behavior are bound to the bytes.
8 Distribution and release procedures
The release chain is strict and ordered:
unitsdb data (tag v*) → unitsdb-ruby (submodule pin, VERSION, UNITS_DATA_VERSION) → unitsml-ruby (payload regeneration, dependency bump) → unitsdb-ts / unitsml-ts (dataset rebuild) → npm (bare, unprefixed names)
Rules:
Data schema versions and package versions are independent; the data pin travels via UNITS_DATA_VERSION.
Releases are PATCH bumps unless the maintainer states otherwise.
npm package names are bare and unprefixed (unitsml, unitsdb, asciiunits).
Release workflows run Node 24: trusted publishing requires npm ≥ 11.5.
Every release is gated by conformance-corpus replay (CalConnect 36819).
EXAMPLE
Expected outcome (worked release). Data PRs land schema 2.2.0 (primary references, equivalence classes, 121 canonical conversions, IEC 62720 coverage) → tag v2.2.0 → unitsdb-ruby 2.2.13 (UNITS_DATA_VERSION = "2.2.0") → unitsml-ruby payload regeneration → unitsdb-ts rebuild → unitsdb@0.1.2 on npm, where getById("cur:EUR") returns the Euro with ISO numeric 978, the joule carries its primary reference NISTq17 (energy), and 6 quantities carry the energy equivalence class.
9 Conformance
This part is enforced by the register procedures themselves; it introduces no vectors. Conformance classes are defined in CalConnect 36819 and referenced from every other part’s conformance clause. The informative annexes map the series (Annex A) and provide additional test-suite examples (Annex B).
Annex A
(normative)
Annex A (informative): series map
The series is consumed as mapped in Table A.1.
| Part | Title | Consumes |
|---|---|---|
| 2 | Numeric and serialization contract | 1 |
| 3 | UnitsDB: the register | 1, 2 |
| 4 | The units model | 3, 2 |
| 5 | Conversions | 3, 4, 2 |
| 6 | asciiunits content language | 3, 1 |
| 7 | UnitsML XML usage | 3, 4, 5 |
| 8 | Conformance | 1, 2 and all tested parts |
The companion Plurimath series (math model, format interfaces, uncertainty representation, evaluation) references this series at exactly three seams: the unit-expression content language (Part 6), the units semantics (Parts 4 and 5), and the conformance corpora (Part 8).
Annex B
(normative)
Annex B (informative): additional test-suite examples
EXAMPLE 1
Release-chain integrity. After the worked release of Clause 8, a consumer pinning unitsdb@0.1.2 observes: 178 currencies; getById("cur:EUR") → Euro (ISO numeric 978); the joule’s quantity_references containing exactly one primary: true entry, NISTq17 (energy); and 6 quantities carrying equivalence_class: "energy".
EXAMPLE 2
Checksum failure. Modifying one byte of artifacts/unitsml.json without regenerating checksums aborts the load with the typed checksum error in every runtime.
EXAMPLE 3
Amendment trace. A reader of Published CalConnect 36814 following an amendment finds the Amendment entry referenced from the part’s revision history; an unamended content change between releases is a register defect.
Bibliography
[1] unitsml/unitsml-ruby#95, UnitsML program master graph — https://github.com/unitsml/unitsml-ruby/issues/95
[2] Pendrill 2024, L. R. Pendrill, Quantities and units: order amongst complexity, De Gruyter
[3] unitsml/docs PR #9, UnitsML XML Schema specification (generated from XSD; house document pattern)