FHIR API HIEBus™ FHIR API
Interface Guide

Term Mapping

CareEvolution terms are mapped to (and from) FHIR Codeable Concepts. Each concept contains a coding corresponding to the original term plus additional codings for each of the mapped terms. So for example a race term 2106-3 that is mapped to the term C produces this codeable concept:

<valueCodeableConcept>
    <coding>
        <system value="urn:oid:2.16.840.1.113883.6.238"/>
        <code value="2106-3"/>
        <display value="White or Caucasian"/>
        <userSelected value="true"/>
    </coding>
    <coding>
        <system value="http://fhir.carevolution.com/codes/CareEvolution/Race"/>
        <code value="C"/>
        <display value="Caucasian"/>
        <userSelected value="false"/>
    </coding>
    <text value="White or Caucasian"/>
</valueCodeableConcept>

Each coding uses the following values:

  • code - The code of the corresponding term, either the original term or the mapped one.
  • display - The display name. For mapped terms, this is the CareEvolution term name.
  • userSelected - ‘true’ for the original term and ‘false’ for any mapped terms.
  • system - See below.

The coding system is generated from the term family and namespace as follows:

If the term namespace and family match one of a list of standard coding systems, the system uses the corresponding URI. For example the LOINC namespace with LabObservationType family maps to http://loinc.org. This list is a combination of built-in mapping rules and defined by built-in systems plus configured ones. This mapping combines built-in rules and optional configured ones.

Non-standard term namespace and families are mapped in this way:

Namespace code System URI Example
A URL–i.e., starts with http: or https: same as the namespace code Namespace Code: http://myserver.com/obstype
System URI: http://myserver.com/obstypes
A GUID urn:uuid:<namespace code> Namespace Code: bf0bee1d-3cf6-421a-9a07-f226ac233abd
System URI: urn:uuid:bf0bee1d-3cf6-421a-9a07-f226ac233abd
An OID–i.e., a list of numbers separated by dots urn:oid:<namespace code> Namespace Code: 1.3.6.1.4.1.21367.13.20.3000
System URI: urn:oid:1.3.6.1.4.1.21367.13.20.3000
anything else <site URI>/codes/<namespace code>/<family> Family: ObservationType, Namespace Code: PA
System URI: http://carevolution.com/codes/PA/ObservationType*

(*) assuming http://careevolution.com is the site URI

Mapping Terms from FHIR

When mapping from FHIR to CareEvolution terms, the system just uses the above rules in reverse, except for standard code systems. Standard code systems are typically not writable (e.g., a FHIR import cannot add or modify terms in the standard LOINC namespace) - and so in those cases the system adds a prefix to the namespace code, so for example http://loinc.org is mapped to the FHIR-LOINC namespace. The prefix is the ‘Default term namespace code’ defined in the mapping configuration.

The standard coding system list in the FHIR information page specifies which coding systems are writable. It is possible to redefine a standard coding system as writable by adding it to the coding systems in the mapping configuration.

Enabling ‘Forbid standard term namespaces’ in the mapping configuration prevents the prefixing of standard namespaces, causing the system to throw an error instead if an unrecognized term is encountered. This can be useful for clients that both read and write FHIR data and could find the prefixing misleading (e.g., sending codes using the http://loinc.org system and then getting back something completely different).

When mapping from FHIR, the system also considers the OID of standard coding system, if present. For example: both http://loinc.org and urn:oid:2.16.840.1.113883.6.1 map to the LOINC namespace. This OID is ignored when mapping to FHIR.