Biomarker Reference

Biomarker standardization, UCUM unit codes, and common biomarker reference table.

⚠️ Pre-Release

This page is currently under active development and is provided in a pre-release state.

Some content may evolve as we continue to iterate on the implementation based on your feedback, but the core concepts and functionality are expected to remain consistent.

The page will be marked as general release in the near future

What Is biomarker.key?

Every result extracted from a lab report is matched against Terra's reference dataset of 4,100+ known biomarkers. When a match is found, the result's biomarker.key field is set to a canonical slug — a stable, machine-readable identifier you can use to aggregate and compare results across different labs, reports, and patients.

{
  "source": { "name": "Haemoglobin (Hb)" },
  "biomarker": {
    "key": "hemoglobin_blood",
    "display_name": "Hemoglobin"
  }
}

When Is biomarker.key null?

biomarker.key is always present, and is null when the system cannot confidently match the extracted name to a known biomarker. This happens with:

• Lab-specific proprietary test names

• Uncommon or newly introduced assays

• Ambiguous abbreviations

• Composite panels reported as a single line item

When biomarker.key is null, source.name and biomarker.display_name still contain the text extracted from the report. Use source.name as a fallback for display.

How Matching Works

1. The source.name is extracted from the lab report file via OCR and AI parsing

2. The name is compared against the reference dataset using fuzzy string matching

3. If a high-confidence match is found, the canonical biomarker.key slug, biomarker.display_name, and related metadata are assigned

4. If no confident match is found, biomarker.key is set to null

The matching accounts for common variations:

Report Might Say	Matched To
Haemoglobin (Hb)	hemoglobin_blood
HbA1c	hemoglobin_a1c
25-OH Vitamin D	vitamin_d_25_hydroxy
Thyroid Stimulating Hormone	tsh
TSH	tsh
GFR (estimated)	egfr

UCUM Unit Codes

Terra maps lab units to UCUM (Unified Code for Units of Measure) codes wherever possible. UCUM is the international standard for machine-readable unit representation in healthcare.

Common UCUM Mappings

Report Units	ucum_code	Description
g/dL	g/dL	Grams per deciliter
mg/dL	mg/dL	Milligrams per deciliter
mmol/L	mmol/L	Millimoles per liter
µmol/L	umol/L	Micromoles per liter
ng/mL	ng/mL	Nanograms per milliliter
pg/mL	pg/mL	Picograms per milliliter
mIU/L	m[IU]/L	Milli-international units/liter
IU/L	[IU]/L	International units per liter
10^9/L	10*9/L	Billions per liter
10^12/L	10*12/L	Trillions per liter
%	%	Percent
fL	fL	Femtoliters
mm/hr	mm/h	Millimeters per hour
seconds	s	Seconds

When a UCUM mapping is not possible (e.g., proprietary or ambiguous units), measurement.ucum_code is omitted. The source.units field still shows exactly what the report printed.

LOINC Codes

When a matched biomarker has a corresponding LOINC code, the result includes a biomarker.loinc_code field. LOINC (Logical Observation Identifiers Names and Codes) is the international standard for identifying laboratory observations — useful for interoperability with EHRs and other health systems.

{
  "biomarker": {
    "key": "hemoglobin_blood",
    "display_name": "Hemoglobin",
    "loinc_code": "718-7"
  }
}

biomarker.loinc_code is omitted when the matched biomarker has no LOINC mapping. Coverage is partial — roughly 1,900 of the 4,100+ reference biomarkers currently carry a LOINC code, concentrated on common blood, serum, and urine analytes. Biomarkers without a mapping (many derived ratios, qualitative microbiology results, and specialised assays for which LOINC has no specific term) have no loinc_code.

The loinc_code for each mapped biomarker is also included in the downloadable reference file linked at the bottom of this page.

Measurement Types

Every result carries a single measurement object. Read measurement.type, then read the matching field:

measurement.type	Populated field	Example
numeric	measurement.numeric (number)	Hemoglobin: 14.2 g/dL
bounded	measurement.bounded ({ operator, value })	PSA: <0.04
qualitative	measurement.qualitative ({ text })	HIV screen: Non-Reactive
text	measurement.text (string)	Morphology: Normal appearance
absent	measurement.absent_reason (string)	Value not reported

When the lab reports a bound rather than an exact value, measurement.type is "bounded" and measurement.bounded carries the operator and magnitude:

Report Shows	measurement.type	Populated value
14.2	numeric	measurement.numeric is 14.2
>5.0	bounded	{ "operator": "gt", "value": 5.0 }
<0.01	bounded	{ "operator": "lt", "value": 0.01 }

Common Biomarkers

The table below lists frequently encountered biomarkers. For the complete dataset, download the reference file linked at the bottom of this page.

Complete Blood Count (CBC)

biomarker	Display Name	Typical Units	ucum_code
hemoglobin_blood	Hemoglobin	g/dL	g/dL
hematocrit	Hematocrit	%	%
rbc	Red Blood Cell Count	10^12/L	10*12/L
wbc_blood	White Blood Cell Count	10^9/L	10*9/L
platelet_count	Platelet Count	10^9/L	10*9/L
mcv	MCV	fL	fL
mch	MCH	pg	pg
neutrophils	Neutrophils	10^9/L	10*9/L
lymphocytes	Lymphocytes	10^9/L	10*9/L
monocytes	Monocytes	10^9/L	10*9/L

Metabolic Panel

biomarker	Display Name	Typical Units	ucum_code
glucose_fasting	Fasting Glucose	mg/dL	mg/dL
hemoglobin_a1c	HbA1c	%	%
creatinine_serum	Creatinine	mg/dL	mg/dL
blood_urea_nitrogen_bun	BUN	mg/dL	mg/dL
egfr	eGFR	mL/min/1.73m2	mL/min/{1.73_m2}
sodium_serum	Sodium	mmol/L	mmol/L
potassium_serum	Potassium	mmol/L	mmol/L
calcium_serum	Calcium	mg/dL	mg/dL
uric_acid_serum	Uric Acid	mg/dL	mg/dL

Lipid Panel

biomarker	Display Name	Typical Units	ucum_code
cholesterol	Total Cholesterol	mg/dL	mg/dL
hdl_cholesterol	HDL Cholesterol	mg/dL	mg/dL
ldl_cholesterol	LDL Cholesterol	mg/dL	mg/dL
triglycerides	Triglycerides	mg/dL	mg/dL

Thyroid

biomarker	Display Name	Typical Units	ucum_code
tsh	TSH	mIU/L	m[IU]/L
thyroxine_t4_free	Free T4	ng/dL	ng/dL
triiodothyronine_t3_free	Free T3	pg/mL	pg/mL

Hormones

biomarker	Display Name	Typical Units	ucum_code
testosterone_total	Total Testosterone	ng/dL	ng/dL
testosterone_free	Free Testosterone	pg/mL	pg/mL
estradiol_blood	Estradiol	pg/mL	pg/mL
cortisol	Cortisol	µg/dL	ug/dL
insulin_fasting	Insulin	µIU/mL	u[IU]/mL

Vitamins and Minerals

biomarker	Display Name	Typical Units	ucum_code
vitamin_d_25_hydroxy	Vitamin D	ng/mL	ng/mL
vitamin_b12	Vitamin B12	pg/mL	pg/mL
folate	Folate	ng/mL	ng/mL
ferritin	Ferritin	ng/mL	ng/mL
iron_serum	Iron	µg/dL	ug/dL

Liver

biomarker	Display Name	Typical Units	ucum_code
alt	ALT	IU/L	[IU]/L
ast	AST	IU/L	[IU]/L
ggt	GGT	IU/L	[IU]/L
alp	ALP	IU/L	[IU]/L
bilirubin_total_blood	Total Bilirubin	mg/dL	mg/dL
albumin_serum	Albumin	g/dL	g/dL

Inflammation

biomarker	Display Name	Typical Units	ucum_code
crp	CRP	mg/L	mg/L
c_reactive_protein_high_sensitivity	hs-CRP	mg/L	mg/L
esr	ESR	mm/hr	mm/h

Full Biomarker Reference File

The complete list of all 4,100+ supported biomarkers is available as a downloadable JSON file:

692KB

biomarkers.json

Open

The file contains each biomarker's canonical key, display name, and associated metadata.