© 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
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.
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.
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.
No terms and definitions are listed in this document.
For the purposes of this document, the following terms and definitions apply.
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.
a versioned collection of test vectors owned by CalConnect 36819. A corpus entry names its normative source clause and the tolerance convention that applies.
an implementation whose output is frozen into a corpus. The reference implementation of the series is the Ruby one; corpora are frozen from it.
a recorded revision of an artifact or register, identified by checksum and version string.
the set of vector classes an implementation replays, licensing specific claims (CalConnect 36819).
the legacy AsciiMath compatibility dialect (Plurimath series, asciimath Part 1); not extended by this series.
the featureful strict input language (Plurimath series, pma Part 1).
NIST Special Publication 811, Guide for the Use of the International System of Units (SI).
JCGM 200, International vocabulary of metrology.
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).
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.
Register documents are classified as in
| 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 |
Idea → Draft (docstage 20) → Committee Draft (30) → Final Draft (50) → Published (60).
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.
Part numbers are permanent and never reused. Informational documents share the numbering space with an explicit type marker.
A Published document changes only by a numbered Amendment; corrections that would alter normative content require an Amendment entry, never silent edits.
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”.
Statements are declarative; requirement strength comes from precision and from the corpus vectors that test them.
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.
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.
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.
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).
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.
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 (
The series is consumed as mapped in
| 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).
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".
Checksum failure. Modifying one byte of artifacts/unitsml.json without regenerating checksums aborts the load with the typed checksum error in every runtime.
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.
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.