FHIR Response Terminology Mapping
A common problem when implementing FHIR APIs is the challenge of how to return coded data using standard vocabularies when your source data is not modelled using these vocabularies, or is inconsistently modelled using these vocabularies.
For example, suppose you want to implement support for an Implementation Guide that mandates the use of LOINC but your source data uses local/proprietary observation codes.
One solution is to simply apply mappings and add them to the FHIR data you are storing in your repository as you are storing it. This solution, often called Mapping on the Way In, will work but it has potential pitfalls, including:
A potentially better solution is to apply Mapping on the Way Out, meaning that your terminology is managed centrally, and Smile CDR terminology services manipulate your responses before serving them to your FHIR clients.
This approach can be much easier to manage, since it means that you have a single source of truth: if mappings change over time, you have only one place to change them.
Smile CDR provides two settings that can help with this approach. These settings are present on all FHIR Endpoint modules (FHIR Endpoint, Hybrid Providers, and FHIR Gateway). A Validation Support Repository module dependency must be supplied in order to use these features.
Smile CDR can apply concept mappings to your FHIR responses. This means that when a client performs a read-oriented FHIR operation (read/vread/search/history), Smile CDR will look for coded fields of type CodeableConcept and will apply mappings where they exist.
Smile CDR can also apply concept mappings to files generated in a Bulk Export Operation.
Mappings are supplied using one or more ConceptMap resources, which are stored in your validation support repository.
To enable this mapping, enable the Enable Response Terminology Mapping setting. You must also populate the Response Terminology Mapping Specification to supply a specification document.
The specification document should use the format described in FhirEndpointTerminologyResponseMappingSpec and will resemble the following:
{
"systems" : [
{
"sourceSystemUri" : "http://example.com/lab_codes",
"targetSystemUri" : "http://loinc.org"
}, {
"sourceSystemUri" : "http://example.com/anatomy",
"targetSystemUri" : "http://snomed.info"
}
]
}
Each entry in the specification supplies a source CodeSystem canonical URL and a target CodeSystem canonical URL. Only codings found in the response resource where the coding system URL matches an entry in the specification will be mapped. Codes will not be mapped if the CodeableConcept already contains an additional coding with a system matching the specification.
If the Populate Response Coding Displays setting is enabled, Smile CDR will examine all response resources for any Coding elements without a populated Coding.display value. If the system and code are populated the system will attempt to look up the code in the Validation Support Repository and will automatically populate the display if it is found.