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
| 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
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 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.valueCoverage.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.quantityMedicationDispense.quantity |
| Patient Identifier | US Core Patient Profile | Patient.identifier |
| Procedure Status | US Core Procedure Profile | Procedure.status |
New Profiles:
For the new USCDI Appointment Data Element, we added the US Core Appointment Profile. We also added Encounter.appointment to the US Core Encounter Profile as an Additional USCDI element to link an encounter to the appointment that scheduled it.
For the new USCDI Medication Administration Data Element, we added the US Core MedicationAdministration Profile. MedicationAdministration.statusReason also supports the new USCDI Reason Not Performed Data Element. The Medication List guidance is unchanged and remains based on MedicationRequest.
For the new USCDI Medical Device Order Data Element, we added the US Core DeviceRequest Profile with profile-specific guidance that a medical device order may instead be represented using other request resources too.
For the new USCDI Nutrition Order Data Element, we added the US Core NutritionOrder Profile for oral diet orders with profile-specific guidance that a nutrition order may instead be represented using other request resources too.
DiagnosticReport.identifier, DiagnosticReport.basedOn, DiagnosticReport.imagingStudy, and DiagnosticReport.media.link to the US Core DiagnosticReport Profile for Report and Note Exchange as Additional USCDI elements.ServiceRequest.identifier to the US Core ServiceRequest Profile as an Additional USCDI element.patient + identifier combination search API requirements.New Elements and Terminology:
For the new USCDI Allergy Intolerance Criticality Data Element, we added AllergyIntolerance.criticality to the US Core AllergyIntolerance Profile as an Additional USCDI element.
For the new USCDI Healthcare Agent Data Element, we added healthcare agent codes to the US Core CareTeam Profile's Care Team Member Function value set, and changed US Core RelatedPerson Profile's RelatedPerson.relationship binding from preferred to extensible. For both profiles, we added guidance on recording the person legally authorized to make healthcare decisions for a patient.
Many USCDI Clinical Notes are already supported in US Core. For the new USCDI Referral Note Data Element, we added Referral Note (LOINC 57133-1) to the "Common Clinical Notes" list and to the US Core Clinical Note Type value set.
For the USCDI Tobacco and Nicotine Product Use Data Element, which replaces Smoking Status, we renamed the US Core Smoking Status Observation Profile to the US Core Tobacco And Nicotine Use Observation Profile. We also renamed the value sets bound to Observation.status, Observation.code, and Observation.value[x] to US Core Tobacco And Nicotine Observation Status, Tobacco And Nicotine Use Status, and Tobacco And Nicotine Use.
For the new USCDI Nutrition Assessment Data Element, we added the "nutrition-assessment" category code to the US Core Category code system and to the US Core Screening Assessment Observation Category value set. We also added guidance on recording nutrition assessments to the Screening and Assessments page.
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.Immunization.statusReason terminology to an extensible binding to the HL7 Terminology (THO) ActNoImmunizationReason value set.patient + status combination search API requirements to SHALLFor the new 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.
ServiceRequest.category for referral orders.New Guidance:
Individual Level Provenance: We updated the individual provenance table on the Basic Provenance page adding an Author Time Stamp column naming, for each profile, the element that records when the information was first captured. We added the following previously omitted Author Time Stamp elements as Additional USCDI.
| US Core Profile | Author Time Stamp Element |
|---|---|
| US Core AllergyIntolerance Profile | AllergyIntolerance.recordedDate |
| US Core CarePlan Profile | CarePlan.created |
| US Core FamilyMemberHistory Profile | FamilyMemberHistory.date |
| US Core Immunization Profile | Immunization.recorded |
These resources are based on FHIR R5 and define the types of systems covered by this implementation guide.
Writing Documents: in the Looking Ahead Section, we updated the Writing Clinical Notes page to Writing Documents which defines a US Core approach to writing any document type, such as clinical notes, insurance cards, and advance directives to a FHIR server as DocumentReference resources. It is based on the 2026 Argonaut-sponsored FHIR Write - DocumentReference project.
Terminology: We continue aligning terminology between US Core and HL7 C-CDA and, where needed, linking it to the FHIR® Terminology Service for VSAC Resources (Value Set Authority Center (VSAC)) or HL7 Terminology (THO). The following value set has been moved:
| Pre 10.0.0 US Core ValueSet | 10.0.0 ValueSet | THO/VSAC |
|---|---|---|
| US Core Goal Codes | VSAC 2.16.840.1.113762.1.4.1267.46 | VSAC |
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.
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:
For a detailed description of these different usages of US Core, see the Conformance Requirements page.
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.
This Guide is divided into several pages, which are listed at the top of each page in the menu bar.
Downloads: This page provides links to downloadable artifacts.
The following actors are part of the US Core IG:
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".
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".
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.
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:
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