How UnitsML Works

UnitsML is a set of models for encoding scientific units of measure. It provides the semantic meaning of units — what a unit represents, how it relates to other units, what quantities it measures, and how to convert between them. This page explains how the pieces fit together.

The three-layer architecture

UnitsML operates across three layers:

Layer 1: The UnitsML data model

UnitsML defines five core element types, each wrapped in a corresponding Set container. The containers are modular — use one or combine several.

Unit (UnitSet / Unit)

The central element. A Unit defines a measurement unit with its name, symbols, system membership, dimensional reference, and optional conversion information.

<UnitSet>
  <Unit xml:id="m" dimensionURL="#dim_L">
    <UnitSystem>
      <SystemName>SI</SystemName>
      <SystemDescription>SI_base</SystemDescription>
    </UnitSystem>
    <UnitName>metre</UnitName>
    <UnitSymbol typeface="ASCII">m</UnitSymbol>
    <UnitSymbol typeface="HTML">m</UnitSymbol>
  </Unit>
</UnitSet>

Key attributes:

Quantity (QuantitySet / Quantity)

A Quantity is a measurable property — length, mass, force, energy, etc. Quantities link abstract concepts to the specific units that can express them. Each quantity is typed as either base or derived and references a dimension.

<QuantitySet>
  <Quantity xml:id="q_force" quantityType="derived">
    <QuantityName>force</QuantityName>
    <QuantitySymbol typeface="ASCII">F</QuantitySymbol>
    <UnitReference unitURL="#N" unitName="newton"/>
  </Quantity>
</QuantitySet>

A single unit can measure multiple quantities. For example, the metre measures length, wavelength, distance, focal length, and many others. When using UnitsML, you can tag which quantity you intend, disambiguating the unit’s role:

<Value unitURL="#m" quantityURL="#q_length">1.83</Value>
<Value unitURL="#m" quantityURL="#q_wavelength">550</Value>

Dimension (DimensionSet / Dimension)

Dimensions express any unit or quantity in terms of the seven SI base quantities:

A dimension definition specifies which base quantities participate and at what power:

<Dimension xml:id="dim_LMT-2">
  <Length symbol="L" powerNumerator="1"/>
  <Mass symbol="M" powerNumerator="1"/>
  <Time symbol="T" powerNumerator="-2"/>
</Dimension>

This represents the dimension of force: L·M·T⁻². Any unit with this dimension (newton, dyne, pound-force) can be converted between them, because they share the same dimensional structure.

The dimensionless attribute marks entities that have no dimension (e.g., refractive index, strain, mach number).

Prefix (PrefixSet / Prefix)

Prefixes define decimal and binary scaling factors. UnitsML supports all 20 SI decimal prefixes defined in the BIPM SI Brochure, plus 7 binary prefixes:

<PrefixSet>
  <Prefix xml:id="p10_3">
    <PrefixName>kilo</PrefixName>
    <PrefixSymbol typeface="ASCII">k</PrefixSymbol>
    <PrefixBase>10</PrefixBase>
    <PrefixPower>3</PrefixPower>
  </Prefix>
</PrefixSet>

Binary prefixes (Ki, Mi, Gi, Ti, Pi, Ei, Zi, Yi) follow the same pattern with base 2.

CountedItem (CountedItemSet / CountedItem)

Counted items represent things that are counted and combined with scientific units — distinct from physical quantities. They support expressions like “electrons per second” or “particles per cubic meter”:

<CountedItemSet>
  <CountedItem xml:id="electron">
    <ItemName>electron</ItemName>
    <ItemSymbol typeface="ASCII">e⁻</ItemSymbol>
  </CountedItem>
</CountedItemSet>

Layer 2: UnitsDB — the pre-built database

While the UnitsML data model tells you how to define a unit, UnitsDB provides a ready-made collection of commonly used definitions. Instead of defining every unit from scratch, you reference entries from UnitsDB.

What UnitsDB contains

Browse all entries interactively at the UnitsDB browser.

How to reference a UnitsDB entry

In your UnitsML document, reference a UnitsDB unit by its identifier:

<Unit xml:id="m" dimensionURL="#dim_L">
  <UnitName>metre</UnitName>
  <UnitSymbol typeface="ASCII">m</UnitSymbol>
</Unit>

In UnitsDB, the metre is identified by both a NIST ID (NISTu1) and an organization-neutral UnitsML ID (u:meter). The YAML entry looks like:

identifiers:
  - type: nist
    id: NISTu1
  - type: unitsml
    id: u:meter
names:
  - value: metre
    lang: en
  - value: mètre
    lang: fr
symbols:
  - ascii: m
    unicode: m
    html: m
    latex: "\\ensuremath{\\mathrm{m}}"
    mathml: "<mi mathvariant='normal'>m</mi>"

External dataset linkage

UnitsDB entries include cross-references to major external datasets, providing interoperability with other unit systems:

For example, the metre entry links to BIPM, IEC CDD, UCUM, and QUDT:

references:
  - type: normative
    authority: si-digital-framework
    uri: http://si-digital-framework.org/SI/units/metre
  - type: normative
    authority: iec-cdd
    uri: http://cdd.iec.ch/cdd/iec62720/iec62720.nsf/UAA176
  - type: informative
    authority: ucum
    uri: ucum:base-unit:code:m
  - type: informative
    authority: qudt
    uri: http://qudt.org/vocab/unit/M

These cross-references allow applications to bridge between UnitsML and other unit systems automatically.

Multilingual names

UnitsDB 2.0 introduced multilingual support. Units and quantities carry names in multiple languages, sourced from the BIPM SI Digital Reference:

names:
  - value: length
    lang: en
  - value: longueur
    lang: fr

Building custom units

Not every unit is in UnitsDB. UnitsML provides mechanisms to construct custom units from existing definitions.

Adding prefixes

Apply an SI prefix to any base or derived unit:

<Unit xml:id="km" dimensionURL="#dim_L">
  <UnitName>kilometer</UnitName>
  <UnitSymbol typeface="ASCII">km</UnitSymbol>
  <RootUnits>
    <EnumeratedRootUnit unit="meter" prefix="k" powerNumerator="1"/>
  </RootUnits>
</Unit>

Changing powers

Express squared, cubed, or inverse units by setting the powerNumerator:

<!-- Square meter: m² -->
<EnumeratedRootUnit unit="meter" powerNumerator="2"/>

<!-- Per second: s⁻¹ -->
<EnumeratedRootUnit unit="second" powerNumerator="-1"/>

<!-- Square root of meter: m^(1/2) -->
<EnumeratedRootUnit unit="meter" powerNumerator="1" powerDenominator="2"/>

Composite units

Most scientific units are composites — products of base units raised to powers. The RootUnits element decomposes any derived unit:

<Unit xml:id="N" dimensionURL="#dim_LMT-2">
  <UnitName>newton</UnitName>
  <UnitSymbol typeface="ASCII">N</UnitSymbol>
  <RootUnits>
    <EnumeratedRootUnit unit="meter" powerNumerator="1"/>
    <EnumeratedRootUnit unit="gram" prefix="k" powerNumerator="1"/>
    <EnumeratedRootUnit unit="second" powerNumerator="-2"/>
  </RootUnits>
</Unit>

For units not in the built-in enumeration, ExternalRootUnit allows referencing any unit by URI.

Custom units not in UnitsDB

Define entirely custom units with their own names, symbols, and dimensions:

<Unit xml:id="custom_flux" dimensionURL="#dim_L-2T-1">
  <UnitName>custom flux unit</UnitName>
  <UnitSymbol typeface="ASCII">cfu</UnitSymbol>
  <RootUnits>
    <EnumeratedRootUnit unit="meter" powerNumerator="-2"/>
    <EnumeratedRootUnit unit="second" powerNumerator="-1"/>
  </RootUnits>
</Unit>

Tagging quantities

A single unit can describe multiple quantities. For example, the second measures both time and period. Use the quantityURL attribute to tag which quantity you intend:

<Period unitURL="#s" quantityURL="#q_time">2.5</Period>
<Frequency unitURL="#Hz" quantityURL="#q_frequency">0.4</Frequency>

This disambiguation is essential because some units share dimensions but represent different quantities — hertz and becquerel both decompose to s⁻¹, but one measures frequency while the other measures radioactive activity.

Conversion rules

UnitsML provides three types of unit conversions:

Linear conversions

Most unit conversions follow the linear equation: y = d + ((b / c) × (x + a))

Simple scaling (m → km):

<Float64ConversionFrom xml:id="conv_m_to_km"
  initialUnit="#m"
  multiplicand="0.001"
  exact="true"/>

Temperature offset (°C → K):

<Float64ConversionFrom xml:id="conv_C_to_K"
  initialUnit="#degC"
  multiplicand="1"
  finalAddend="273.15"
  exact="true"/>

Special conversions

For non-linear conversions:

<SpecialConversionFrom xml:id="conv_pH"
  initialUnit="#pH"
  conversionURL="https://example.org/conversions/pH">
  <ConversionDescription>
    pH is the negative logarithm of hydrogen ion activity.
  </ConversionDescription>
</SpecialConversionFrom>

WSDL conversions

For conversions provided by remote services:

<WSDLConversionFrom xml:id="conv_remote"
  initialUnit="#custom_unit"
  wsdlURL="https://example.org/conversions/service.wsdl"/>

Layer 3: Integration with XML and MathML

UnitsML provides semantic meaning — what a unit is, what it measures, how it converts. But to display a unit symbol in a document, you need presentation markup. This is where MathML comes in.

How UnitsML and MathML work together

UnitsML and MathML serve complementary roles:

• UnitsML — defines the unit’s identity, dimension, system, conversions (the “what”)
• MathML — renders the unit’s symbol visually in a document (the “how”)

When you use UnitsML inside an XML document, the unit symbols can be expressed as MathML elements. The UnitsML schema’s UnitSymbol element supports MathML typeface, and UnitsDB stores MathML representations for every symbol:

symbols:
  - mathml: "<mi mathvariant='normal'>m</mi>"    # metre
  - mathml: "<mi mathvariant='normal'>kg</mi>"   # kilogram
  - mathml: "<mi mathvariant='normal'>N</mi>"    # newton

Practical example: PluXML + MathML

In practice, when a document contains a quantity value, UnitsML identifies the unit and MathML renders it:

<Measurement>
  <Value>9.81</Value>
  <unitsml:Unit xml:id="m_s2" dimensionURL="#dim_LT-2">
    <unitsml:UnitName>metre per second squared</unitsml:UnitName>
    <unitsml:UnitSymbol typeface="MathML">
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <mrow>
          <mi mathvariant="normal">m</mi>
          <mo>·</mo>
          <msup>
            <mi mathvariant="normal">s</mi>
            <mn>-2</mn>
          </msup>
        </mrow>
      </math>
    </unitsml:UnitSymbol>
  </unitsml:Unit>
</Measurement>

Programmatic generation with unitsml-ruby

The unitsml-ruby library parses unit expressions (like m*s^-2 or kg*m^2/s^3/A) and automatically generates:

• MathML — rendering markup for the unit symbol
• LaTeX — for scientific documents
• Unicode / HTML — for plain text and web display
• UnitsML XML — the semantic definition with dimension references

# Parse a unit expression and generate MathML
formula = Unitsml.parse("kg*m^2*s^-3*A^-1")
mathml = formula.to_mathml
# Produces MathML for the volt: kg·m²·s⁻³·A⁻¹

The library resolves each component against UnitsDB to look up the correct symbol in each representation format, applies prefix and power transformations, and produces properly structured output.

Six-format symbol coverage

UnitsDB stores symbols in six representation formats, enabling integration with any display technology:

Putting it all together

A complete UnitsML document combines the data model, UnitsDB references, and presentation:

<UnitsML xmlns="https://schema.unitsml.org/unitsml/1.0">
  <UnitSet>
    <Unit xml:id="m" dimensionURL="#dim_L">
      <UnitName>metre</UnitName>
      <UnitSymbol typeface="ASCII">m</UnitSymbol>
    </Unit>
    <Unit xml:id="N" dimensionURL="#dim_LMT-2">
      <UnitName>newton</UnitName>
      <UnitSymbol typeface="ASCII">N</UnitSymbol>
      <RootUnits>
        <EnumeratedRootUnit unit="meter" powerNumerator="1"/>
        <EnumeratedRootUnit unit="gram" prefix="k" powerNumerator="1"/>
        <EnumeratedRootUnit unit="second" powerNumerator="-2"/>
      </RootUnits>
      <Conversions>
        <Float64ConversionFrom xml:id="conv_lbf_to_N"
          initialUnit="#lbf"
          multiplicand="4.4482216152605"
          exact="true"/>
      </Conversions>
    </Unit>
  </UnitSet>
  <QuantitySet>
    <Quantity xml:id="q_force" quantityType="derived">
      <QuantityName>force</QuantityName>
      <UnitReference unitURL="#N" unitName="newton"/>
    </Quantity>
  </QuantitySet>
  <DimensionSet>
    <Dimension xml:id="dim_L">
      <Length symbol="L" powerNumerator="1"/>
    </Dimension>
    <Dimension xml:id="dim_LMT-2">
      <Length symbol="L" powerNumerator="1"/>
      <Mass symbol="M" powerNumerator="1"/>
      <Time symbol="T" powerNumerator="-2"/>
    </Dimension>
  </DimensionSet>
</UnitsML>

Schema location

The UnitsML 1.0 schema uses the following namespace:

• Namespace: https://schema.unitsml.org/unitsml/1.0
• Schema file: https://schema.unitsml.org/unitsml/unitsml-v1.0.xsd
• Interactive docs: schema.unitsml.org

Next steps

• Incorporating UnitsML — how to add UnitsML to your markup languages
• UnitsML Guide — comprehensive usage guide with examples
• UnitsDB — browse the complete interactive database
• Get started — practical quick-start instructions
• Schemas — UnitsML XML Schemas and UnitsDB YAML Schemas