Skip to main content

ConceptMap Operations

ConceptMap resources define mappings between codes in different code systems -- essential for data integration across systems that use different terminologies.

ConceptMap in FHIR​

A ConceptMap defines relationships between codes in a source code system and codes in a target code system. Common use cases include:

SourceTargetUse Case
ICD-9-CMICD-10-CMLegacy system migration
HL7v2 tablesFHIR code systemsHL7v2 to FHIR transformation
Local codesSNOMED CTStandardization
SNOMED CTICD-10Billing and reporting

$translate​

The $translate operation translates a code from a source ValueSet (or CodeSystem) to a target, by matching it against the groups of a persisted ConceptMap.

source is required. The code to translate can be given either as a coding/codeableConcept parameter, or as separate system + code (+ optional version) parameters. target and targetsystem are treated as aliases of each other.

The non-standard sourceSystem / sourceCode / targetSystem aliases are also accepted as a convenience (filling in system/code/target when those aren't otherwise supplied), for compatibility with test suites that use that naming.

GET Request​

curl 'http://localhost:9090/fhir/r4/ConceptMap/$translate?source=http://hl7.org/fhir/sid/icd-10-cm&target=http://snomed.info/sct&system=http://hl7.org/fhir/sid/icd-10-cm&code=E11.9'

POST Request​

curl -X POST http://localhost:9090/fhir/r4/ConceptMap/$translate \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "Parameters",
"parameter": [
{ "name": "source", "valueUri": "http://snomed.info/sct?fhir_vs" },
{ "name": "target", "valueUri": "http://hl7.org/fhir/sid/icd-10-us" },
{ "name": "system", "valueUri": "http://snomed.info/sct" },
{ "name": "code", "valueCode": "263204007" }
]
}'

Response​

{
"resourceType": "Parameters",
"parameter": [
{
"name": "match",
"part": [
{
"valueCode": "equivalent",
"name": "equivalent"
},
{
"name": "concept",
"valueCoding": {
"system": "http://snomed.info/sct",
"code": "44054006",
"display": "Type 2 diabetes mellitus",
"userSelected": false
}
},
{
"name": "source",
"valueUri": "http://example.org/fhir/ConceptMap/icd10-to-snomed-diabetes-example"
}
]
},
{
"name": "result",
"valueBoolean": true
}
]
}

Parameters​

ParameterTypeDescription
sourceuriSource ValueSet (or CodeSystem) canonical URL -- required
target / targetsystemuriTarget ValueSet (or CodeSystem) canonical URL -- aliases of each other
systemuriCodeSystem of the code being translated, when not using coding/codeableConcept
codecodeThe code being translated, when not using coding/codeableConcept
versionstringVersion of system, when using system + code
codingCodingThe code being translated, as a Coding
codeableConceptCodeableConceptThe code being translated, as a CodeableConcept

Match Equivalence Types​

EquivalenceMeaning
equivalentExact semantic match
widerTarget is broader in meaning
narrowerTarget is narrower in meaning
inexactApproximate match
unmatchedNo match found

$closure​

The $closure operation (HL7 spec) maintains a client-named, incrementally-growing subsumption table. It's a base-level operation -- called as POST /fhir/r4/$closure, not scoped under /ConceptMap -- but is documented here because it returns a ConceptMap.

Each call adds the given concepts to the named table and returns only the subsumption pairs not yet reported for that name: both a new concept's own ancestors (backed by the same closure table $subsumes and $lookup use), and any case where the new concept turns out to be an ancestor of a concept added in an earlier call. Concepts that can't be resolved against a known CodeSystem are returned as unmatched rather than failing the whole call.

Request​

curl -X POST 'http://localhost:9090/fhir/r4/$closure' \
-H "Content-Type: application/fhir+json" \
-d '{
"resourceType": "Parameters",
"parameter": [
{ "name": "name", "valueString": "icd10-diabetes-closure-demo" },
{ "name": "concept", "valueCoding": { "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9" } },
{ "name": "concept", "valueCoding": { "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E10.9" } }
]
}'

Response​

{
"resourceType": "ConceptMap",
"id": "72eb62df-98f3-46d0-8bb1-b188884ae7f3",
"group": [
{
"source": "http://hl7.org/fhir/sid/icd-10-cm",
"element": [
{
"code": "E11.9",
"display": "Type 2 diabetes mellitus without complications",
"target": [
{
"equivalence": "subsumes",
"code": "E11",
"display": "Type 2 diabetes mellitus"
}
]
},
{
"code": "E11.9",
"display": "Type 2 diabetes mellitus without complications",
"target": [
{
"equivalence": "subsumes",
"code": "Section-E08-E13",
"display": "Diabetes mellitus (E08-E13)"
}
]
},
{
"code": "E11.9",
"display": "Type 2 diabetes mellitus without complications",
"target": [
{
"equivalence": "subsumes",
"code": "Chapter-4",
"display": "Endocrine, nutritional and metabolic diseases (E00-E89)"
}
]
},
{
"code": "E10.9",
"display": "Type 1 diabetes mellitus without complications",
"target": [
{
"equivalence": "subsumes",
"code": "E10",
"display": "Type 1 diabetes mellitus"
}
]
},
{
"code": "E10.9",
"display": "Type 1 diabetes mellitus without complications",
"target": [
{
"equivalence": "subsumes",
"code": "Section-E08-E13",
"display": "Diabetes mellitus (E08-E13)"
}
]
},
{
"code": "E10.9",
"display": "Type 1 diabetes mellitus without complications",
"target": [
{
"equivalence": "subsumes",
"code": "Chapter-4",
"display": "Endocrine, nutritional and metabolic diseases (E00-E89)"
}
]
}
],
"target": "http://hl7.org/fhir/sid/icd-10-cm"
}
],
"version": "3",
"status": "active"
}

The response version identifies this call's result. Pass it back as a version parameter on a later $closure call for the same name to resync everything reported since that version, in addition to whatever the new call discovers.

Parameters​

ParameterTypeDescription
namestringIdentifies the closure table -- required
conceptCodingZero or more concepts to add to the table
versionstringA previously-returned version, to resync everything reported since

Creating ConceptMaps​

You can define custom ConceptMap resources for your mappings:

{
"resourceType": "ConceptMap",
"url": "http://example.org/ConceptMap/local-to-loinc",
"status": "active",
"sourceUri": "http://example.org/CodeSystem/local-lab-codes",
"targetUri": "http://loinc.org",
"group": [
{
"source": "http://example.org/CodeSystem/local-lab-codes",
"target": "http://loinc.org",
"element": [
{
"code": "GLU",
"display": "Glucose",
"target": [
{
"code": "2345-7",
"display": "Glucose [Mass/volume] in Serum or Plasma",
"equivalence": "equivalent"
}
]
}
]
}
]
}