HL7 FHIR® US Core Implementation Guide CI Build

US Core, published by HL7 International - US Realm Steering Committee. This is not an authorized publication; it is the continuous build for version 3.1.1). This version is based on the current content of https://github.com/HL7/US-Core-R4/ and changes regularly. See the Directory of published versions

General Guidance

This section outlines important definitions, interpretations, and requirements common to all US Core actors used in this guide. The conformance verbs - SHALL, SHOULD, MAY - used in this guide are defined in FHIR Conformance Rules.


Contents


U.S. Core Data for Interoperability and 2015 Edition Common Clinical Data Set

The US Core Profiles were originally designed to meet the 2015 Edition certification criterion for Patient Selection 170.315(g)(7), and Application Access – Data Category Request 170.315(g)(8). They were created for each item in the 2015 Edition Common Clinical Data Set (CCDS). The Location, Organization, and Practitioner Profiles are not called out specifically in the certification criteria but are included because they are directly referenced by other profiles. The US Core Profiles are informed by the prior Data Access Framework and the Argonaut Data Query Implementation Guides. However, the profiles here are stand alone and include requirements from the U.S. Core Data for Interoperability (USCDI) v1.

The table below lists the US Core Profile and FHIR Resources used for the corresponding USCDI Data elements:

USCDI v1 Summary of Data Classes and Data Elements US Core Profile FHIR Resource  
Allergies and Intolerances:      
Substance (Medication) US Core Allergies Profile AllergyIntolerance  
Substance (Drug Class) US Core Allergies Profile AllergyIntolerance  
Reaction US Core Allergies Profile AllergyIntolerance  
Assessment and Plan of Treatment US Core CarePlan Profile CarePlan  
Care Team Members US Core CareTeam Profile CareTeam  
Clinical Notes:      
Consultation Note US Core DocumentReference Profile DocumentReference  
Discharge US Core DocumentReference Profile DocumentReference  
Summary Note US Core DocumentReference Profile DocumentReference  
History & Physical US Core DocumentReference Profile,US Core DiagnosticReport Profile for Report and Note exchange DocumentReference,DiagnosticReport  
Imaging Narrative US Core DocumentReference Profile,US Core DiagnosticReport Profile for Report and Note exchange DocumentReference,DiagnosticReport  
Laboratory Report Narrative US Core DocumentReference Profile,US Core DiagnosticReport Profile for Report and Note exchange DocumentReference,DiagnosticReport  
Pathology Report Narrative US Core DocumentReference Profile,US Core DiagnosticReport Profile for Report and Note exchange DocumentReference,DiagnosticReport  
Procedure Note US Core DocumentReference Profile,US Core DiagnosticReport Profile for Report and Note exchange DocumentReference,DiagnosticReport  
Progress Note US Core DocumentReference Profile DocumentReference  
Consultation Note US Core DocumentReference Profile DocumentReference  
Goals:      
Patient Goals US Core Goal Profile Goal  
Health Concerns US Core Condition Profile Condition  
Immunizations US Core Immunization Profile Immunization  
Laboratory:      
Tests US Core Laboratory Result Observation Profile, US Core DiagnosticReport Profile for Laboratory Results Reporting Observation, DiagnosticReport  
Values/Results US Core Laboratory Result Observation Profile, US Core DiagnosticReport Profile for Laboratory Results Reporting Observation, DiagnosticReport  
Medications:      
Medications US Core Medication Profile, US Core Medication Request Profile Medication, MedicationRequest  
Medication Allergies US Core Allergies Profile AllergyIntolerance  
Patient Demographics:      
First Name US Core Patient Profile Patient.name.given  
Last Name US Core Patient Profile Patient.name.family  
Previous Name US Core Patient Profile Patient.name  
Middle Name (including middle initial) US Core Patient Profile Patient.name.given  
Suffix US Core Patient Profile Patient.name.suffix  
Birth Sex US Core Patient Profile US Core Birth Sex Extension  
Date of Birth US Core Patient Profile Patient.birthDate  
Race US Core Patient Profile US Core Race Extension  
Ethnicity US Core Patient Profile US Core Ethnicity Extension  
Preferred Language US Core Patient Profile Patient.communication  
Address US Core Patient Profile Patient.address  
Phone Number US Core Patient Profile Patient.telecom  
Problems US Core Condition Profile Condition  
Procedures US Core Procedure Profile Procedure  
Provenance: US Core Provenance Profile Provenance  
Author Time Stamp US Core Provenance Profile Provenance.recorded  
Author Organization US Core Provenance Profile Provenance.agent  
Smoking Status US Core Smoking Status Observation Profile Observation  
Unique Device Identifier(s) for a Patient’s Implantable Device(s) US Core Implantable Device Profile Device  
Vital Signs:      
Diastolic blood pressure Blood pressure systolic and diastolic (FHIR Core Profile) Observation  
Systolic blood pressure Blood pressure systolic and diastolic (FHIR Core Profile) Observation  
Body height Body height (FHIR Core Profile) Observation  
Body weight Body weight (FHIR Core Profile) Observation  
Heart rate Heart rate (FHIR Core Profile) Observation  
Respiratory rate Respiratory rate (FHIR Core Profile) Observation  
Body temperature Body temperature (FHIR Core Profile) Observation  
Pulse oximetry US Core Pulse Oximetry Profile (Builds on FHIR Core Profile) Observation  
Inhaled oxygen concentration US Core Pulse Oximetry Profile (Builds on FHIR Core Profile) Observation  
BMI Percentile (2-20 years old) US Core Pediatric BMI for Age Observation Profile (Builds on FHIR Core Profile) Observation  
Weight-for-length Percentile (Birth - 36 months) US Core Pediatric Weight for Height Observation Profile (Builds on FHIR Core Profile) Observation  
Occipital-frontal Head Circumference Percentile (Birth - 36 months) US Core Pediatric Head Occipital Frontal Circumference Observation Profile (Builds on FHIR Core Profile) Observation  

Changes Between Major Version of FHIR

With each major version in FHIR, the core data models have undergone changes. The FHIR core specification provides a base resource differential to help implementers navigate version changes.

Claiming Conformance to a US Core Profile

To claim conformance to a US Core Profile US Core Servers SHALL:

  • Be able to populate all profile data elements that have a minimum cardinality >= 1 and/or flagged as Must Support as defined by that profile’s StructureDefinition.
  • Conform to the US Core Server Capability Statement expectations for that profile’s type.

Must Support

For querying and reading US Core Profiles, Must Support on any profile data element SHALL be interpreted as follows (see the Future of US Core page for writing and updating US Core Profiles.) :

  • US Core Responders SHALL be capable of populating all data elements as part of the query results as specified by the US Core Server Capability Statement.
  • US Core Requestors SHALL be capable of processing resource instances containing the data elements without generating an error or causing the application to fail. In other words US Core Requestors SHOULD be capable of displaying the data elements for human use or storing it for other purposes.
  • In situations where information on a particular data element is not present and the reason for absence is unknown, US Core Responders SHALL NOT include the data elements in the resource instance returned as part of the query results.
  • When querying US Core Responders, US Core Requestors SHALL interpret missing data elements within resource instances as data not present in the US Core Responder’s system.
  • In situations where information on a particular data element is missing and the US Core Responder knows the precise reason for the absence of data, US Core Responders SHALL send the reason for the missing information using values (such as nullFlavors) from the value set where they exist or using the dataAbsentReason extension.
  • US Core Requestors SHALL be able to process resource instances containing data elements asserting missing information.

  • NOTE: Typically US Core Responder Actor = Server and US Core Requestor Actor = Client
  • NOTE: The above definition of Must Support is derived from HL7v2 concept “Required but may be empty - RE” described in HL7v2 V28_CH02B_Conformance.doc.
  • NOTE: Readers are advised to understand FHIR Terminology requirements, FHIR RESTful API based on the HTTP protocol, along with FHIR Data Types, FHIR Search and FHIR Resource formats before implementing US Core requirements.

Referencing US Core Profiles

Many of the profiles in this guide reference other FHIR resources that are also US Core Profiles. This is defined in the formal profile definitions. For example, US Core CareTeam Profile references US Core Patient. For any other references to base FHIR resources1 or not formally defined in a US Core Profiles, the referenced resource SHOULD be a US Core Profile if a US Core Profile exists for the resource type. For example, although Condition.asserter is not constrained by this guide, the reference to Patient or Practitioner SHOULD be a valid US Core Patient or US Core Practitioner. US Core Resources in the differential view and marked as “Must Support” follow the Must Support rules listed above. Other resources allowed in the base FHIR specification may be referenced even though the current publication framework does not display them. For example, RelatedPerson is an allowed target reference in DocumentReference.author.

There are scenarios when contained resources are used in US Core Profiles. They occur when the content referred to in the contained resource does not have an independent existence apart from the resource that contains it. For example, the Medication List Guidance page describes how a contained Medication in MedicationRequest is used for representing the medication. When referencing a contained resource in a US Core Profile, the contained resource SHOULD be a US Core Profile if a US Core Profile exists for the resource type.

Missing Data

If the source system does not have data for a Must Support data element, the data element is omitted from the resource as described above. If the source system does not have data for a required data element (in other words, where the minimum cardinality is > 0), the core specification provides guidance which is summarized below:

  1. For non-coded data elements, use the DataAbsentReason Extension in the data type
    • Use the code unknown - The value is expected to exist but is not known.

    Example: Patient resource where the patient name is not available.

    {
      "resourceType" : "Patient",
           ...
           "name": [
             {
               "extension": [
                 {
                   "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
                   "valueCode": "unknown"
                 }
               ]
             }
           ]
            "telecom" :
            ...
         }
    
  2. For coded data elements:
    • example, preferred, or extensible binding strengths (CodeableConcept datatypes):
      • if the source systems has text but no coded data, only the text element is used.
      • if there is neither text or coded data:
        • use the appropriate “unknown” concept code from the value set if available
        • if the value set does not have the appropriate “unknown” concept code, use unknown from the DataAbsentReason Code System.
    • required binding strength (CodeableConcept or code datatypes):
      • use the appropriate “unknown” concept code from the value set if available
      • For the following status elements no appropriate “unknown” concept code is available, therefore the element must be populated:
        • AllergyIntolerance.clinicalStatus
        • Condition.clinicalStatus
        • DocumentReference.status
        • Immunization.status
        • Goal.lifecycleStatus

        If one of these a status code is missing, a 404 http error code and an OperationOutcome SHALL be returned in response to a query for the resource.

Using Codes in US Core Profiles

Required binding for CodeableConcept Datatype

Required binding to a value set definition means that one of the codes from the specified value set SHALL be used and using only text is not valid. Multiple codings (translations) are permitted as is discussed below.

Extensible binding for CodeableConcept Datatype

Extensible binding to a value set definition for this IG means that if the data type is CodeableConcept, then one of the coding values SHALL be from the specified value set if a code applies, but if no suitable code exists in the value set, alternate code(s) may be provided in its place. If only text available, then just text may be used.

Using multiple codes with CodeableConcept Datatype

Alternate codes may be provided in addition to the standard codes defined in required or extensible value sets. The alternate codes are called “translations”. These translations may be equivalent to or narrower in meaning to the standard concept code.

Example of multiple translation for Body Weight concept code.

    "code": {
        "coding": [
         {
            "system": "http://loinc.org",  //NOTE:this is the standard concept defined in the value set//
            "code": "29463-7",
            "display": "Body Weight"
          },
    //NOTE:this is a translation to a more specific concept
         {
            "system": "http://loinc.org",
            "code": "3141-9",
            "display": "Body Weight Measured"
          },
    //NOTE:this is a translation to a different code system (Snomed CT)
         {
            "system": "http://snomed.info/sct",
            "code":  “364589006”,
            "display": "Body Weight"
          }
    //NOTE:this is a translation to a locally defined code
         {
            "system": "http://AcmeHealthCare.org",
            "code":  “BWT”,
            "display": "Body Weight"
          }
        ],
        "text": "weight"
      },

Example of translation of CVX vaccine code to NDC code.

    "vaccineCode" : {
        "coding" : [
          {
            "system" : "http://hl7.org/fhir/R4/sid/cvx",
            "code" : "158",
            "display" : "influenza, injectable, quadrivalent"
          },
          {
            "system" : "http://hl7.org/fhir/R4/sid/ndc",
            "code" : "49281-0623-78",
            "display" : "FLUZONE QUADRIVALENT"
          }
        ]
      },

Using UCUM codes in the Quantity datatype

Both the Vital Signs Profile and US Core Laboratory Result Observation Profile bind the valueQuantity datatypes to the UCUM code system. A FHIR UCUM Codes value set that defines all UCUM codes is in the FHIR specification. This guidance specifies how to represent the Quantity datatype when the correct UCUM units are missing or the units are missing altogether which will likely occur in the real world.

UCUM code provided

 "valueQuantity": {
    "value": 26.0,
    "unit": "g/mL",
   "system": "http://unitsofmeasure.org",
   "code": "g/mL"
  }

free text units only:

  • If UCUM units are not available then represent units in the unit element.
 "valueQuantity": {
    "value": 26.0,
    "unit": "RR",
     }

no units

 "valueQuantity": {
    "value": 26.0
 }

Representing Deleted Information

Clinical information that has been removed from the patient’s record needs to be represented in a way so that client systems know they can delete them.

  • A FHIR server SHOULD not delete resources.

  • The resource status SHOULD be updated to the appropriate status such as entered-in-error or inactive, and these resources SHOULD still be searchable by client applications.

  • If the status is entered-in-error:

    • for patient viewing systems the content of resource SHOULD be removed. In other words a blank resource.

    • A provider facing system MAY be supplied with additional details that the patient viewing system would typically not have access to.

Language Support

There is a basic need be able to access records in your language, and the data provider should do their best to translate (safely) to the language being requested. Understanding that this will be variably complete depending on the nature of the record. For example translating the following elements is relatively straightforward:

  • Coding.display
  • Generated narrative
  • Attachment.title

The following guidelines outline how to request and return a resource in the requested language.

  • Clients MAY request language/locale using the http Accept-Language header.
  • Servers SHOULD make reasonable efforts to translate what can be safely translated.
  • Servers SHOULD populate the Resource’s language element which is reasonably based on the underlying language of record, not the requested language.
    • Servers SHALL use the http://hl7.org/fhir/StructureDefinition/language extension when the language of a display, etc is known to be different to the stated (or inferred) language.

      Example

          <?xml version="1.0" encoding="UTF-8"?>
          <Patient xmlns="http://hl7.org/fhir">
              <id value="language-example-1"/>
              <meta>
              [...snip...]
              </meta>
              <language value="es"/>
              <!--0..1 Language of the resource content in this case Spanish-->
              <text>
              [...snip...]
              </text>
              <extension url="http://hl7.org/fhir/us/core/StructureDefinition/us-core-race">
                  <extension url="ombCategory">
                      <valueCoding>
                          <system value="urn:oid:2.16.840.1.113883.6.238"/>
                          <code value="2106-3"/>
                          <display value="White">
                              <!--Human Language extension-->
                              <extension url="http://hl7.org/fhir/StructureDefinition/language">
                                  <valueCode value="en"/>
                                  <!--English is different from stated language-->
                              </extension>
                          </display>
                      </valueCoding>
                  </extension>
              [...snip...]
      
  • Servers SHALL use the http://hl7.org/fhir/StructureDefinition/translation extension when the server is providing additional translations by its own choice or in response to a different Accept-Language than what the resource is stored in.

    Example

          <?xml version="1.0" encoding="UTF-8"?>
          <Patient xmlns="http://hl7.org/fhir">
              <id value="language-example-2"/>
              <meta>
              [...snip...]
              </meta>
              <language value="en"/>
              <!--0..1 Language of the resource content: English-->
              <text>
              [...snip...]
              </text>
              <extension url="http://hl7.org/fhir/us/core/StructureDefinition/us-core-race">
                  <extension url="ombCategory">
                      <valueCoding>
                          <system value="urn:oid:2.16.840.1.113883.6.238"/>
                          <code value="2106-3"/>
                          <display value="White">
                          <!-- Translation -->
                          <extension
                               url="http://hl7.org/fhir/StructureDefinition/translation" >
                           <extension url="lang"> <!-- 1..1 Code for Language -->
                            <valueCode value="es"/><!-- 0..1 Value of extension -->
                           </extension>
                           <extension url="content"> <!-- 1..1 Content in other Language -->
                            <valueString value="Blanca">
                           </extension>
                          </extension>
                          </display>
                      </valueCoding>
                  </extension>
                  [...snip...]
    
  • Servers SHOULD make it known what languages are supported in their CapabilityStatement(s) using this extension2:

    http://hl7.org/fhir/5.0/StructureDefinition/extension-CapablilityStatement.acceptLanguage

For further guidance on language and locale for generation of the resource narrative, see the Multi-language support for Narratives in the core specification.

Read(Fetch) Syntax

For fetching a resource interactions on profile pages are defined with the following syntax:

GET [base]/[Resource-type]/[id] {parameters}

  • GET is the HTTP verb used for fetching a resource
  • Content surrounded by [] is mandatory for the client to supply, and will be replaced by the string literal identified.
  • Content surrounded by {} is optional for the client to supply, and will be replaced by the string literal identified.
    • parameters: URL parameters as defined for the particular interaction (e.g.”?_format=xml”}

For more information see the FHIR RESTful API

Search Syntax

For searching a resource, interactions on profile pages are defined with the following syntax:

GET [base]/[Resource-type]?[parameter1]{:m1|m2|...}={c1|c2|...}[value1{,value2,...}]{&[parameter2]{:m1|m2|...}={c1|c2|...}[value1{,value2,...}]&...}

  • GET is the HTTP verb used for fetching a resource
  • Variables surrounded by “[]” are mandatory for the client to supply, and will be replaced by the string literal identified.
  • Variables surrounded by “{}” are optional for the client to supply, and will be replaced by the string literal identified.
    • base: The Service Root URL (e.g. “https://fhir-open-api-dstu2.smarthealthit.org”)
    • Resource-type: The name of a resource type (e.g. “Patient”)
    • parameter: the search parameters as defined for the particular interaction (e.g.”?patient=Patient/123”)
    • value: the search parameter value for a particular search
      • note for values of type token (how to search by token), the syntax {system|}[code] means that the system value is optional for the client to supply
    • {:m1 m2 …}: The list of supported search parameter modifiers
    • {c1 c2 …}: The list of supported search parameter comparators
    • {,value2,…}: Optional multiple ‘OR’ Values
    • {&parameter2={:m1 m2 …}={c1 c2 …}[value1{,value2,…}&…}: Optional multiple ‘AND’ search parameters

In the simplest case, a search is executed by performing a GET operation in the RESTful framework:

GET [base]/[Resource-type]?name=value&...

For this RESTful search, the parameters are a series of name=[value] pairs encoded in the URL. The search parameter names are defined for each resource. For example, the Observation resource the name “code” for search on the LOINC code. For more information see the FHIR RESTful Search API

Note that the patient may be implicit in the context in some implementations (e.g. using SMART). Then the patient parameter can be omitted:

GET [base]/[Resource-type]{?other-parameters}

Search for Servers Requiring Status

Servers are strongly encouraged to support a query for resources without requiring a status parameter. However, if business requirements prohibit this they SHALL follow the guidelines here.

For searches where the client does not supply a status parameter, an implementation’s business rules may override the FHIR RESTful search expectations and require a status parameter to be provided. These systems are allowed to reject such requests as follows:

  • SHALL return an http 400 status
  • SHALL return an OperationOutcome specifying that status(es) must be present.
  • SHALL support search with status if status required
  • SHALL NOT restrict search results ( i.e. apply ‘hidden’ filters) when a client includes status parameters in the query.
    • If a system doesn’t support a specific status code value that is queried, search results SHOULD return an http 200 status with search bundle containing resources matching the search criteria and an OperationOutcome warning the client which status code value is not supported.

    • For example, in a query enumerating all the AllergyIntolerance.verificationStatus statuses to a system that supports concepts unconfirmed, confirmed, entered-in-error but not refuted, the search parameter is referring to an unsupported code since refuted is not known to the server.

Storyboard for this example

This example is based upon the following scenario:

Patient 1137192 uses an App to request all his encounters from the provider. The provider system requires status and rejects the request returning a 400 and an OperationOutcome specifying that a status parameter is required for this search.

Request:

Get “all encounters” for a patient 1137192 by querying Encounter using the patient search parameter.

GET [base]/Encounter?patient=1137192

Response:

Instead of returning a search Bundle resource containing all the Encounter for the patient, the server return a 400 Not Found and an OperationOutcome detailing hat a status parameter is required for this search.

HTTP/1.1 400 Not Found
[other headers]
{
  "resourceType": "OperationOutcome",
  "id": "no-status",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "details": {
        "text": "A \"status\" search parameter is required for this search"
      },
      "diagnostics": "valid statuses for Encounter include planned | arrived | triaged | in-progress | onleave | finished | cancelled | entered-in-error | unknown"
    }
  ]
}


  • SHALL document this behavior in its CapabilityStatement for the “search-type” interaction in CapabilityStatement.rest.resource.interaction.documentation.
  • Follow the deleted data guidance above.

Searching Multiple Patients

Currently, most EHRs permit queries that provide a single patient id, but do not support the comma separated query or a query where the patient parameter is omitted as described in the standard FHIR REST API. Instead, a user facing app can perform multiple “parallel” queries on a list of patient ids. Alternatively, the FHIR Bulk Data Access (Flat FHIR) specification can be used to perform a “back end” system level query to access a large volumes of information on a group of individuals or when trying to identify and query against an unknown population such as when looking for population based research data.

However, neither specification defines how a user facing provider app is able to seek realtime “operational” data on multiple patients (such as all patients with recent lab results). Opportunities to add this capability to this guide are discussed in Future of US Core

This IG does not support patient compartment based searches.

Across Platform Searches

US Core servers are not required to resolve full URLs that are external to their environment.

Guidance On Limiting The Number Of Search Results

In order to manage the number of search results returned, the server may choose to return the results in a series of pages. The search result set contains the URLs that the client uses to request additional pages from the search set. For a simple RESTful search, the page links are contained in the returned bundle as links. See the managing returned resources in the FHIR specification for more information.


  1. For example, the base Location resource is being referenced by the US Core Encounter and US Core PractitionerRole resources. 

  2. This extension is converted from a new element in a future version of CapabilityStatement.