API Reference

Biomarkers

What is a Biomarker?

A biomarker is a measurable biological indicator (e.g., glucose, cholesterol, sodium, hemoglobin) that provides information about a person’s health state.
Biomarkers are used in laboratory tests, wearable device data, and clinical reports.

For example, a complete blood count consists of several biomarkers.

Currently, there are more than 5000 biomarkers in Ornament’s database.
We are constantly expanding our information, but it is still incomplete. Ornament will not include any biomarker values given in units of measurement not present in the app. Typos or other mistakes in biomarker names may also cause them to not upload correctly. If a biomarker is later added to the database, you can manually update your previous results to include it.

If any biomarkers from an uploaded report are missing, the rest of the test will still be digitized.
You can also request new biomarkers to be added.

Structure of a Biomarker in Ornament

Each biomarker in Ornament includes several key characteristics:

• Name and Synonyms

A biomarker has a main title (e.g., “Anion Gap”) and can have synonyms or translations in different languages.

• Biomaterial

Defines the sample type (serum, blood, urine, etc.). This ensures values are not confused across different sample sources.
For example:

“Glucose in serum” and “Glucose in blood” are treated as different biomarkers in the system.

• Measurement Units

Biomarkers can be measured in different units depending on their type (e.g., glucose in mg/dL or mmol/L).
Some are unitless (e.g., Body Mass Index, ratios, scores), and some are binary (e.g., Positive / Negative).

Many units include alternate spellings or symbols
(e.g., µg = mcg = ug, µL = uL = mcL, mM = mmol/L).
Ornament normalizes these via a synonyms list so inputs from various labs are parsed consistently.

• Possible Value Range

Most biomarkers have realistic minimum and maximum values. These ranges help filter out input errors (e.g., mistyped lab results).

• References

Biomarkers often include reference ranges for interpreting results:

  • Common range - values expected for most healthy individuals.
  • Optimal range - narrower, sometimes recommended for specific populations.

• Recorded Values (Entries)

Each record (entry) typically contains:

  • The measured value (normalized into the default unit).
  • The original value and unit as it appeared in the lab result.
  • The date of the measurement.

Measurement Units in Ornament

Laboratory biomarkers can be reported in different measurement units depending on the type of measurement used by the laboratory.

For example, glucose units can be presented in:

  • Mass concentration - weight of a substance per volume
    Examples: mg/dL, g/L, µg/mL

  • Molar concentration - number of molecules per volume, based on molecular weight
    Examples: mmol/L, µmol/L

  • Activity units - used for enzymes, reflecting catalytic activity
    Examples: U/L, IU/mL

1. Measurement Trees (Unit Families)

Biomarker units are organized into measurement trees - groups of units belonging to the same physical dimension.
A biomarker may support one or more unit families, such as:

Mass concentration (mass / volume)

Examples:

  • mg/dL
  • g/L
  • µg/mL

Molar concentration (amount of substance / volume)

Examples:

  • mmol/L
  • µmol/L

Enzymatic activity

Examples:

  • U/L
  • IU/mL

Ratios or percentages

Examples:

  • %
  • fractions

Unitless values

Examples:

  • pH
  • indexes, ratios, scores

Each biomarker’s unit families define a unit tree, describing which units are compatible with each other.

2. Conversion Rules

2.1 Conversions within the same branch

Units inside one tree branch differ only by decimal scaling.

Examples:

  • mg/dL ↔ g/L ↔ µg/mL
  • mmol/L ↔ µmol/L

These conversions do not require biomarker-specific information.

2.2 Conversions across branches

Switching between mass-based and molar-based units requires biomarker-specific conversion factors, typically based on molecular weight.

Examples:

  • mg/dL ↔ mmol/L
  • µg/mL ↔ µmol/L
  • General conversion formula: molar_value = mass_value / molecular_weight
  • Example (Glucose):
    • Molecular weight = 180 g/mol
    • Conversion formula: mmol/L = (mg/dL × 10) / 180
    • Example result: 90 mg/dL → 5.0 mmol/L
  • Because each biomarker has its own molecular weight (or activity definition), each biomarker uses a unique conversion factor.
  • Default units in Ornament: each biomarker has one canonical default unit selected according to clinical standards.
  • Examples of default units: Glucose → mmol/L, Cholesterol → mmol/L, Creatinine → µmol/L, Sodium → mmol/L.
  • Why default units are used: they ensure value consistency across data sources, avoid ambiguity during normalization.
  • When receiving data: the client sends a value and a unit; Ornament identifies the unit branch, applies decimal scaling or a biomarker-specific conversion factor, and stores the value internally in the default unit.
  • When returning data: the API returns biomarker values in the default unit and also includes the original value and unit as they appeared in the source (e.g., the lab report).
  • Unit definitions in the API: each biomarker exposes supported unit IDs together with their conversion factors. Here is an example of measurement unit conversion using the Ornament API. .
  • Conversion rule used in practice: Converted Value = Default Value / UnitFactor.
  • This rule applies to: biomarker values, reference ranges, and display-unit conversions.
  • Important: all reference ranges are defined in the default unit and follow the same conversion logic as biomarker values.