US Core Implementation Guide
9.0.0-ballot - STU 9 Ballot United States of America flag

US Core Implementation Guide, published by HL7 International / Cross-Group Projects. This guide is not an authorized publication; it is the continuous build for version 9.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/US-Core/ and changes regularly. See the Directory of published versions

Changes Between Versions

Page standards status: Trial-use

Introduction

With each major version of FHIR, the core data models have changed. The FHIR core specification provides a base resource differential to help implementers navigate version changes. However, there are additional considerations for the user and developer experience when transitioning from FHIR Version DSTU2 to FHIR R4. Similarly, US Core undergoes annual updates, which are documented on the US Core Roadmap page. Each update to a new version of US Core changes the US Core Profiles and conformance expectations. The following guidance on this page is provided to ensure a smoother upgrade path. It reflects non-normative best practices established at the time of publication.

Versioning of US Core

US Core undergoes annual updates with new guidance, requirements, profiles, and changes to existing content. The Directory of published versions lists the publication history with links to each version of US Core. The Change Log documents the changes across the versions of US Core. The Argonaut Data Query guide was published separately and is not included in the directory or change log.

Work is underway to identify corrections in subsequent versions as "patches" to prior versions for ASTP Certification.

Cross Version Comparisons

The table below summarizes the different profiles and resource types between Argonaut Data Query and major releases of US Core :

Detailed comparisons between the FHIR artifacts in this current 9.0.0-ballot version of US Core and each previous major release are provided in the links below:

Endpoint Discoverability

A Server may support Version DSTU2 and Argonaut Data Query or FHIR R4 and US Core ver 3.1.1+ or both. A Server may make explicit which version of Argo/US Core is on their FHIR endpoint (e.g., "DSTU2" or "R4" path component or separate files based on version). However, the best practice is to inspect the endpoint metadata on each endpoint to discover the information about a Server's capabilities, including the FHIR version and the US Core Profile version that is supported:

GET [base]/metadata{?mode=[mode]} {&_format=[mime-type]}

No Guarantee that Resource IDs are Preserved

Servers SHOULD maintain a stable common identifier for a resource across versions. When the FHIR resource ID or business identifier of the underlying clinical data is not maintained across FHIR versions, the Client SHALL use an alternative method to avoid duplication, such as the guidance provided in the Interoperable Digital Identity and Patient Matching Implementation Guide.

Expectation that FHIR DSTU2 Data is Preserved in FHIR R4

In an upgraded R4 endpoint, any data in FHIR DSTU2 SHOULD be in FHIR R4. However, not all data in R4 may be available in DSTU2 because some profiles and data classes, like Clinical Notes and pediatric observations, are not part of DSTU2.

  • The FHIR RESTful resource types supported in a DSTU2 implementation SHOULD be supported in a R4 implementation
    • Exceptions
      • MedicationStatement may be deprecated, and the data SHOULD be mapped to MedicationRequest.
        • See the guidance on the Medication List page for how to access a patient's medications
      • Care teams as represented by CarePlan in DSTU2 SHOULD be replaced by and the data mapped to CareTeam in R4
  • Servers SHOULD make available the same information in DSTU2 and R4 where the more recent standard allows. (e.g., patient Rhonda Jones is available on both)
    • Exceptions
      • MedicationStatement data mapped to MedicationRequest
      • care teams, as represented by CarePlan, SHOULD be mapped to CareTeam in R4
  • Data SHOULD be maintained between versions (i.e., not be degraded).
  • When updating between versions, Clients SHOULD consider the impact of any changes to data visualization on the usability for the end user and the maintenance of data integrity.

Authorization Across Versions

  • To enable the clients to access resources from different version-specific endpoints with the same authorization token, Production Systems SHOULD use the same base endpoint (Authorization Endpoint URL) across versions and allow the same authorization token for different version-specific endpoints.
  • The more recent version endpoints will have additional/changed resource types and thus added scopes. For example, US Core may add a DeviceAssociation Profile when updating from FHIR R4 to FHIR R6.