US Core Implementation Guide
3.2.0 - CI build

US Core Implementation Guide, published by HL7 International - US Realm Steering Committee. This is not an authorized publication; it is the continuous build for version 3.2.0). This version is based on the current content of and changes regularly. See the Directory of published versions


punch list:

  • Finish [Resolving Trackers]
  • Finish Applying Resolved Trackers
  • QA
    • [] review applied trackers
    • errors and warnings

Where possible, new and updated content will be highlighted with green text and background

Continuous Integration Build for US Core (latest in version control)

The January 2021 Ballot comment resolutions have been voted on by the members of the sponsoring work group HL7 International Cross-Group Projects.

January 2021 Ballot comments and links to the updated content

Listed below are the resolved trackers for this version:

Status: Summary:(Jira Issue) Link to Change

  1. Applied:Update PractitionerRole.practitioner to )..1 MS (FHIR-29681) See Change Here
  2. Triaged:CareTeam Mandatory Search composite OR search (FHIR-29768) See Change Here
  3. Applied:Provide guidance on the population of narrative (FHIR-29777) See Change Here
  4. Applied: Change $docref start and end input parameter types from date to dateTime (FHIR-29825) See Change Here
  5. Resolved - change required:The history file markdown rendering of the table (FHIR-30100) See Change Here
  6. Applied:footnote rendering - pre-applied (FHIR-30101) See Change Here
  7. Triaged:Random Section Numbering (Reminder for tooling issue) (FHIR-30102) See Change Here
  8. Applied:Move section 1.5 US Core Conformance Requirements (FHIR-30103) See Change Here
  9. Resolved - change required:imm-1.json NDC/CVX codes QA Error (FHIR-30104) See Change Here
  10. Resolved - change required:Patient Examples QA Errors: CDCREC code system in VSAC (FHIR-30105) See Change Here
  11. Resolved - change required:Procedure Example QA Issue - code system not found (FHIR-30106) See Change Here
  12. Resolved - change required:valueset-simple-language.xml QA Error (FHIR-30107) See Change Here
  13. Applied:Make custodian optional on document reference (FHIR-30108) See Change Here
  14. Triaged:Remove required binding on procedure and condition (FHIR-30109) See Change Here
  15. Applied:Update DocumentReference CCD operation (FHIR-30110) See Change Here
  16. Applied:Update DocumentReference MustSupport to choice of data or url (FHIR-30111) See Change Here
  17. Resolved - change required:Reference to 3 new document types - addressing corresponding metadat (FHIR-30112) See Change Here
  18. Applied:Typo (FHIR-30113)
  19. Applied:Clarify Must Support of Complex elements (FHIR-30321) See Change Here
  20. Triaged:DiagnosticReport for Laboratory Result Reporting issued should be optional (FHIR-30328) See Change Here
  21. Applied:Clarify that VSAC FHIR API only retrieves a definition (FHIR-30344) See Change Here
  22. Applied:Allergy Intolerance example for UNKNOWN allergy status does not use unknown (FHIR-30345) See Change Here
  23. Applied:Corrected allergy intolerance example SNOMED CT code (FHIR-30346) See Change Here
  24. Triaged:Need to change the value set used for drug classes (FHIR-30347) See Change Here
  25. Applied:Clarify plans to align with Gender Harmony(FHIR-30350) See Change Here
  26. Applied:Typos on Conformance Expectations Page (FHIR-30353) See Change Here
  27. Applied:clarify use of additional codings (FHIR-30354) See Change Here
  28. Applied:Clarify server requirements for Choice of Profile Elements scenario (FHIR-30355) See Change Here
  29. Applied:Add all options to Procedure.performedx See Change Here
  30. Applied:Updated MedicationRequest.authoredOn from mandatory to must support(FHIR-30430) See Change Here
  31. Applied:Typo (FHIR-30460) See Change Here
  32. Applied: Update Encounter Type CPT Description (FHIR-30470) See Change Here
  33. Applied: Clarify Missing Data language for coded data elements with required binding strength (FHIR-30630) See Change Here
  34. Resolved - change required:Reference codes as an aid(FHIR-30654) See Change Here
  35. Applied:Change URL for Healthcare Common Procedure Coding System (HCPCS) level II alphanumeric codes(FHIR-30655) See Changes Here and Here
  36. Applied:Typo (FHIR-30656)
  37. Applied: Explain the relationship between US CORE and an evolving USCDI. (FHIR-30657) See Change Here
  38. Applied:Correct 2 bullet points in section 1.2. (FHIR-30658) See Change Here
  39. Applied:Clarify actors (FHIR-30659) See Change Here
  40. Applied:Edit basic provenance (FHIR-30660) See Change Here
  41. Applied:Clarify the duplication requirement for scanned documents in DocumentReference and DiagnosticReport. (FHIR-30662) See Change Here
  42. Triaged:Clarify that developers and implementers will retain data visualization between DSTU2 to R4 upgrades. (FHIR-30665) See Change Here
  43. Applied:Add provenance to writing/updating guidance? (FHIR-30666) See Change Here
  44. Applied:Clarify Code System section and update codesystem table (FHIR-30667) See Change Here
  45. Resolved - change required::Clarify that the manufacturer and model information is available, it SHOULD be included to support historical reports of implantable medical devices. (FHIR-30669) [See Change Here
  46. Resolved - change required:Clarify that servers are not required to support both udi_HRF and udi_AIDC but they SHALL support at least one of these elements. (FHIR-30670) See Change Here
  47. Applied: Clarify UDI information. (FHIR-30672) See Change Here
  48. Applied:Clarify text (FHIR-30673) See Change Here
  49. Applied:Typos (FHIR-30674)
  50. Applied:Clarify prohibition on using contained resources. (FHIR-30677) See Change Here
  51. Applied:Add guidance on suppressed data. (FHIR-30678) See Change Here
  52. Applied:Clarify what is meant by “support the other elements.” (FHIR-30680) See Change Here
  53. Applied:Typo(FHIR-30681)
  54. Applied:Fix typos (FHIR-30683) Various Changes
  55. Resolved - change required:Update on Guidance on DataAbsentReason for Observations (FHIR-30685) See Change Here
  56. Applied:Clarify use of qualifier LOINCs (FHIR-30690) See Change Here
  57. Applied: Fix Typo (FHIR-30695) See Change Here
  58. Applied: Update on Guidance on DataAbsentReason for Observations (FHIR-30699) See Change Here
  59. Applied:Clarify what is intended with “additional observations”(FHIR-30772) See Change Here
  60. Applied:Add statement about clinical safety to the security page (FHIR-30776) See Change Here
  61. Applied:Added clarification to vitals profile regarding use of additional codings and component observations. (FHIR-30778) See Change Here
  62. Resolved - change required:In most of the data elements – “Binding is from base FHIR and US Core Vital Signs” Need this to be one single combined listing (FHIR-30780) See Change Here
  63. Resolved - change required:Typo grammar. All codes SHALL have an system value. Correction “a value system”. (FHIR-30782) See Change Here
  64. Resolved - change required:Confusing for commercial vendor. Reads very confusing. (FHIR-30783) See Change Here
  65. Resolved - change required:Loosen the requirement for including patient or state clearly on the home page that US Core is insufficient for many public health use cases. (FHIR-30787) See Change Here
  66. Applied: Add MedicationAdministration to the Future Page. (FHIR-30788) See Change Here
  67. Resolved - change required: Fix text in $docref description (FHIR-30810) See Change Here
  68. Resolved - change required: Mandate that CapabilityStatement.implementationGuide refer to US Core (FHIR-30889) See Change Here
  69. Applied: Add binding so Vitals will render it in differential view (FHIR-31391) See Change Here
  70. Applied: Update to URI from OID for CDT in Procedure Code ValueSet (FHIR-31556) See Change Here
  71. Applied: Add DocumentReference.content is under “must have” list (FHIR-31364) See Change Here
  72. Applied: Update Must Support Bullet regarding missing data (FHIR-31507) See Change Here
  73. Applied: Update use context for Race and Ethnicity extensions (FHIR-31008) See Change Here
  74. Applied: Add guidance on “POST … _search” (FHIR-31585) See Change Here
  75. Applied: Add reference to Mapping from LOINC scale type to FHIR data type (FHIR-31084) See Change Here
  76. Applied: Update Observation.value[x] definition (FHIR-31083) See Change Here


The US Core Implementation Guide is based on FHIR Version R4 and defines the minimum conformance requirements for accessing patient data. US Core has benefitted from 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. This guide and the US Core profiles have become the foundation for US Realm FHIR implementation guides. 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.

This release is the first of yearly US Core updates to reflect changes to U.S. Core Data for Interoperability (USCDI) v1 and requests from the US Realm FHIR community. This Approach is outlined in the figure below:

Figure 1: US Core Yearly Updates


The US Core 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. 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) v1.

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.
  • 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 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 US Core.
  • 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 Profile.
    • Search Parameters and Operations: This page lists the defined Operations and Search Parameters that are used in US Core transactions.
    • Terminology: This page lists the value sets and code system defined for profiles.
    • Capability Statements: This set of pages describes the expected FHIR capabilities of the various actors.
  • Security: General security requirements and recommendations for 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. 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, the same technology can be used by payers and other users. Consider these terms as a short-hand notation for something like “user application”
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. The terms “US Core Responder” and “Server” and “EHR” are used interchangeably throughout this guide and are not meant to limit this actor to electronic health record systems. The same technology can be used in HIEs, care coordination platforms, population health systems, etc. Consider these terms as a short-hand notation for something like “interoperable healthcare platform”.

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 BMI Profile
  • US Core Blood Pressure Profile
  • US Core Body Height Profile
  • US Core Body Temperature Profile
  • US Core Body Weight 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 Head Circumference Profile
  • US Core Heart Rate 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 Respiratory Rate Profile
  • US Core Smoking Status Observation Profile
  • US Core Vital Signs Profile
  • See the General Guidance page for a mapping to the U.S. Core Data for Interoperability (USCDI).

    Primary Authors: Brett Marquard, Eric Haas, Gay Dolin

    Secondary Authors: Grahame Grieve, Nagesh Bashyam