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

Implementation Guide HomePage

Change Notes for Ver 3.1.1 Technical Errata to US Core For Review:

This update addresses several technical corrections and errata and clarifications listed below. They have been reviewed and voted on by the members of the HL7 International Cross-Group Projects WorkGroup which is sponsoring this errata release and reconciliation of the comments. To make a comment against a particular errata:

  1. Create a new Jira tracker (New trackers can be made by clicking on the link in the page footer entitled “Propose a change”
  2. Reference the tracker in the Advanced Tab’s Related Issues field
  3. add “US-Core-Errata” in the Advanced Tab’s Grouping field

(see example tracker)

review of this errata release are limited to these items. If you wish to comment on other content in this guide which are outside the scope of this errata release, you can log a new tracker for future consideration. :

There are several outstanding ig publishing qa issues for this release which are summarized here. These are currently being resolved in cooperation with the FHIR ig publishing team.

  1. review period comments Add guidance for representing patient name suffix and previous patient name to the US Core Patient Profile (FHIR-28129)

  2. review period comments Correct copy/paste error in Goal Profile (FHIR-28109)

  3. Correct US Core Provider Speciality (NUCC) ValueSet to hide abstract grouping codes (FHIR-27975)

  4. Added example of US Core Direct Extension to Practitioner-2 Example (FHIR-27947)

  5. Corrected technical errors in pediatric profiles StructureDefinitions (FHIR-27946)

  6. Corrected errors in DiagnosticReport Cardiology Example (FHIR-27913)

  7. Update Federal Register link for OMB race and ethnicity category classifications. (FHIR-27907)

  8. Clarified token search syntax (FHIR-27897).

  9. Corrected US Core DocumentReference Profile to support multiple attachments (FHIR-25778).

  10. Fix FHIRPath Expression in USCoreGoalTargetDate (FHIR-27892).

  11. Fix FHIRPath Expression in USCoreProcedureDate(FHIR-27887).

  12. Add omitted “ge” comparators to SearchParameters (FHIR-27893).

  13. Remove Must Support References to non US Core Profiles (FHIR-27876)

  14. Add missing reaction to the US Core AllergyIntolerance Profile (FHIR-27867).

  15. Clarify reference to US Core Patient in Vitals Signs Profiles (FHIR-27857).

  16. Corrected US Core Pulse Oximetry Profile component.valueQuantity.code and component.valueQuantity.unit min from 0 to 1 to be consistent with the valueQuantity constraints within US Core (FHIR-27846)

  17. Correct UCUM Unit in US Core Pulse Oximetry Profile Text Summary (FHIR-27845)

  18. Update Procedure Codes Value Set to include ICD-10 PCS codes (FHIR-27836)

  19. Update Procedure Codes Value Set to include CDT codes (FHIR-27737)

  20. Clarify that pediatric vital sign percentile Observations should reference growth chart (FHIR-27549),

  21. Added Missing US core Head Occipital-frontal Circumference Percentile Profile (FHIR-27542).

  22. Correct requirements for supporting CLIA identifiers (FHIR-27158)

  23. Change Description of ICD-10-PCS Value Set (FHIR-27116)

  24. Correct AllergyIntolerance guidance for verificationStatus (FHIR-27096)

  25. Fix example US Core heart-rate example (FHIR-27086)

  26. review period comments Update smoking status codes to align with USCDI (FHIR-27082).

  27. Fix invariant provenance-1 (FHIR-27065)

  28. Fix invalid json snippet (FHIR-27001)

  29. review period comments Remove Provenance requirement from Medication, Location, Practitioner, PractitionerRole, and Organization and correct copy and paste error to Medication and Provenance searchType support in CapabilityStatement (FHIR-26840, FHIR-28161).

  30. Correction on USCDI Table change ‘MedicationStatement’ to ‘MedicationRequest’ and remove references to MedicationStatement in the Medication Profile and CapabilityStatements (FHIR-26840).

  31. Clarify that US Core Location/PractitionerRole are not being referenced by other resources (FHIR-26840).

  32. Correct editing error restoring Write and Operation capability guidance into DocumentReference QuickStart (FHIR-26840).

  33. Clarify guidance that servers SHALL support search with status if status required (FHIR-26840).

  34. Correct canonical url for ImplementationGuide (FHIR-26686).

  35. Correct system URI for ICD-10 procedure codes (FHIR-26679).

  36. Fix invariant us-core-1 (FHIR-26605).

  37. Change valueCode min from 0 to 1 for US Core Birth Sex Extension and valueBoolean min from 0 to 1 forUS Core Direct email Extension (FHIR-26459).

  38. Change valueQuantity min from 1 to 0 for US Core Pediatric BMI for Age Observation Profile and US Core Pediatric Weight for Height Observation Profile (FHIR-26363).

  39. Add page contents to Clinical Notes and Basic Provenance pages (FHIR-25785).

  40. Fix duplicate URL causing validation failure. (FHIR-25536).

  41. Fix Invariant us-core-8 (FHIR-25459).

  42. Corrected the wording “should support” to “shall support” in Clinical Notes Guidance (FHIR-25455).

  43. Fix Invariant us-core-8 to allow for Data Absent Reason Extension on Patient name.(FHIR-25249).

  44. Fix Link to LOINC LP29708-2 (FHIR-25213).

  45. Corrected guidance for conveying “Patient-Reported medications” (FHIR-25035).


The US Core Implementation Guide is based on FHIR Version R4 and defines the minimum conformance requirements for accessing patient data. The Argonaut pilot implementations, ONC 2015 Edition Common Clinical Data Set (CCDS), and ONC U.S. Core Data for Interoperability (USCDI) v1 provided the requirements for this guide. The prior Argonaut search and vocabulary requirements, based on FHIR DSTU2, are updated in this guide to support FHIR Version R4. This guide was used as the basis for further testing and guidance by the Argonaut Project Team to provide additional content and guidance specific to Data Query Access for purpose of ONC Certification testing. These profiles are the foundation for future US Realm FHIR implementation guides. In addition to Argonaut, they are used by DAF-Research, QI-Core, and CIMI. 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.

These requirements were originally developed, balloted, and published in FHIR DSTU2 as part of the Office of the National Coordinator for Health Information Technology (ONC) sponsored Data Access Framework (DAF) project. For more information on how DAF became US Core see the US Core change notes.

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 HL7 FHIR® US Core Implementation Guide.
  • Guidance: These pages provides overall guidance in using the profiles and transactions defined in this guide.
    • General Guidance provides guidance, definitions and requirements common to all HL7 FHIR® US Core Implementation Guide actors used in this guide.
    • Clinical Notes Guidance gives guidance on the interactions between Consumers and Producers of clinical notes.
    • Medication List Guidance gives guidance on how a patient or provider can access a patient’s medications.
    • Basic Provenance provides implementers with important definitions to create and share the Provenance Resource.
    • DSTU2 to R4 Conversion considers the user and developer experience when transitioning from FHIR DSTU2 to FHIR R4.
    • Future of US Core outlines the approach to adding new content to HL7 FHIR® US Core Implementation Guide.
  • FHIR Artifacts: These pages provides detailed descriptions and formal definitions for all the FHIR objects defined in this guide.
    • Profiles and Extensions: This page lists the set of Profile and Extension that are defined in this guide to exchange quality data. Each Profile page includes a narrative introduction, formal definition and a “Quick Start” guide to the supported search transaction for each HL7 FHIR® US Core Implementation Guide Profile.
    • Search Parameters and Operations: This page lists the HL7 FHIR® US Core Implementation Guide defined Operations and Search Parameters that are used in US Core transactions.
    • Terminology: This page lists the value sets and code system defined for HL7 FHIR® US Core Implementation Guide profiles.
    • Capability Statements: This set of pages describes the expected FHIR capabilities of the various HL7 FHIR® US Core Implementation Guide actors.
  • Security: General security requirements and recommendations for HL7 FHIR® US Core Implementation Guide actors.
  • Examples: List of links to all the examples used in this guide.
  • Downloads: This page provides links to downloadable artifacts.

US Core Actors

The following actors are part of the US Core IG:

  • US Core Requestor: An application that initiates a data access request to retrieve patient data. This can be thought of as the client in a client-server interaction.
  • US Core Responder: A product that responds to the data access request providing patient data. This can be thought of as the server in a client-server interaction.

US Core Profiles

The list of US Core Profiles is shown below. Each profile defines the minimum mandatory elements, extensions and terminology requirements that MUST be present. For each profile, requirements and guidance are given in a simple narrative summary. A formal hierarchical table that presents a logical view of the content in both a differential and snapshot view is also provided along with references to appropriate terminologies and examples. For each US Core Profile, an overview of the required set of RESTful FHIR interactions - for example, search and read operations - is provided in the Quick Start Section of the profile page.

  • US Core AllergyIntolerance Profile
  • US Core CarePlan Profile
  • US Core CareTeam Profile
  • US Core Condition Profile
  • US Core DiagnosticReport Profile for Laboratory Results Reporting
  • US Core DiagnosticReport Profile for Report and Note exchange
  • US Core DocumentReference Profile
  • US Core Encounter Profile
  • US Core Goal Profile
  • US Core Immunization Profile
  • US Core Implantable Device Profile
  • US Core Laboratory Result Observation Profile
  • US Core Location Profile
  • US Core Medication Profile
  • US Core MedicationRequest Profile
  • US Core Organization Profile
  • US Core Patient Profile
  • US Core Pediatric BMI for Age Observation Profile
  • US Core Pediatric Head Occipital-frontal Circumference Percentile Profile
  • US Core Pediatric Weight for Height Observation Profile
  • US Core Practitioner Profile
  • US Core PractitionerRole Profile
  • US Core Procedure Profile
  • US Core Provenance Profile
  • US Core Pulse Oximetry Profile
  • US Core Smoking Status Observation Profile
  • See the General Guidance page for a mapping to the U.S. Core Data for Interoperability (USCDI).

    US Core Conformance Requirements

    The Capability Statements page outlines conformance requirements and expectations for the US Core Servers and Client applications, identifying the specific profiles and RESTful transactions that need to be supported. Note that the individual US Core profiles identify the structural constraints, terminology bindings and invariants. Similarly, the individual US Core SearchParameter and Operation resources specify how they are understood by the server. However, implementers must refer to the CapabilityStatement for details on the RESTful transactions, specific profiles and the search parameters applicable to each of the US Core actors.

    Primary Authors: Brett Marquard, Eric Haas

    Secondary Authors: Grahame Grieve, Nagesh Bashyam