ConceptMap — Mapping between terminologies
The bridge between two code worlds. ICD-10 to SNOMED CT, LOINC to CPT, RxNorm to ATC, NDC to EAN: ConceptMap is the translation table.
Purpose of the resource
ConceptMap is the mapping table between two code reference systems: two CodeSystems, two ValueSets, or combinations. It is used to translate a code from system A to its equivalent (or its closest equivalent) in system B.
Terminology servers (Snowstorm, HAPI Terminology, Ontoserver, Fhir-Term) typically expose the
$translate operation backed by a ConceptMap.
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
url | uri | 0..1 | Canonical URL. |
identifier | Identifier[] | 0..* | Business identifiers. |
version | string | 0..1 | Version. |
name | string | 0..1 | Technical name. |
title | string | 0..1 | Human-readable title. |
status | code | 1..1 | draft | active | retired | unknown. |
sourceScopeUri | sourceScopeCanonical | uri | canonical | 0..1 | Mapping source (ValueSet, CodeSystem). |
targetScopeUri | targetScopeCanonical | uri | canonical | 0..1 | Mapping target. |
group | BackboneElement[] | 0..* | Mapping groups (per source/target pair). |
group.element | BackboneElement[] | 0..* | Mapping source (code + target). |
group.element.target | BackboneElement[] | 0..* | Target with relationship (equivalent | source-is-narrower-than-target | source-is-broader-than-target | related-to | not-related-to). |
group.unmapped | BackboneElement | 0..1 | Strategy for unmapped codes (fixed, other-map). |
property | BackboneElement[] | 0..* | Ad-hoc properties. |
JSON example
{
"resourceType": "ConceptMap",
"id": "icd10-to-snomedct",
"url": "http://example.org/ConceptMap/icd10-to-snomedct",
"version": "5.0.0",
"name": "Icd10ToSnomedCT",
"title": "ICD-10 to SNOMED CT mapping",
"status": "active",
"experimental": false,
"date": "2026-05-15",
"publisher": "HL7 International (Terminology Authority)",
"sourceScopeUri": "http://hl7.org/fhir/ValueSet/icd-10",
"targetScopeUri": "http://hl7.org/fhir/ValueSet/snomedct-all",
"group": [{
"source": "http://hl7.org/fhir/sid/icd-10",
"target": "http://snomed.info/sct",
"element": [{
"code": "I48.0",
"display": "Paroxysmal atrial fibrillation",
"target": [{
"code": "440059007",
"display": "Paroxysmal atrial fibrillation",
"relationship": "equivalent"
}]
}]
}]
}$translate operation
GET /ConceptMap/$translate?url=…&system=…&code=…- Returns a
Parameterswith the list of matches and theirrelationship. - Also lets you qualify the context:
targetSystem,reverse.
Common pitfalls
- Missing relationship — by default, many tools interpret it as equivalent, which is wrong.
- Unidirectional mapping — an ICD-10 → SNOMED CT mapping is NOT the inverse of SNOMED CT → ICD-10.
- Missing unmapped — how should the consumer behave when faced with an unknown source code?