US Core Implementation Guide
3.2.0 - ballot

This page is part of the US Core (v3.2.0: STU4 Ballot 1) 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

Home

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

The changes in this version have been voted on by the members of the sponsoring work group HL7 International Cross-Group Projects. This version addresses the following key issues:

  1. Clarification of the Must Support definitions as it relates to:
    • Polymorphic datatypes, which of the possible types must be supported
    • Reference datatype (Reference, canonical) which of the target types must be supported
    • The vital signs profile in the Core Specification which profiles must be supported
    • New Conformance Expectations page (see individual trackers below for details)
  2. Publishing a set US Core Vital Signs independent of the FHIR core profile upon which it is based (see individual trackers below for details)
  3. Linking terminology directly to the FHIR® Terminology Service for VSAC Resources (Value Set Authority Center (VSAC) - NIH) where applicable
  • We are seeking to resolve several technical and policy glitches when using VSAC directly prior to publishing which include the requirement to log in using your own UMLS API Key requiring a current UMLS account to view the value sets. VSAC UMLS Licensing information.
  • To view the VSAC value set, use the link https://vsac.nlm.nih.gov/valueset/{OID}/expansion in your browser replacing the ‘{OID}’ with the OID from the table below.
  • Enumerated (extensional) value sets can also be downloaded as a FHIR ValueSet resource. To do this, use the link https://cts.nlm.nih.gov/fhir/ValueSet/{OID} in your browser replacing the ‘{OID}’ with the OID from the table below.
  • NOTE that the Code System value used in FHIR® Terminology Service for VSAC Resources for Race and Ethnicity (CDCREC) concepts does not align with historical and current usage of OIDs in C-CDA and US Core. This issue has not been resolved in time for publication of the ballot version of this guide. As a result validation errors may occur when validating against this version of the US Core Patient Profile. Feedback on which code system value to use is welcome.
US Core Value Set VSAC Value Set VSAC OID extensional?
Detailed ethnicity Detailed Ethnicity 2.16.840.1.114222.4.11.877 No
Detailed Race Race 2.16.840.1.113883.1.11.14914 No
OMB Ethnicity Categories Ethnicity 2.16.840.1.114222.4.11.837 Yes
US Core CareTeam Provider Roles Care Team Member Function 2.16.840.1.113762.1.4.1099.30 Yes
US Core Medication Codes (RxNorm) Medication Clinical Drug 2.16.840.1.113762.1.4.1010.4 Yes
US Core Provider Speciality (NUCC) Healthcare Provider Taxonomy 2.16.840.1.114222.4.11.1066 No
US Core Smoking Status Smoking Status 2.16.840.1.113883.11.20.9.38 Yes
US Core Vaccine Administered Value Set (CVX) CVX Vaccines Administered Vaccine Set 2.16.840.1.113762.1.4.1010.6 Yes
US Core Common substances for allergy and intolerance documentation including refutations Common substances for allergy and intolerance documentation including refutations 2.16.840.1.113762.1.4.1186.8 No
  1. Migrating to the standard set of HL7 FHIR IG templates for publishing. Although we strove to minimize the differences between this version and the previous versions of US Core, these changes are notable:
    • Additional Features include:
      • Addition of vocabulary and constraint tables to the profile pages
      • Addition of a summary table and to the profile page introduction
      • Addition of “Snapshot Table (Must Support)” Tab to profile views
    • Due to restrictions on customizable content, the following features of prior versions are no longer available:
      • Full narrative text summaries of profiles NOTE: We are seeking feedback on whether to retain these full narrative text summaries for this guide (an example can be seen here by clicking on the “Text Summary” tab)*
  2. Addressing over 95 outstanding trackers.

Trackers items and links to the updated content listed below are the resolved trackers for this version:

  1. Must Support Over Interpreted (FHIR-28375) Changes throughoughout the profiles – added conformance page See Change Here

  2. Replace the US Core Update Allergy substances value set with VSAC reference (FHIR-29322) See Change Here

  3. Update Organization Quick Start Example Search. (FHIR-29269) See Change Here

  4. birthsex binding applied to the wrong element in US Core Patient StructuredDefinition/differential (FHIR-29262) See Change Here

  5. us-core-12 invariant interpretation (FHIR-28942) See Changes Here

  6. Incorrect Description Observation.component (Pulse Ox) (FHIR-28934) See Change Here

  7. References should be constrained to use reference not identifier (FHIR-28573) See Change Here

  8. Update USCorePatientName search description for consistency (FHIR-28540) See Change Here

  9. Make Provenance.author optional (FHIR-28517) See Change Here

  10. Add must support type choices for US Core Goal.target.due[x]. (FHIR-28477) See Change Here

  11. Immunization Profile Mandatory and Must Support Intro is missing attributes (FHIR-28452) See Change Here

  12. DiagnosticReport-cardiology-report JSON and XML samples contain invalid hashes (FHIR-28408) See Change Here

  13. MedicationRequest.medication[x] (FHIR-28395) See Change Here

  14. Fix MedicationRequest.encounter reference (FHIR-28258) See Change Here

  15. Fix typo: “an another” -> “another” (FHIR-28227) See Change Here

  16. Declare mustSupport on Organization telecom children (FHIR-28216) See Change Here

  17. Resolve remaining discrepancies with FHIR R4 Search Parameters (FHIR-28181) See Changes Here:

  18. Provenance without activity isn’t very useful (FHIR-28179) See Change Here

  19. Make Provenance.target.reference mandatory (FHIR-28165) See Change Here

  20. Missing narrative Element (FHIR-28159) See Change Here

  21. “Updated guidance regarding gender and sex.” (FHIR-28138) See Change Here

  22. Replace the US Core Smoking Status with VSAC reference (FHIR-28123,FHIR-26059) See Change Here

  23. Timing association for smoking status changed from issued to effectiveDateTime (FHIR-28090) See Change Here

  24. Remove Must Support from Patient.telecom (FHIR-27731) See Change Here

  25. Remove Must Support from Patient.communication.language (FHIR-27730) See Change Here

  26. Remove Must Support from us-core-birthsex extension (FHIR-27729) See Change Here

  27. Remove Must Support from us-core-ethnicity extension (FHIR-27728) See Change Here

  28. Remove Must Support from us-core-race extension (FHIR-27727) See Change Here

  29. Expand US Core state value set to include US Military codes (FHIR-26833) See Change Here

  30. Fixed Value Set Expansion Operation examples (FHIR-26625) See Change Here

  31. Add must support reference type choices for US Core laboratory DiagnosticReport.performer (FHIR-25120) See Change Here

  32. Fix US-Core-1 constraint on Observation.effectivePeriod (FHIR-29658) See Change Here

  33. Change bindings from extensible to required for Condition.code value set: US Core Condition Category Codes Procedure.code value set: US Core Procedure Codes (FHIR-29563) See Changes Here:

  34. Remove text ‘an author responsible for the update’. Keep author organization (FHIR-28516) See Change Here

  35. “Clarify expectations when accessing ‘other endpoint’ for DocumentReference.content.attachment.url” (FHIR-28472) See Change Here

  36. Add a required category to smoking status (FHIR-28436) See Change Here

  37. Use of US Core Profile when not explicitly referenced when using Contained resources (FHIR-28396) See Change Here

  38. DocumentReference.custodian to be Optional (FHIR-28393) See Proposed Change Here

  39. Encounter.serviceProvider Must Support and Encounter.location.location Optional (FHIR-28392) See Change Here

  40. Observation.hasMember Vital Signs Panel Profile Reference Choice (FHIR-28391) See Change Here

  41. Add must support type choices for Observation.value[x] for for Lab Observation Profile (FHIR-28390) See Change Here

  42. Add must support type choices for Observation.effective[x] for Lab Observation Profile (FHIR-28389) See Change Here

  43. Add must support type choices for Immunization.occurrence[x] (FHIR-28388) See Change Here

  44. Add must support type choices for DiagnosticReport.effective[x] for Note Data (FHIR-28387) See Change Here

  45. Add must support type choices for DiagnosticReport.effective[x] for Lab Data Type (FHIR-28385) See Change Here

  46. Add must support reference type choices for Provenance.agent.who Reference (FHIR-28383) See Change Here

  47. Add must support reference type choices for MedicationRequest.requester Reference (FHIR-28382) See Change Here

  48. Add must support reference type choices for MedicationRequest.reported Choice (FHIR-28381) See Change Here

  49. Add must support reference type choices for DocumentReference.author Reference (FHIR-28380) See Change Here

  50. Add must support reference type choices for DiagnosticReport.performer for Note (FHIR-28379) See Change Here

  51. Add must support reference type choices for DiagnosticReport.performer for Lab (FHIR-28378) See Change Here

  52. Add must support reference type choices for CareTeam.participant.member Reference (FHIR-28376) See Change Here

  53. Add choice for and type choices for Encounter.reasonReference (FHIR-27951) See Change Here

  54. Add choice for Procedure.performed[x] (FHIR-29695) See Change Here

  55. Clarify deleted resources requirements and guidance (FHIR-28091) See Change Here

  56. Clarify search by date precision conformance expectations (FHIR-27906) See Change Here
  57. Clarify search by reference conformance expectations (FHIR-27905) See Changes Here:

  58. Add “Cause of Death” to category codes to meet the Public Health Use Case for VRDR (FHIR-27904) See Change Here

  59. Address non-implantable device and how to document usage (FHIR-27896, FHIR-23715, FHIR-23715) See Change Here

  60. Resource constraints based on Jurisdiction which are not well documented (FHIR-27810) See Change Here

  61. Updated CPT copyright to current year (FHIR-27770) See Change Here

  62. Change binding for CareTeam.participant.role from NUCC to Care Team Member Function, replace the US Core Careteam Provider Roles Value Set with VSAC reference (FHIR-27769) See Change Here

  63. Remove US Core Server Capability Statement requires support for HTTP status 410-deleted (FHIR-26597) See Change Here

  64. Change US Core Condition Code Value Set Logical Definition (FHIR-26060) See Change Here

  65. Recommend against using SSN for Patient.identifier (FHIR-24903) See Change Here

  66. Remove identifier (OID) from ValueSet: US Core Encounter Type (FHIR-29691) See Change Here

  67. Review vocabulary to align with CCDA and use VSAC valueset where possible (FHIR-22488) [See Changes Here:

  68. Remove remove CVS-NDC mapping table (FHIR-29745) See Change Here

  69. Since CarePlan.text.div is min== 1 add must support == true element to be consisten with US Core design (FHIR-29765) See Change Here

  70. Remove unused US Core ICD-10-PCS Procedure Codes valueset (FHIR-29822)

  71. Remove Clinical Notes Guidance References to ONC 2019 NPRM and move requirements to main body (FHIR-29824) See Change Here

Introduction

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 .
  • 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 .
  • 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.
  • 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 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).

    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, Gay Dolin

    Secondary Authors: Grahame Grieve, Nagesh Bashyam