Every developer who has stored a Weight in kilograms and shipped it downstream thinks units are simple. UCUM is the vocabulary that reveals they are not. Milliliters vs milligrams, degrees Celsius vs Fahrenheit, mmol/L vs mg/dL — same numeric value, different clinical meaning, and unit-safe conversion is the mechanism that keeps the two apart. The site's Clinical UCUM unit converter handles most of the daily conversions. For the wider setting, more FHIR healthcare guides has more.

What UCUM Actually Is

UCUM — Unified Code for Units of Measure — is a formal grammar for expressing units as codes. kg is kilograms. mg/dL is milligrams per deciliter. mmol/L is millimoles per liter. Every code is deterministic: no ambiguity between authors, no locale-specific variation, no free-text drift.

Every FHIR Quantity carries a UCUM code in system = http://unitsofmeasure.org and a code string. That is the compact, machine-readable form.

The Grammar

UCUM units compose from:

• Base units — m (meter), g (gram), s (second), mol (mole), K (kelvin)
• Prefixes — k (kilo), m (milli), u (micro), c (centi), d (deci)
• Operators — . (multiply), / (divide), digit exponents

kg is k + g. mg/dL is m + g divided by d + L. mmol/L is m + mol divided by L. The grammar is small and composable.

The Common Mistakes

• mg and mg/dL are different — one is a mass, one is a mass concentration
• ml is wrong — UCUM is case-sensitive; mL is the milliliter
• cc is not a UCUM unit — use mL
• mm[H2O] and mmHg are different — column pressure of water vs mercury
• degC is not a canonical unit — UCUM uses Cel for Celsius

Every one of these is a place where a well-intentioned developer sends a wrong-but-close unit and downstream logic quietly misinterprets it.

FHIR Expects Canonical UCUM

Every Observation.valueQuantity should use a UCUM code. Every reference range should too. Not every server enforces it, but the interoperability contract assumes it. For the specific mechanic, UCUM in Observation.valueQuantity: the strict version covers the strict form.

Prefixes Are Where People Get Bitten

m alone is meter. mg is milligram. mmol is millimole. Prefix precedence matters — mm is millimeter, not mega·meter, because UCUM chooses the longest matching prefix. That is subtle and common to miss.

For the deeper coverage, prefix and exponent handling that's easy to miss is the entry.

Conversions Have To Be Type-Safe

Converting mg/dL to mmol/L for glucose is not the same conversion as for calcium. The molecular weight enters the calculation. Every conversion between mass concentration and molar concentration is analyte-specific, and confusing them produces wrong values with valid-looking units.

The converter at /workshop/convert-clinical-units/ handles the analyte-specific paths for common lab tests.

The FHIR Contract

A FHIR Quantity has:

• value — the numeric magnitude
• system — http://unitsofmeasure.org for UCUM
• code — the UCUM code string
• Optional unit — human-readable display

Downstream systems dispatch on system + code. unit is for humans only. For the canonical set of codes FHIR most commonly assumes, canonical UCUM units the FHIR spec assumes you'll use enumerates them.

The Short Version

UCUM is a small, composable grammar for unambiguous units. Case-sensitive. Prefixes matter. Conversions between concentration types are analyte-specific. The FHIR contract is system + code. Use the converter for daily work; understand the basics for design.

Sources

• UCUM canonical specification hosted by Regenstrief - UCUM canonical specification hosted by Regenstrief, evergreen reference