US Core Implementation Guide
10.0.0-ballot - STU 10 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 10.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

Plain Language Summary goes here

Home

Official URL: http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core Version: 10.0.0-ballot
IG Standards status: Trial-use Maturity Level: 3 Computable Name: USCore
Other Identifiers: OID:2.16.840.1.113883.4.642.40.2

The January 2027 ballot addresses the following

todo.png

  • USCDI-related Updates: We have updated US Core to include the new U.S. Core Data for Interoperability (USCDI) v7 Data Elements and Classes that the Office of the National Coordinator for Health Information Technology (ONC) published. USCDI v7 includes 30 new data elements and one significantly revised data element (Tobacco and Nicotine Product Use, an evolution of the Smoking Status data element) for a total of 31 overall new data elements across multiple data classes:

    • Of the 31 overall new data elements, the following 14 data elements are already represented in in US Core as Must Support or Additional USCDI elements, and no changes were introduced in this version:

      USCDI v7 Data Element US Core Profile US Core element
      Condition Status US Core Condition Problems and Health Concerns Profile Condition.clinicalStatus
      Deceased Indicator US Core Patient Profile Patient.deceased[x] (Additional USCDI)
      Device Type US Core Device Profile Device.type
      Diagnostic Report Date and Time US Core DiagnosticReport Profile for Laboratory Results Reporting
      US Core DiagnosticReport Profile for Report and Note Exchange      		 DiagnosticReport.issued
      Facility Telecom US Core Location Profile Location.telecom
      Health Insurance Coverage Period US Core Coverage Profile Coverage.period
      Health Insurance Payer US Core Coverage Profile Coverage.payor
      Health Insurance Plan US Core Coverage Profile Coverage.class:plan
      Health Insurance Plan Identifier US Core Coverage Profile Coverage.class:plan.value
      Coverage.class:plan.name
      Immunization Record Source US Core Immunization Profile Immunization.primarySource
      Immunization Status US Core Immunization Profile Immunization.status
      Medication Dispense Quantity US Core MedicationRequest Profile
      US Core MedicationDispense Profile      		 MedicationRequest.dispenseRequest.quantity
      MedicationDispense.quantity
      Patient Identifier US Core Patient Profile Patient.identifier
      Procedure Status US Core Procedure Profile Procedure.status

    • For the USCDI Allergy Intolerance Criticality data element, we added AllergyIntolerance.criticality to the US Core AllergyIntolerance Profile as an Additional USCDI element.

    • For the USCDI Healthcare Agent data element, we added guidance to the US Core CareTeam Profile and the US Core RelatedPerson Profile on recording the person legally authorized to make healthcare decisions for a patient. CareTeam.participant.role is bound to a new US Core value set that adds the durable power of attorney (DPOWATT), healthcare power of attorney (HPOWATT), and Patient Healthcare agent (LOINC 81335-2) codes to Care Team Member Function, and the RelatedPerson.relationship binding strength is raised from preferred to extensible. Note that the US Core Care Team Member Function value set is pending authoring in VSAC. Until it is published, CareTeam.participant.role is bound to a placeholder value set that does not resolve, and validation reports that the value set cannot be found.

    • For the USCDI Referral Note data element, we added Referral Note (LOINC 57133-1) to the "Common Clinical Notes" list on the Clinical Notes guidance page and to the US Core Clinical Note Type value set, raising the minimum set of note types servers support from ten to eleven.

    • For the USCDI Tobacco and Nicotine Product Use data element, which USCDI v7 renamed and broadened from Smoking Status, we renamed the US Core Smoking Status Observation Profile to the US Core Tobacco And Nicotine Use Observation Profile and updated its description for the expanded scope. The value sets bound to Observation.status, Observation.code and Observation.value[x] have also been renamed to US Core Tobacco And Nicotine Observation Status, Tobacco And Nicotine Use Status, and Tobacco And Nicotine Use. Note that the review to add codes to those value sets for broader tobacco and nicotine coverage is pending in VSAC.

    • For the USCDI Nutrition Assessment data element, we added guidance to the Screening and Assessments page on recording nutrition assessments using the existing Screening and Assessments framework, and added a new category code, "nutrition-assessment", to the US Core Category code system and to the US Core Screening Assessment Observation Category value set, the minimum set of category codes servers support for the USCDI Health Status Assessments data class. Note that the terminology for this data element is still pending a decision. The new US Core Nutrition Assessment value set is a placeholder containing the panel items of the LOINC Nutrition assessment panel (75282-4) and is expected to change.

    • For the USCDI Reason Not Performed data element, we:
      • added Procedure.statusReason to the US Core Procedure Profile as a Must Support element, and preadopted the FHIR R5 Procedure.recorded element as a cross-version extension and an Additional USCDI element.
      • raised the binding strength of Immunization.statusReason on the US Core Immunization Profile from example to extensible.
      • raised the patient + status combination search API conformance to SHALL for both profiles.
      • The US Core MedicationAdministration Profile is also in scope for this data element and is addressed in the USCDI Medication Administration data element below.

      Note that the bindings are provisional, pending the review of the terminology aligned with the HL7 FHIR US Quality Core Implementation Guide.

    • For the USCDI Specimen Collection Date and Time and Specimen Collection Method data elements, we added Specimen.collection.collected[x] and Specimen.collection.method to the US Core Specimen Profile as Additional USCDI elements. Note that Observation.effective[x] on the US Core Laboratory Result Observation Profile is already a Must Support element and also maps to Specimen Collection Date and Time.

    • For the USCDI Referral Order data element, we added Patient referral (procedure) (SNOMED CT 3457005) to the US Core ServiceRequest Category Codes value set and added guidance to the US Core ServiceRequest Profile recommending it as the ServiceRequest.category code for referral orders. The ServiceRequest.code binding remains unconstrained, as it is for the USCDI Procedure Order data element.

    • For the USCDI Appointment data element, we added a new US Core Appointment Profile that sets minimum expectations for recording, searching, and fetching a healthcare event scheduled for a past, current, or future date and time. Appointment.identifier, Appointment.status, Appointment.serviceType, Appointment.start, Appointment.end, Appointment.participant.type, Appointment.participant.actor, and Appointment.participant.status are Must Support elements, and the US Core Patient Profile, US Core Practitioner Profile, and US Core Location Profile are Must Support Appointment.participant.actor targets. The Location target also conveys the facility where the scheduled event is to take place. We also added Encounter.appointment to the US Core Encounter Profile as an Additional USCDI element so an encounter records the appointment that scheduled it. Note that the Appointment.serviceType binding is example, since appointment service types are typically drawn from a local service catalog. It names the IHE Scheduling profile's SNOMED CT services value set, which is not published in a package US Core depends on, so validation reports that the value set cannot be found.

    • For the USCDI Medication Administration data element, we added a new US Core MedicationAdministration Profile that sets minimum expectations for recording, searching, and fetching the event of a patient consuming or otherwise being given a medication. MedicationAdministration.status, MedicationAdministration.statusReason, MedicationAdministration.medication[x], MedicationAdministration.subject, MedicationAdministration.effective[x], MedicationAdministration.performer.actor, MedicationAdministration.request, MedicationAdministration.dosage.text, MedicationAdministration.dosage.route, and MedicationAdministration.dosage.dose are Must Support elements, with MedicationAdministration.effective[x] a Must Support choice of dateTime and Period and the US Core Patient Profile and US Core Practitioner Profile as Must Support MedicationAdministration.subject and MedicationAdministration.performer.actor targets. The medication terminology matches the US Core MedicationRequest Profile and the US Core MedicationDispense Profile, and neither of those profiles changed. MedicationAdministration.statusReason also addresses the USCDI Reason Not Performed data element. The Medication List guidance for accessing a patient's medications is unchanged and remains based on MedicationRequest. Note that the MedicationAdministration.statusReason binding is provisional, pending the review of the terminology aligned with the HL7 FHIR US Quality Core Implementation Guide.

    • For the USCDI Medical Device Order data element, we added a new US Core DeviceRequest Profile that sets minimum expectations for recording, searching, and fetching an order for a medical device for a patient. DeviceRequest.status, DeviceRequest.intent, DeviceRequest.code[x], DeviceRequest.subject, DeviceRequest.authoredOn, and DeviceRequest.requester are Must Support elements, with DeviceRequest.code[x] a Must Support choice of CodeableConcept and Reference(US Core Device Profile), and the US Core Patient Profile and US Core Practitioner Profile as Must Support DeviceRequest.subject and DeviceRequest.requester targets. Because DeviceRequest.code[x] is a choice, a Server supports at least one of DeviceRequest.codeCodeableConcept and DeviceRequest.codeReference and a Client supports both. Guidance notes that a medical device order might instead be represented with the US Core ServiceRequest Profile or the US Core MedicationRequest Profile, depending on whether the request is procedure focused or medication related. Note that the DeviceRequest.codeCodeableConcept binding is strengthened from the base FHIR example to preferred rather than naming a required vocabulary; HCPCS was considered and declined, since durable medical equipment orders are often descriptive and USCDI names no vocabulary standard for this data element.

    • For the USCDI Nutrition Order data element, we added a new US Core NutritionOrder Profile that sets minimum expectations for recording, searching, and fetching an oral diet order for a patient. NutritionOrder.status, NutritionOrder.intent, NutritionOrder.patient, NutritionOrder.dateTime, NutritionOrder.orderer, NutritionOrder.oralDiet, and NutritionOrder.oralDiet.type are Must Support elements, with the US Core Patient Profile and US Core Practitioner Profile as Must Support NutritionOrder.patient and NutritionOrder.orderer targets, and NutritionOrder.oralDiet.instruction as an Additional USCDI element. The profile constrains only the oral diet, so no element of NutritionOrder.supplement or NutritionOrder.enteralFormula is Must Support. Guidance notes that a nutrition order might instead be represented with the US Core ServiceRequest Profile or the US Core MedicationRequest Profile depending on context, that providing the diet is recorded with the US Core Procedure Profile, and that findings about what a patient has eaten are recorded as nutrition assessments on the Screening and Assessments page. Note that the NutritionOrder.oralDiet.type binding to the FHIR Diet Type value set is strengthened from the base FHIR example strength to preferred. That value set selects the SNOMED CT descendants of 182922004 (Dietary regime). These value sets are expected to move from the FHIR specification to the HL7 Terminology (THO), and US Core will use the THO value set as the preferred binding if it is published before this guide is published.

    • For the USCDI Diagnostic Imaging Reference data element, we added a new US Core ImagingStudy Profile and marked elements on two existing profiles as Additional USCDI elements. The new profile is deliberately slim and sets minimum expectations only for the information needed to locate or access a diagnostic imaging study: ImagingStudy.identifier, ImagingStudy.status, ImagingStudy.subject, and ImagingStudy.endpoint are Must Support elements, with the US Core Patient Profile as the Must Support ImagingStudy.subject target. ImagingStudy.identifier is sliced into an accession number slice, which is Must Support, and a DICOM Study Instance UID slice, which is neither mandatory nor Must Support and establishes a path for a future version. Guidance describes how an endpoint is used, since an endpoint can launch a remote picture archiving and communication system (PACS) or viewer, provide a patient- or provider-accessible viewer, or enable transfer and retrieval, and the receiving system is not assumed to contain a viewer itself. Neither ImagingStudy.series nor ImagingStudy.modality is constrained. On the US Core DiagnosticReport Profile for Report and Note Exchange we added DiagnosticReport.identifier, DiagnosticReport.basedOn, DiagnosticReport.imagingStudy, and DiagnosticReport.media.link as Additional USCDI elements, with the new US Core ImagingStudy Profile and the US Core ServiceRequest Profile as Must Support reference targets. DiagnosticReport.media and DiagnosticReport.media.link were Must Support before version 8.0.0 and return here as Additional USCDI elements. Guidance states that the reference to an ImagingStudy, with its endpoint information, is the principal mechanism for meeting this data element, and that supporting DiagnosticReport.media.link is not a substitute for meeting it. On the US Core ServiceRequest Profile we added ServiceRequest.identifier as an Additional USCDI element, because an imaging accession number originates with the order and is what ties the order, the report, and the imaging study together. The search API adds patient + identifier as SHALL for ImagingStudy and SHOULD for DiagnosticReport and ServiceRequest, so a known accession or business identifier can be used to locate the corresponding study, report, or order.

    • For the USCDI Accommodation data element, we added a new US Core Patient Accommodation Profile, an Observation that records the supports and services a patient needs in order to access care, such as a sign language interpreter, a wheelchair-accessible room, or a sensory accommodation. Observation.status, Observation.category, Observation.code, Observation.subject, Observation.effective[x], and Observation.value[x] are Must Support elements, with the US Core Patient Profile as the Observation.subject target and Observation.performer an Additional USCDI element. Observation.value[x] is a Must Support choice of valueCodeableConcept and valueString, so a Server supports at least one and a Client supports both. We added a new category code, "accommodation", to the US Core Category code system for Observation.category. Guidance states that an accommodation records what a patient needs in order to access care, not the patient's disability or functional status, which are recorded as assessments on the Screening and Assessments page. The design team considered reusing the Simple Observation Profile within the Screening and Assessments framework and discarded it as confusing and as breaking the assessments pattern. Note that the terminology for this data element is outstanding in two places. Observation.code is fixed to the placeholder code 55555-5, which is not a real LOINC code; the design team settled on a new prerelease LOINC code for "Accommodation Need" that has not been issued yet, so validation reports the code as unknown until it is replaced. Observation.value[x] carries no binding, because PACIO and Gravity are developing a strawman value set in VSAC. As the terminology matures, US Core will consider removing the free-text option. This profile is the first in the guide marked Incompatible with IPS, which represents the same information with Flag rather than Observation.

    • For the USCDI Adverse Events data class, which is new in USCDI v7 and comprises the Adverse Event Condition and Adverse Event Outcome data elements, we added a new Adverse Events: Clinical Records and Patient Safety Reporting guidance page. US Core does not define an AdverseEvent profile and does not use the FHIR AdverseEvent resource. The information the two data elements describe is already recorded by existing US Core Profiles, and the new page documents which ones and why. Adverse Event Condition is recorded by the US Core AllergyIntolerance Profile, US Core Immunization Profile, both Condition profiles, US Core DocumentReference Profile, US Core Simple Observation Profile, and US Core Procedure Profile; Adverse Event Outcome is recorded by those and additionally by the US Core Encounter Profile and US Core CarePlan Profile. Each of those profile pages gains a bullet pointing at the new page. Two points drive the guidance. First, adverse events are recorded as ordinary clinical events and are not tagged as adverse events, so implementers should not expect a flag, a category code, or a dedicated resource; deciding that an event was adverse, and that a clinical intervention caused it, is a judgment made elsewhere. Second, USCDI v7 scopes this data class to the clinical record and explicitly excludes patient safety analyses, internal risk management documentation, patient safety work products as defined under the Patient Safety and Quality Improvement Act of 2005, and Patient Safety Organization investigations, safety reviews, and facility-level reporting. US Core follows that boundary, which is what the page title distinguishes. The data class is not limited to immunizations and medications, although USCDI notes it includes at least those. No new profile, extension, value set, or example was added for this data class. Note that this guidance page is a draft for this ballot. Further editing and examples are still pending.

Where possible, new and updated pre-publishing content is highlighted with green text and background. This highlighting will be removed prior to publication.

Key updates and detailed changes between this and prior versions are available on the US Core Change Log and Changes Between Versions pages.

Introduction

This guide and the US Core profiles have become the foundation for US Realm FHIR implementation guides. This annual release reflects changes to U.S. Core Data for Interoperability (USCDI) and comments and requests from the US Realm FHIR community. (The US Core Roadmap page outlines this approach to yearly updates.) US Core has benefitted from testing and guidance by the Argonaut Project Team. Their feedback continues to lay the groundwork for documenting the US Core Profile design, interactions, requirements, and guidelines for patient data access and Office of the National Coordinator for Health Information Technology (ONC) Certification testing. Under the guidance of HL7 and the HL7 US Realm Steering Committee, the content will expand in future versions to meet the needs specific to the US Realm.

The US Core Implementation Guide is based on FHIR Version R4. It defines the minimum constraints on the FHIR resources to create the US Core Profiles. The elements, extensions, vocabularies, and value sets that SHALL be present are identified, and how they are used is defined. It also documents the minimum FHIR RESTful interactions for each US Core Profiles to access patient data. Establishing the "floor" of standards to promote interoperability and adoption through common implementation allows for further standards development evolution for specific use cases. There are two different ways to implement US Core:

  1. Profile Only Support: Systems may support only the US Core Profiles to represent clinical information.
  2. Profile Support + Interaction Support: Systems may support both the US Core Profile content structure and the RESTful interactions defined for a resource.

For a detailed description of these different usages of US Core, see the Conformance Requirements page.

Background

The US Core requirements were initially developed, balloted, and published in FHIR DSTU2 as part of the ONC sponsored Data Access Framework (DAF) project. The Argonaut Data Query Implementation Guide superseded DAF and documented security and authorization and the querying of the 2015 Edition Common Clinical Data Set (CCDS) and static documents. US Core descended directly from the Argonaut guide to support FHIR Version STU3 and eventually FHIR R4 and the ONC U.S. Core Data for Interoperability (USCDI). Refer to the USCDI page which maps the US Core versions and profiles to the USCDI versions and Data Elements.

How To Read This Guide

This Guide is divided into several pages, which are listed at the top of each page in the menu bar.

  • Home: The home page provides the introduction and background for US Core.
  • Conformance: These pages describe the set of rules to claim conformance to this guide
    • General Requirements: This page defines requirements common to all actors and profiles used in this guide, including how CapabilityStatements are used to claim conformance.
    • Must Support: This page defines the expectations for mandatory and Must Support elements in the US Core Profiles.
    • Security: This page documents the general security requirements and recommendations for actors.
    • Requirements Table: These tables list the US Core Server and Client requirements defined in the US Core Implementation Guide’s narrative sections.
  • Guidance: The Guidance pages document best practices and how to use the profiles and transactions defined in this guide.
    • USCDI: This page maps the US Core Profiles to the (USCDI) data classes and data elements.
    • General Guidance: This page provides guidance, definitions, and requirements common to all actors and profiles used in this guide.
    • Clinical Notes: This page provides guidance on the interactions between Consumers and Producers of clinical notes.
    • Medication List: This page provides guidance on how a patient or provider can access a patient's medications.
    • Basic Provenance: This page provides implementers with important definitions to create and share the Provenance Resource.
    • Screening and Assessments: This page documents how US Core Profiles are used to represent screenings and assessments for patient health status
    • Relationship With Other IGs: This page outlines the relationship between US Core and other implementation guides, including a detailed comparison with International Patient Access (IPA) and International Patient Summary (IPS).
  • FHIR Artifacts: These pages provide detailed descriptions and formal definitions for all the FHIR objects defined in this guide.
    • Profiles and Extensions: This page lists the US Core Profiles and Extensions defined in this guide to exchange quality data.
      • Each US Core Profile page includes a narrative description that lists all the Mandatory and Must Support data elements, profile-specific implementation guidance, and formal definitions. A "Quick Start" guide summarizes the supported search transactions for each profile. Although the guidance typically focuses on the profiled elements, it also may cover un-profiled elements to aid with implementation and certification.
    • Search Parameters and Operations: This page lists the defined US Core Operations and Search Parameters used in US Core transactions.
    • Terminology: This page lists the US Core ValueSets, and CodeSystems defined for the profiles.
    • Capability Statements and Requirements Resources: These pages define the expected FHIR capabilities and requirements of the US Core Servers and Clients.
    • Examples: This page lists all the examples used in this guide. These examples show what data produced and consumed by systems conforming with this implementation guide might look like. Every effort has been made to ensure that the examples are correct and useful, but they are not a normative part of the specification, nor fully representative of real-world examples.

  • Downloads: This page provides links to downloadable artifacts.

  • Version History: These pages document the changes across the versions of US Core.
    • Change Log: The Change Log lists all the updates, enhancements, clarifications, and corrections resulting from community feedback on US Core ballots and changes to align with evolving USCDI standards.
    • Changes Between Versions: This page documents the changes between US Core versions and documents some considerations when transitioning between versions of FHIR and US Core.
  • Looking Ahead: These pages provide a preview of the future direction of US Core
    • US Core Roadmap: This page outlines the approach to adding new content to US Core.
    • Writing Vital Signs: This page documents how to write vital sign observations using patient- and provider-facing apps.
    • Writing Clinical Notes: This page documents how to write clinical notes using patient- and provider-facing apps.
    • Patient Data Feed: This page documents how to use FHIR Subscriptions to be notified when events related to US Core content occur.

US Core Actors

The following actors are part of the US Core IG:

US Core Requestor

A US Core Requester is an application that initiates a data access request to retrieve patient data. The US Core Requestor is the Client in a Client-Server interaction. The terms "US Core Requestor" and "Client" are used interchangeably throughout this guide and are not meant to limit this actor to only patient and provider apps. For example, payers and other users can use the same technology. These terms are a short-hand notation for "user application".

US Core Responder

A US Core Responder is a system that responds to the data access request providing patient data. The US Core responder is the Server in a Client-Server interaction. The terms "US Core Responder", "Server", and "EHR" are used interchangeably throughout this guide and are not meant to limit this actor to electronic health record systems. For example, HIEs, care coordination platforms, population health systems, etc., can use the same technology. These terms are a short-hand notation for "interoperable healthcare platform".

US Core Profiles

Below is the list of US Core Profiles. Each profile identifies which core elements, extensions, vocabularies, and ValueSets SHALL be present in the resource when using this profile. Together, they promote interoperability and adoption through common implementation and provide the floor for standards development for specific use cases. See the USCDI page, for a mapping to the U.S. Core Data for Interoperability (USCDI).

A simple narrative summary gives each profile's requirements and guidance. A formal hierarchical table presents a logical view of the content in both a differential and snapshot view, and provides references to appropriate terminologies and examples.

AllergyIntolerance

Appointment

CarePlan

CareTeam

Condition

Coverage

Device

DeviceRequest

DiagnosticReport

DocumentReference

Encounter

FamilyMemberHistory

Goal

ImagingStudy

Immunization

Location

Medication

MedicationAdministration

MedicationDispense

MedicationRequest

NutritionOrder

Observation

Organization

Patient

Practitioner

PractitionerRole

Procedure

Provenance

QuestionnaireResponse

RelatedPerson

ServiceRequest

Specimen

US Core FHIR RESTful interactions

For systems that support the US Core Profile content structure and the RESTful interactions defined for a resource, the requirements are formally defined in the US Core CapabilityStatements. In addition, each profile page has a Quick Start Section that documents the required FHIR RESTful search and read operations. These sections demonstrate how to access a patient's clinical and administrative data:

Example of a simple FHIR RESTful Search Transaction
basic_fhir_restful_interaction.svg

See the FHIR specification for details on FHIR RESTful Search API and the SMART App Launch for how an application gets access to a patient record.

Primary Authors: Brett Marquard, Eric Haas, Gay Dolin