18.4.1Terminology Mapping

Smile CDR includes the ability to apply translations/mappings between different CodeSystems through a series of operations and capabilities described here.

In this context, mapping refers to taking a concept in one CodeSystem, and finding a concept with an identical, similar, or related meaning in another CodeSystem. For example, this might mean conbverting between standard terminologies such as converting between SNOMED CT and LOINC. It might also mean converting between local codes defined within an institution and standardized terminology sets.

Translation does not refer to human language translation in this context, such as converting between English and other spoken/written languages. For clarity, the term mapping is used here.

18.4.2The ConceptMap Resource

Mappings are stored in Smile CDR using the ConceptMap resource. ConceptMap resources store mappings between source and target concepts, identified by their CodeSystem URL and code, and optionally the CodeSystem version as well.

A simple example is shown below. Here, we have a local CodeSystem called http://my-codes that contains concepts for blood pressure. We want to map these concepts to the LOINC CodeSystem, which contains internationally recognized concepts for blood pressure.

{
	"resourceType": "ConceptMap",
	"id": "my-codes-to-loinc",
	"url": "http://my-codes-to-loinc",
	"version": "1.0",
	"group": [ {
		"source": "http://my-codes",
		"target": "http://loinc.org",
		"element": [ {
			"code": "BP-S",
			"target": [ {
				"code": "8480-6",
				"display": "Systolic blood pressure",
				"equivalence": "equivalent"
			} ]
		}, {
			"code": "BP-D",
			"target": [ {
				"code": "8462-4",
				"display": "Diastolic blood pressure",
				"equivalence": "equivalent"
			} ]
		} ]
	} ]
}

18.4.3Mapping Codes: $translate Operation

The $translate operation is used to look up mappings stored in ConceptMaps. It takes a number of different combinations of parameters, depending on your use case. See also the FHIR $translate Operation page in the FHIR specification.

This operation leverages an internal memory-based caching layer and should typically be very performant for normal operation, even under a heavy load.

18.4.3.1Request Parameters

The following table shows the parameters that can be used with the $translate operation request. The names of some parameters were changed in FHIR R5. In Smile CDR, both versions of the parameter names are supported regardless of the FHIR version being used. It is recommended to migrate applications to use the newer R5 parameter names, which will likely be permanent.

18.4.3.2Example Request

The following shows a simple request to translate a code from one CodeSystem to another. This request should be POSTed to the http://base/ConceptMap/$translate endpoint.

{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "system",
    "valueUri": "http://my-codes"
  }, {
    "name": "targetSystem",
    "valueUri": "http://loinc.org"
  }, {
    "name": "sourceCode",
    "valueCode": "BP-S"
  } ]
}

18.4.3.3Example Response

The following shows a simple response to a translation request.

{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "result",
    "valueBoolean": true
  }, {
    "name": "message",
    "valueString": "Matches found"
  }, {
    "name": "match",
    "part": [ {
      "name": "equivalence",
      "valueCode": "equivalent"
    }, {
      "name": "concept",
      "valueCoding": {
        "system": "http://loinc.org",
        "code": "8480-6",
        "display": "Systolic blood pressure"
      }
    }, {
      "name": "source",
      "valueUri": "http://my-codes-to-loinc"
    } ]
  } ]
}

18.4.4Adding Mappings to ConceptMaps

It is always possible to make changes to a ConceptMap resource directly and upload a new resource version of the ConceptMap to the server. However, two convenience operations are also provided which can be used to make individual modifications to the ConceptMap.

The $hapi.fhir.add-mapping operation adds a new mapping to an existing ConceptMap.

18.4.4.1Request Parameters

18.4.4.2Example Request

The following shows a simple request to add a mapping to a ConceptMap. This request should be POSTed to the http://base/ConceptMap/$hapi.fhir.add-mapping endpoint.

{
	"resourceType": "Parameters",
	"parameter": [ {
		"name": "url",
		"valueUri": "http://my-concept-map-url"
	}, {
		"name": "system",
		"valueUri": "http://my-code-system"
	}, {
		"name": "version",
		"valueCode": "1.0"
	}, {
		"name": "code",
		"valueString": "BP-SYS"
	}, {
		"name": "display",
		"valueString": "Systolic BP"
	}, {
		"name": "targetSystem",
		"valueUri": "http://loinc.org"
	}, {
		"name": "targetVersion",
		"valueCode": "2.57"
	}, {
		"name": "targetCode",
		"valueCode": "11378-7"
	}, {
		"name": "targetDisplay",
		"valueString": "Systolic blood pressure at First encounter"
	}, {
		"name": "equivalence",
		"valueCode": "equivalent"
	} ]
}

18.4.4.3Example Response

The server responds with an OperationOutcome resource indicating that the mapping was added successfully.

{
  "resourceType": "OperationOutcome",
  "issue": [ {
    "severity": "information",
    "code": "informational",
    "diagnostics": "Mapping has been added"
  } ]
}

18.4.5Removing Mappings from ConceptMaps

A similar operation is provided to remove mappings from a ConceptMap.

The $hapi.fhir.remove-mapping operation adds a new mapping to an existing ConceptMap.

18.4.5.1Request Parameters

18.4.5.2Example Request

The following shows a simple request to add a mapping to a ConceptMap. This request should be POSTed to the http://base/ConceptMap/$hapi.fhir.add-mapping endpoint.

{
	"resourceType": "Parameters",
	"parameter": [ {
		"name": "url",
		"valueUri": "http://my-concept-map-url"
	}, {
		"name": "system",
		"valueUri": "http://my-code-system"
	}, {
		"name": "version",
		"valueCode": "1.0"
	}, {
		"name": "code",
		"valueString": "BP-SYS"
	}, {
		"name": "targetSystem",
		"valueUri": "http://loinc.org"
	}, {
		"name": "targetVersion",
		"valueCode": "2.57"
	}, {
		"name": "targetCode",
		"valueCode": "11378-7"
	} ]
}

18.4.5.3Example Response

The server responds with an OperationOutcome resource indicating that the mapping was removed successfully.

{
	"resourceType": "OperationOutcome",
	"issue": [ {
		"severity": "information",
		"code": "informational",
		"diagnostics": "Removed 1 ConceptMap mappings"
	} ]
}