ObservationDefinition — detail: observation catalogue

Editorial catalogue of assays a lab offers: LOINC codes, UCUM units, reference ranges. Any produced Observation references its ObservationDefinition.

Role in a lab assay catalogue

A lab publishes its assay catalogue as N ObservationDefinitions. Each ServiceRequest (assay order) references an ObservationDefinition. Each produced Observation implicitly inherits the rules: LOINC code, unit, reference ranges.

Key fields

• code — assay LOINC code.
• permittedDataType — Quantity | CodeableConcept | string | boolean | integer | Range | Ratio | SampledData | time | dateTime | Period.
• permittedUnit — allowed UCUM units.
• category — laboratory, vital-signs, imaging, social-history, ...
• preferredReportName — short display name.
• qualifiedValue — ranges qualified by context (age, sex, condition).
• specimen — required SpecimenDefinition(s).
• device — DeviceDefinition used.

qualifiedValue — context-aware ranges

Where a simple referenceRange does not distinguish contexts (male vs female, adult vs child), qualifiedValue introduces a context qualifying each range:

• range — numeric range.
• interpretation — interpretation code (N, H, L, A).
• condition — clinical phase (pregnancy trim 1, post-stroke ...).
• appliesTo — qualified population (CodeableConcept).
• gender, age, gestationalAge — standard discriminants.

Example: blood HbA1c

{
  "resourceType": "ObservationDefinition",
  "id": "od-hba1c",
  "url": "http://example.org/fhir/ObservationDefinition/HbA1c",
  "version": "1.0.0",
  "status": "active",
  "code": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "4548-4",
      "display": "Hemoglobin A1c/Hemoglobin.total in Blood"
    }]
  },
  "permittedDataType": ["Quantity"],
  "preferredReportName": "HbA1c",
  "category": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/observation-category",
      "code": "laboratory"
    }]
  }],
  "permittedUnit": [{
    "system": "http://unitsofmeasure.org",
    "code": "%",
    "display": "percent"
  }, {
    "system": "http://unitsofmeasure.org",
    "code": "mmol/mol"
  }],
  "qualifiedValue": [{
    "context": { "text": "Non-diabetic adult" },
    "range": {
      "low": { "value": 4.0, "unit": "%" },
      "high": { "value": 5.6, "unit": "%" }
    },
    "interpretation": [{
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
        "code": "N",
        "display": "Normal"
      }]
    }]
  }, {
    "context": { "text": "Diabetic adult - target" },
    "range": {
      "high": { "value": 7.0, "unit": "%" }
    },
    "interpretation": [{
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
        "code": "H",
        "display": "High"
      }]
    }]
  }]
}

Common pitfalls

• Non-UCUM unit — avoid mg/dL as free string; use mg/dL with system=http://unitsofmeasure.org.
• qualifiedValue without context — prevents automatic discrimination of ranges.
• Missing permittedDataType — the Observation can be validated with any value[x], a source of silent errors.

Related resources

• ObservationDefinition — overview
• Observation
• SpecimenDefinition
• ServiceRequest