Draft Standard

Ribose Standard

•
36818(d) (draft 2026-11-01)
UnitsML specifications — Xml Usage
CalConnect
Ribose Standard

Draft Standard

Warning for Drafts

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.

© Ribose Asia Limited 2026

Ribose Asia Limited

Suite 1, 8/F, New Henry House
10 Ice House Street
Central
Hong Kong

copyright@ribose.com
www.ribose.com

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.





Foreword

Two documents govern UnitsML XML: the base document — the generated XSD specification (unitsml/docs PR #9), specifying the SYNTAX of unitsml-v1.0.xsd, all 96 schema components, enumerations and examples — and THIS part, specifying the USAGE SEMANTICS: what conforming producers emit, what conforming consumers may infer, and what neither may invent. This part adds no elements and changes no schema; where the series needs what the schema cannot say, the gap is recorded and the path is Annex B.


Introduction

A schema tells you what is well-formed; only a usage contract tells you what is true. The schema permits any QuantityReference order — the register’s primary-reference rule says which one is the truth. The schema permits omitting digit metadata — the usage contract says importing without it loses exactness. This part is those statements, made normative.

1  Scope

This document specifies: the emission contract for the element set; quantity-reference selection; conversion emission; cross-references from MathML; reading rules for foreign payloads; and the uncertainty-representation gap.

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.

generated XSD specification, (base document)

UnitsML 1.0 XSD, (unitsml-v1.0.xsd)

3  Terms and definitions

No terms and definitions are listed in this document.

base document

the generated XSD specification; normative for XML syntax.

emission

the production of UnitsML XML by a conforming producer.

xref

the IDREF bond from a MathML unit symbol to the UnitsML xml:id.

deterministic reading

acceptance behavior for foreign payloads that is fully specified — accept, skip, or fail, never whim.

4  Conventions

Requirement language per CalConnect 36812. XML examples are illustrative; the XSD (base document) governs well-formedness.

5  Emission contract

Producers emit only elements and attributes the XSD defines, targeting the declared schema version. xml:id values are producer-allocated, unique per document, and stable across regenerations of the same input. The emitted element set: Unit (symbols, unitSystem, roots and prefixes, dimensionURL), Prefix, Quantity (names, symbols, quantityType, dimensionURL), Dimension, per-unit QuantityReference (0..*) and Conversions (0..1). SpecialConversionFrom/WSDLConversionFrom are never emitted synthetically.

EXAMPLE

Expected outcome. Regenerating the UnitsML for the same input yields byte-identical XML — same ids, same order, same attribute values. A producer whose regeneration flips element order or mints new ids is non-conforming.

6  QuantityReference selection

QuantityReference is 0..* per unit; a producer never emits positional order. Selection follows the CalConnect 36814 primary-reference rule: the primary: true entry when present; the caller’s asserted kind when one is stated.

EXAMPLE

Expected outcome. A joule emitted against the current register resolves to Quantity id="NISTq17" (energy). A producer emitting NISTq152 (“Lagrange function”) from list position is non-conforming — the red member of the frozen vector pair.

7  Conversions emission

Conversions carries the full affine attribute set of CalConnect 36816 — initialUnit, initialAddend, multiplicand, divisor, finalAddend, exact, digit metadata — with decimal attributes as lexical strings. A producer never emits a conversion whose definition it cannot reproduce; register factors are emitted with their exact strings.

EXAMPLE

Expected outcome. The degree Celsius emission carries finalAddend="273.15" exact="true"; the percent-per-degree emission carries its full declared decimal and no exact attribute.

8  Cross-references from MathML

MathML embeds unit symbols with xref pointing at the UnitsML xml:id; the linkage is the machine-readable bond between presentation and definition (the embedding clauses of the Plurimath input-language parts define the ASCII side).

EXAMPLE

Expected outcome. parse('mg') rendered to MathML emits the milligram symbol with an xref resolving, inside the document, to the milligram Unit element — the reader can walk from presentation to definition without name matching.

9  Reading rules and determinism

Readers tolerate foreign-payload defects deterministically: duplicate lowercase attributes (the openCDD finaladdend beside finalAddend) are accepted with the camel-case value prevailing on read and never reproduced on write; unrecognized elements are skipped, not fatal; recognized names with malformed shapes are fatal.

EXAMPLE

Expected outcome. The known degree-Celsius payload defect (one duplicate attribute) is reported in the coverage report, accepted on read, and absent from every emission this series produces.

10  The uncertainty gap

UnitsML 1.0 has no first-class uncertainty element. Measured values travel in the math layer (Plurimath 2). This part does not invent one; Annex B records the proposal shape for the WG.

11  Conformance

Conformance class parse/render includes this part for emission and reading; conversion round-trips additionally require quantity-conversion. Annex A defines the validation profile; Annex B discusses a measurement-result element; CalConnect 36819 freezes the round-trip vectors.


Annex A
(normative)

Annex A (informative): validation profile

Emitted documents validate against the XSD; every xref resolves; every QuantityReference/Conversions value round-trips through the CalConnect 36816 semantics; document regeneration from the same input is byte-stable.


Annex B
(normative)

Annex B (informative): proposal — a measurement-result element

A sibling of QuantityReference on Quantity-carrying elements, or a child of Unit:

MeasurementResult: category (standard | expanded | coverage-interval),
  value (decimal string), magnitude?, k?, p?, lower?, upper?,
  intervalKind?, distribution? (JCGM 101 family + parameters),
  exact (boolean), digits metadata
Figure B.1

Adoption is a WG decision; until adopted, this series carries uncertainty in the math layer only.


Bibliography

[1]  unitsml/docs PR #9, (base document); unitsml/unitsml-ruby#92; unitsml/unitsdb#139 (reading-rule provenance)