A unit conversion error inside a demo tool is an annoyance. The same error inside a clinical decision path is a patient-safety event. UCUM is the vocabulary that lets converters avoid the class of errors that show up as "why is the alerting firing on normal glucose" or "why is the report reading potassium as though it were sodium." The site's Clinical UCUM unit converter is where the daily conversions happen. For the wider FHIR framing, more resources for healthcare teams has more.
The Categories Of Error
- Wrong base unit — kg vs g, mL vs L
- Wrong prefix — mg vs ug
- Wrong concentration type — mg/dL vs mmol/L for the wrong analyte
- Wrong temperature convention — Celsius vs Fahrenheit
- Wrong compound — mm[Hg] vs cm[H2O]
- Wrong direction — inverted quotient
- Missing conversion — assumed identity
Each has a signature. Each has a downstream cost. Naming them explicitly helps every team spot them in code review.
The Mass Concentration Trap
mg/dL to mmol/L conversion is analyte-specific. For glucose, divide by 18. For cholesterol, divide by 38.7. For urea, divide by 6. For calcium, divide by 4.
A converter that uses a single divisor for all mass-concentration inputs produces wrong values with valid-looking UCUM codes. The values pass structural validation. The clinician reads a number that is off by a factor.
For the basics behind this, UCUM basics for developers who thought units were simple covers the ground.
The Temperature Confusion
Cel and [degF] require an affine conversion — subtract 32, multiply by 5/9. It is not linear. Converters that treat all unit conversions as multiplication produce spectacular errors on temperature.
Kelvin is linear from Celsius (Cel + 273.15). Kelvin is also linear from Fahrenheit (via an intermediate step). Every temperature converter has to know the affine parts.
The Compound Pressure Case
mm[Hg] and cm[H2O] differ by roughly 13.6× (the density ratio). A blood-pressure converter that treats them as interchangeable produces respiratory-pressure-scale numbers where clinicians expect BP-scale numbers.
The right pattern: separate the two compounds. Do not merge into a generic "millimeters of column" converter.
The Inverted-Quotient Case
mL/kg/h is a rate — volume per body weight per unit time. Inverting the quotient (accidentally computing kg·h/mL) produces a number with the same units but no clinical meaning. Downstream systems that reason on the number are lost.
The compiler will not catch this. Only tests will. For the pattern, testing UCUM conversion against clinical fixtures is the entry.
The Silent Fallback
Some converters treat unknown units as "identity" — pass the value through unchanged with the original unit. That produces payloads where the value is un-converted but the code claims the target unit.
Never fall back to identity. Fail explicitly on unrecognised UCUM codes.
Testing Against Reference Values
Every clinical converter should have a fixture set:
- Known input values with known outputs per analyte
- Boundary cases at the limit of the clinical range
- Analytes where the conversion is non-linear
- Edge case UCUM codes with annotations
For the pattern, testing UCUM conversion against clinical fixtures covers it.
Documenting The Analyte Assumption
Converters that assume a specific analyte should surface that in their outputs. mg/dL → mmol/L (for glucose, molecular weight 180) is honest. mg/dL → mmol/L alone is silently wrong for anything not glucose.
For the canonical set, canonical UCUM units the FHIR spec assumes you'll use covers the FHIR contract.
The Short Version
Wrong analyte, wrong compound, wrong direction, wrong prefix, silent fallback. Every category is preventable with test fixtures and explicit failure on unknowns. For the base pattern, UCUM basics for developers who thought units were simple is the entry.
Sources
- UCUM canonical specification with conversion tables - UCUM canonical specification with conversion tables
