Using Codes

Many fields in FHIR are represented with coded values. The HL7 FHIR specification outlines several ways to define and use codes in resources.

Coding Systems

Codes commonly come from:

• The FHIR standard itself (e.g., marital status).
• External standards like HL7, LOINC or SNOMED CT.
• Source system-specific terminology dictionaries.

Resources used in the FHIR Interface may contain any of these coded values. CareEvolution’s terminology management system will translate many source-specific codings into reference codings, in which case both source codings and reference codings will be returned in the resource.

For example, consider the following Observation.code example representing a glucose lab result. Note that it contains both a source specific code of "GLU" from the DemoEMR system, and a reference glucose LOINC code. In addition, code.text field is populated by custom override text provided by the source system.

<code>
    <coding>
        <system value="http://fhir.carevolution.com/codes/DemoEMR/LabObservationType" />
        <code value="GLU" />
        <display value="Glucose" />
        <userSelected value="true" />
    </coding>
    <coding>
        <system value="http://loinc.org" />
        <code value="2345-7" />
        <display value="Glucose SerPl-mCnc" />
        <userSelected value="false" />
    </coding>
    <text value="LRR Conversion Glucose, Fasting (P)" />
</code>

Display Fields

CodeableConcepts can contain an optional text field, populated with a user-entered string. Additionally, the concept may contain one or more codings, each of which may have an optional human-readable display field. Each of these fields is variably populated based on data received from the source system and the ability to translate codings to reference terminologies. Therefore, not all optional values will always be present or populated. Consuming applications must be able to deal with missing fields and to choose among available fields for display.

Each resource type may have one or more fields (e.g. Condition.code, Medication.code, Encounter.class) populated by a CodeableConcept. End-user applications often need to choose a primary value for display while making all other values accessible (e.g. in a click-in or pop-up/hover, etc.). In general, most use cases prioritize a user-entered/source-system display or select a reference terminology display.

Identifying a User-Entered/Source-System Display

Some use cases require display of the text entered or selected in the source system. These typically include use cases for displaying data for an individual person as a complete list without summarization or trending over time.

To display user-entered/source-system display, use the CodeableConcept.text field when available. Otherwise, use the CodeableConcept.coding.display where coding.userSelected=true.

Selecting a Reference Coding

Many use cases require a reference code or display. These include use cases such as:

• Trending labs over time (e.g. display ‘HbA1c (Bld) [Mass fraction]’ for LOINC 4548-4 whether source system provides ‘HbA1C’, ‘Hemoglobin A1C’, ‘HbA1c MFr Bld’, ‘Hemoglobin A1c/Hemoglobin.total in Blood’, or ‘4548-4’)
• Grouping problems in a problem list (e.g. display ‘Asthma’ for ICD10 J45 whether source system provides ‘Mild intermittent asthma’, ‘Asthma (disorder)’, ‘Chronic Asthma’, or ‘Unspecified asthma’, or ‘J45.5’)
• Identifying encounter type (e.g. display ‘OBSENC’ for HL7 ActCode whether source system provides ‘Observation’, ‘obs’, or ‘24hr’)
• Classifying a code using a value set (e.g. using $classify operation on a Medication.code to retrieve therapeutic class)

Reference codings are identified by userSelected=false and a system populated with a reference system URI. In some cases, multiple reference codings will be available and selecting a reference coding is dependent on the specifics of the target use case. For example, Condition.code may contain ICD10, ICD9, and SNOMED. SNOMED is most clinically-friendly and may be the best choice for display in a longitudinal patient record while ICD10 may be most appropriate for analytics. Immunization.code may contain CVX and RxNorm. For vaccinations, CVX is more general while RxNorm has more detail.

In general, the following prioritization is useful in most cases across the most frequent reference code systems:

Though the above list covers many common cases, it is not comprehensive for all fields in all resources and code systems. Furthermore, specific use cases may require a different prioritization.

Finding System URIs

When specifying a code, you must include a system URI. Some examples can be seen in the coded values above:

<system value="http://loinc.org" />
<system value="http://fhir.carevolution.com/codes/DemoEMR/LabObservationType" />

Most codes will be associated with standard, widely-recognized coding systems like LOINC, SNOMED-CT, ICD-10, or NDC. A list of the standard coding systems used by the FHIR API can be found in your site’s FHIR directory.

Normally when performing FHIR operations, you will be working with codes from these standard systems. In unusual situations, you may need to translate between internal CareEvolution codes and standard codes. The system URI explorer, available through the “Search” tab of the request explorer, allows you to take an internal CareEvolution term namespace (such as “LOINC”) and convert it to the standard system URI (http://loinc.org) or vice-versa.