FHIR ConceptMap: The Right Way to Handle Cross-Terminology Mapping

FHIR ConceptMap is the resource for representing cross-terminology mappings. Understanding when and how to use it prevents the common mistake of embedding mappings in application code.

When to use ConceptMap

1. ICD-10 to SNOMED CT. Billing to clinical translation. 2. RxNorm to NDC. Prescribed drug to dispensed product. 3. LOINC to SNOMED CT. Lab observation cross-mapping. 4. Local codes to standard codes. Site-specific to standardized. 5. Custom cross-domain. Any translation from one CodeSystem to another.

When NOT to use ConceptMap

1. Simple display translation ($lookup is better). 2. Hierarchy queries ($subsumes is better). 3. Value normalization within one CodeSystem ($expand is better).

ConceptMap structure

`` ConceptMap: url: canonical URL version: version sourceUri: source CodeSystem targetUri: target CodeSystem group[]: element[]: code: source code target[]: code: target code equivalence: equivalent | wider | narrower | inexact comment: explanation ``

Equivalence semantics

1. equivalent — semantic equivalence. 2. wider — target is more general than source. 3. narrower — target is more specific than source. 4. inexact — approximate mapping, not equivalent.

Analytics that treat all mappings as equivalent produce wrong counts. Filter by equivalence for accurate results.

$translate operation

Invoke via POST /ConceptMap/{id}/$translate?code=X&system=Y. Returns Parameters with match[] array containing target Codings + equivalence.

Common ConceptMap mistakes

1. Unversioned CodeSystem references → drift. 2. Missing equivalence values → analytics wrong. 3. Manual translation in code → drift. 4. One-to-one assumption where mappings are one-to-many. 5. No ConceptMap for local codes → cross-mapping broken.

Vendor state (mid-2026)

FHIR ConceptMap is the right primitive for cross-terminology mapping. Use it consistently and cross-domain translation stays reliable.