FHIR `$lookup`: Terminology Operation Patterns That Work

The FHIR `$lookup` operation returns metadata about a coded value — display name, definition, properties, designations. Four patterns cover most production use cases.

Pattern 1: Display name resolution on read. When a client reads a Coding element (e.g., Observation.code), the code is present but display might be stale or missing. Client calls $lookup to get authoritative display. Best for user-facing rendering.

Pattern 2: Property fetching for reasoning. SNOMED CT concepts have properties (ismap, hierarchy). $lookup?property=parent,definition returns them. Best for clinical decision support that needs to reason about codes.

Pattern 3: Multi-language designation. Concepts have translated designations (English, Spanish, French). $lookup?displayLanguage=es returns Spanish. Best for multi-language patient-facing displays.

Pattern 4: Batch lookup via Bundle. For high-volume rendering, bundle multiple $lookup operations into one HTTP call. Reduces round-trip overhead.

Performance considerations

$lookup on individual codes is fast (typically <20ms). Batch lookups for hundreds of codes per view should cache aggressively — most codes are stable across sessions.

Caching strategy

Where $lookup breaks

1. Missing code system version. Terminology server without pinned version returns latest, may differ from what was written. 2. Multi-server terminology fragmentation. Different servers with different loaded versions produce different lookups. 3. RxNorm licensing. UMLS license gates access; expired licenses cause 401.

Vendor state (mid-2026)

$lookup is one of the most under-used terminology operations. Wire it into rendering pipelines rather than embedding display strings in application code.