US Core Implementation Guide
5.0.0 - STU5 Release US

This page is part of the US Core (v5.0.0: STU5) based on FHIR R4. The current version which supercedes this version is 5.0.1. For a full list of available versions, see the Directory of published versions

Changes Between Versions

Introduction

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. 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 is discussed in the Future of US Core page. With each update to a new versions of US Core, the US Core Profiles and conformance expectation change. The following the guidance in 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, and 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 the purpose of ONC Certification.

Cross Version Comparisons

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

DSTU2 Profile Equivalent US Core Profile Version Added Notes
Argonaut AllergyIntolerance Profile US Core AllergyIntolerance Profile 3.1.1 or prior version  
Argonaut CarePlan Profile US Core CarePlan Profile 3.1.1 or prior version Type changed from CarePlan in DSTU2 to CareTeam in R4
Argonaut CareTeam Profile US Core CareTeam Profile 3.1.1 or prior version  
Argonaut Condition Profile US Core Condition Profile 3.1.1 or prior version In version 5.0.0 split US Core Condition Profilee into US Core Condition Encounter Diagnosis Profile and US Core Condition Problems and Health Concerns Profile
- US Core Condition Encounter Diagnosis Profile 5.0.0 see above
- US Core Condition Problems and Health Concerns Profile 5.0.0 see above
Argonaut Device Profile US Core Implantable Device Profile 3.1.1 or prior version  
Argonaut DiagnosticReport Profile US Core DiagnosticReport Profile for Laboratory Results Reporting 3.1.1 or prior version  
Argonaut DocumentReference Profile US Core DocumentReference Profile 3.1.1 or prior version  
Argonaut Goal Profile US Core Goal Profile 3.1.1 or prior version  
Argonaut Immunization Profile US Core Immunization Profile 3.1.1 or prior version  
Argonaut Medication Profile US Core Medication Profile 3.1.1 or prior version  
Argonaut MedicationOrder Profile US Core MedicationRequest Profile 3.1.1 or prior version  
Argonaut MedicationStatement Profile -   US Core MedicationStatement Profile not defined in 3.1.1 or prior version
Argonaut Observation Results Profile US Core Laboratory Result Observation Profile 3.1.1 or prior version  
Argonaut Patient Profile US Core Patient Profile 3.1.1 or prior version  
Argonaut Procedure Profile US Core Procedure Profile 3.1.1 or prior version  
Argonaut Smoking Status Observation Profile US Core Smoking Status Observation Profile 3.1.1 or prior version  
Argonaut Vital Signs Observation Profile US Core Vital Signs Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core Blood Pressure Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core BMI Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core Head Circumference Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core Body Height Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core Body Weight Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core Body Temperature Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core Heart Rate Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core Respiratory Rate Profile 4.0.0 Previous to this version, referenced the FHIR Vital Signs Profile
- US Core Pediatric BMI for Age Observation Profile 3.1.1 or prior version 3.1.1 or prior version based on the FHIR Vital Signs Profile, 4.0.0+ based on the US Core Vital Signs Profile
- US Core Pediatric Head Occipital-frontal Circumference Percentile Profile 3.1.1 or prior version 3.1.1 or prior version based on the FHIR Vital Signs Profile, 4.0.0+ based on the US Core Vital Signs Profile
- US Core Pediatric Weight for Height Observation Profile 3.1.1 or prior version 3.1.1 or prior version based on the FHIR Vital Signs Profile, 4.0.0+ based on the US Core Vital Signs Profile
- US Core Pulse Oximetry Profile 3.1.1 or prior version 3.1.1 or prior version based on the FHIR Vital Signs Profile, 4.0.0+ based on the US Core Vital Signs Profile
- US Core DiagnosticReport Profile for Report and Note Exchange 3.1.1 or prior version  
- US Core Encounter Profile 3.1.1 or prior version  
- US Core Location Profile 3.1.1 or prior version  
- US Core Organization Profile 3.1.1 or prior version  
- US Core Practitioner Profile 3.1.1 or prior version  
- US Core PractitionerRole Profile 3.1.1 or prior version  
- US Core Provenance Profile 3.1.1 or prior version  
- US Core Observation Sexual Orientation Profile 5.0.0  
- US Core Observation Social History Profile 5.0.0  
- US Core Observation Survey Profile 5.0.0  
- US Core Observation SDOH Assessment Profile 5.0.0  
- US Core Observation Clinical Test Result Profile 5.0.0  
- US Core QuestionnaireResponse Profile 5.0.0  
- US Core RelatedPerson Profile 5.0.0  
- US Core ServiceRequest Profile 5.0.0  
Extensions      
Sex of patient assigned at birth US Core Birth Sex Extension 3.1.1 or prior version  
Argonaut ethnicity Extension US Core Ethnicity Extension 3.1.1 or prior version  
Argonaut Race Extension US Core Race Extension 3.1.1 or prior version  
- US Core Direct email Extension 3.1.1 or prior version  
- US Core Extension Questionnaire URI 5.0.0  
- US Core Gender Identity Extension 5.0.0  
      * see all versions of US Core in the Directory of published versions

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

A comparison between Argonaut Data Query Profiles and this version of US Core is available as CSV or Excel files and links are provided 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 on their FHIR endpoint (e.g., “DSTU2” or “R4” path component or separate files based on version). However 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

In some FHIR servers the identifier of the underlying clinical data is not maintained across FHIR versions. Client applications must plan on deduplication methods that don’t rely on a common identifier across FHIR versions.

  • Servers should maintain a stable common identifier for a resource across versions.

Expectation that DSTU2 Data is Preserved in R4

In an upgraded R4 endpoint any data in DSTU2 should be in 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 in 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 not be degraded between versions.
  • 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

  • Separate authorization is required
    • There is no expectation that DSTU2 authorizations will work on R4 endpoints and reauthorization is required when migrating between versions.
      • Maintaining the same auth server for both endpoints so that the refresh token is valid for both DSTU2 the R4 endpoint as well may be possible but not in scope.
  • The new endpoint will bring additional/changed resource types and added scopes