ConceptMap — detail: mappings and $translate

Implementer-focused companion page for industrialising terminology mappings: ICD-10 to SNOMED CT, LOINC to pCLOCD, local codes to national references.

group/element/target structure

ConceptMap uses a three-level hierarchy: group (source/target code system pair), element (source code), target (one or more target codes with relationship). A single element can have 0..N target depending on mapping type: strict equivalence (1:1), explosion (1:N), aggregation (N:1).

Equivalence codes (relationship)

R5 renamed equivalence to relationship. Values:

$translate operation

The REST $translate operation applies a ConceptMap to translate a code. Example calls:

• GET /ConceptMap/icd10-to-snomed-diabetes/$translate?system=http://hl7.org/fhir/sid/icd-10&code=E11
• POST /ConceptMap/$translate with a Parameters body containing sourceCoding, targetSystem, reverse.
• GET /ConceptMap/$translate?url=...&system=...&code=... — reference by canonical URL instead of id.

The server returns a Parameters resource with result (bool), match[] (each match carries relationship + concept).

Unmapped handling

The unmapped field defines behaviour when no match is found:

• mode=provided — returns the source code as-is.
• mode=fixed — returns a default code.
• mode=other-map — delegates to another ConceptMap (chaining).

Example ICD-10 -> SNOMED CT (diabetes)

{
  "resourceType": "ConceptMap",
  "id": "icd10-to-snomed-diabetes",
  "url": "http://example.org/fhir/ConceptMap/icd10-to-snomed-diabetes",
  "version": "1.0.0",
  "name": "ICD10ToSnomedDiabetes",
  "status": "active",
  "sourceScopeUri": "http://hl7.org/fhir/sid/icd-10",
  "targetScopeUri": "http://snomed.info/sct",
  "group": [{
    "source": "http://hl7.org/fhir/sid/icd-10",
    "target": "http://snomed.info/sct",
    "element": [{
      "code": "E11",
      "display": "Type 2 diabetes mellitus",
      "target": [{
        "code": "44054006",
        "display": "Diabetes mellitus type 2",
        "relationship": "equivalent"
      }]
    }, {
      "code": "E11.9",
      "display": "Type 2 diabetes mellitus without complications",
      "target": [{
        "code": "313436004",
        "display": "Type 2 diabetes mellitus without complication",
        "relationship": "equivalent"
      }]
    }]
  }],
  "unmapped": {
    "mode": "fixed",
    "code": "UNMAPPED",
    "display": "Concept not mapped"
  }
}

Common pitfalls

• Unversioned mappings — SNOMED CT changes every 6 months. Pin source and target version in group.
• Missing relationship — a target without relationship is invalid.
• Cycles via dependsOn — avoid circular maps between ConceptMaps.
• Undocumented 1:N cardinality — specify in comment why a source code yields multiple targets.

Related resources

• ConceptMap — overview
• ValueSet
• CodeSystem
• TerminologyCapabilities