USCDI v7 Developer Guide: All 156 Data Elements Mapped to FHIR Resources and US Core Profiles
Software Development Expert
Writes about software development, scalable architecture, and practical problem-solving across modern digital products. Focuses on turning complex technical ideas into clear, real-world solutions.
Part of our complete guide to a primer on FHIR.
Your EHR vendor tells you they "support USCDI." Your compliance team asks which version. Your developers want to know which FHIR resources to implement. And somewhere between the ONC's 24-page PDF and the HL7 US Core Implementation Guide's 400+ pages of profiles, the answer gets buried.
For hands-on help with this, see our FHIR integration services.
This guide eliminates the guesswork. The United States Core Data for Interoperability (USCDI) v7, published as a draft on January 29, 2026, defines 156 data elements across 27 data classes that certified health IT systems must be capable of exchanging. USCDI defines what data must move. FHIR defines how it moves. And the US Core Implementation Guide bridges the two by defining FHIR profiles that implement each USCDI element with Must Support constraints, terminology bindings, and search parameters.
What follows is the definitive developer reference: every USCDI v7 data class and element mapped to its corresponding FHIR R4 resource, US Core profile, and key Must Support fields. Whether you are building a certified EHR module, integrating with a health information exchange, or preparing for ONC certification testing, this is the mapping table your engineering team needs on the wall.
What Is USCDI and Why Developers Must Care
USCDI is a standardized set of health data classes and constituent data elements established by the Office of the National Coordinator for Health Information Technology (now the Assistant Secretary for Technology Policy, or ASTP/ONC) under the authority of the 21st Century Cures Act. It answers a deceptively simple question: when two health IT systems exchange patient data, what is the minimum set of information they must both understand?
Before USCDI, the answer was the Common Clinical Data Set (CCDS), a static list tied to the 2015 Edition certification criteria. USCDI replaced CCDS with an annually versioned, publicly commented, incrementally expanding standard that grows alongside clinical and regulatory needs.
The Regulatory Teeth: HTI-1 and Certification
USCDI matters because ONC certification requires it. The HTI-1 Final Rule (published January 2024) established USCDI v3 as the mandatory baseline for all certified health IT, effective January 1, 2026. Every EHR vendor, every health information network, and every app developer participating in the ONC Health IT Certification Program must now support USCDI v3 data elements at minimum.
But v3 is the floor, not the ceiling. Through the Standards Version Advancement Process (SVAP), developers can voluntarily adopt newer versions ahead of regulatory mandates. ONC approved USCDI v5 for voluntary adoption through SVAP as of August 29, 2025. This means forward-looking vendors can implement up to v5 elements today and gain competitive advantage, while v7 (targeting final release in July 2026) previews where the standard is heading next.
Why This Is Not Optional
If your system is certified under the ONC Health IT Certification Program (specifically the Section 170.315(g)(10) Standardized API criterion), you must expose USCDI data elements through a FHIR API conforming to US Core profiles. Failure to do so is not a best-practice gap. It is a certification violation that can trigger information blocking enforcement under the Cures Act. For CMS-regulated entities, the stakes include financial penalties and program exclusion.
USCDI Version History: From 53 to 156 Data Elements
USCDI has nearly tripled in scope since its inception. Understanding the version trajectory matters because regulatory timelines, SVAP availability, and implementation guides all reference specific versions.
| Version | Release Date | Total Elements | New Elements | New Data Classes | Key Additions |
|---|---|---|---|---|---|
| v1 | July 2020 | 53 | 53 (baseline) | Allergies, Clinical Notes, Demographics, Goals, Immunizations, Labs, Medications, Problems, Procedures, Provenance, Vital Signs, and more | Foundational: demographics, medications, allergies, problems, labs, vitals, clinical notes |
| v2 | July 2021 | 75 | 22 | Health Status Assessments, SDOH data | Sexual Orientation, Gender Identity, SDOH screening, Clinical Tests, Diagnostic Imaging |
| v3 | December 2022 | 99 | 24 | Health Insurance Information, Facility Information | Average Blood Pressure, Encounter Diagnosis, Health Insurance coverage fields, Specimen data |
| v4 | December 2023 | 119 | 20 | Orders | Medication Orders, Lab Orders, Procedure Orders, Encounter Identifier, Care Team expansion |
| v5 | July 2024 | 135 | 16 | Family Health History, Goals and Preferences expansion | Advance Directives, Treatment Intervention Preference, Care Experience Preference, Portable Medical Orders |
| v6 | July 2025 | 142 | 6 (+errata) | None | Unique Device Identifier, Facility Address, Date of Onset, Family Health History expansion |
| v7 (Draft) | January 2026 | 156 | 30 | Adverse Events, Healthcare Information Attributes | Adverse Event tracking, Medication Administration, Tobacco Use revision, Accommodations, Healthcare Agent, Device Type, Referral Orders |
The pattern is clear: after v6's conservative 6-element addition, v7 represents the largest single-version expansion since v2, adding 30 elements and two entirely new data classes. As healthcare interoperability analyst Brendan Keeler noted in his analysis, v7 signals "the end of incrementalism" in USCDI's evolution.
USCDI v7: The 30 New Data Elements
Draft USCDI v7 includes 29 proposed new data elements and one significantly revised element (Tobacco Use, replacing the narrower Smoking Status), for a total of 30 additions. Of these, 13 are already represented in exchange specifications required by the ONC Health IT Certification Program, meaning certified systems largely support them already. The remaining 17 require new implementation work.
The new elements span three functional categories: adverse health and safety events, care coordination and patient context, and clinical care enhancements. Here is the complete breakdown by data class:
New Data Class: Adverse Events
This is USCDI's first dedicated data class for patient safety event tracking:
- Adverse Event: Documents a change to a patient's condition that could be an unintended effect of clinical interventions, such as medication reactions, vaccination reactions, or device-related events. Essential for patient safety monitoring and quality improvement.
- Adverse Event Outcome: Records the clinical outcome resulting from an adverse event (hospitalized, recovered, recovered with sequelae, ongoing, death). Enables structured pharmacovigilance reporting and cross-system safety signal detection.
New Data Class: Healthcare Information Attributes
A contextual data class providing supporting metadata for clinical records:
- Diagnostic Report Date: The clinically relevant date/time associated with a diagnostic report, distinct from when the report was created in the system.
- Reason Not Performed: Structured documentation of why an ordered test, procedure, immunization, or intervention was not completed, including patient refusal, clinical contraindications, and logistical barriers.
- Plus two relocated elements: Indication and Performance Time, moved from other data classes for organizational coherence.
Additions to Existing Data Classes
| Data Class | New Element | Description |
|---|---|---|
| Allergies and Intolerances | Allergy Intolerance Criticality | Indicates potential severity of a future reaction (life-threatening vs. low-risk). Distinguishes peanut anaphylaxis from mild medication rash. |
| Encounter Information | Encounter Reason | The chief complaint or reason for the clinical encounter. Supports care coordination and billing accuracy. |
| Encounter Information | Encounter Participant | Identifies providers involved in an encounter beyond the primary attending, including consulting physicians and nursing staff. |
| Diagnostic Imaging | Diagnostic Imaging Reference | Computable links enabling access to imaging studies associated with patient encounters, supporting cross-organizational diagnostic decision-making. |
| Health Insurance Information | Plan Name | Name of the health plan benefit offering, supporting cost transparency and value-based care coordination. |
| Health Insurance Information | Plan Identifier | Unique identifier for the health plan, enabling programmatic coverage verification. |
| Health Status Assessments | Tobacco Use (revised) | Replaces the narrower "Smoking Status" element. Expanded to include all tobacco products: smoke, vape, chew, snuff. Adds duration of use and quit date. |
| Health Status Assessments | Goal Assessment | Assessment and monitoring of patient goals and goal progress using tools like Goal Attainment Scaling (GAS), PHQ-9, GAD-7, and PROMIS. |
| Medical Devices | Device Type | Categorization of medical devices beyond UDI, enabling structured queries for device class and function. |
| Medications | Medication Administration | Records actual medication administration events (what was given, when, by whom), distinct from orders and dispenses. |
| Medications | Medication Dispense Quantity | The amount of medication dispensed to the patient, supporting medication reconciliation and adherence tracking. |
| Medications | Medication Status | Current status of a medication (active, completed, stopped, on hold). A fundamental element that was, notably, absent from prior versions. |
| Orders | Referral Orders | Provider-authored requests to another provider, specialist, or organization (wound specialist referral, podiatrist referral). Vocabulary: SNOMED CT. |
| Orders | Medical Device Orders | Provider-authored requests for medical devices (therapeutic footwear, walking aids, CPAP machines). Vocabulary: SNOMED CT. |
| Patient Demographics | Accommodations | Patient-specific accommodation needs (wheelchair access, sign language interpreter, service animal). Supports disability-inclusive care. |
| Patient Demographics | Healthcare Agent | The individual designated to make healthcare decisions on behalf of the patient (healthcare proxy, power of attorney for healthcare). |
The remaining elements in the count of 30 include refinements to existing categories such as expanded encounter attributes, additional health insurance information fields, and the relocation of Indication and Performance Time into the new Healthcare Information Attributes class.
The Complete USCDI v7 to FHIR Mapping Table
This is the centerpiece of this guide. The table below maps every USCDI v7 data class and data element to its corresponding FHIR R4 resource, US Core Implementation Guide profile, and key Must Support fields. This mapping is derived from the US Core IG v9.0.0 USCDI mapping and the ONC ISP reference.
How to read this table: The "US Core Profile" column identifies the specific HL7 profile that implements each element. "Key Must Support Fields" lists the FHIR element paths that conformant systems must populate when data is available. Elements marked [NEW in v7] are draft additions.
Allergies and Intolerances
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Substance (Medication) | AllergyIntolerance | US Core AllergyIntolerance | code, patient, clinicalStatus, verificationStatus |
| Substance (Drug Class) | AllergyIntolerance | US Core AllergyIntolerance | code (NDF-RT or RxNorm drug class), patient |
| Substance (Non-Medication) | AllergyIntolerance | US Core AllergyIntolerance | code (SNOMED CT), patient, category |
| Reaction | AllergyIntolerance | US Core AllergyIntolerance | reaction.manifestation (SNOMED CT) |
| Allergy Intolerance Criticality [NEW in v7] | AllergyIntolerance | US Core AllergyIntolerance | criticality (low | high | unable-to-assess) |
Adverse Events [NEW Data Class in v7]
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Adverse Event [NEW in v7] | AdverseEvent | US Core AdverseEvent (proposed) | event, subject, date, suspectEntity, seriousness |
| Adverse Event Outcome [NEW in v7] | AdverseEvent | US Core AdverseEvent (proposed) | outcome (resolved, recovering, ongoing, fatal, unknown) |
Care Plan
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Assessment and Plan of Treatment | CarePlan | US Core CarePlan | text.div, status, intent, category, subject |
Care Team Members
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Care Team Member Name | Practitioner, Patient, RelatedPerson | US Core Practitioner, Patient, RelatedPerson | name.family, name.given |
| Care Team Member Identifier | Practitioner, Patient | US Core Practitioner, Patient | identifier (NPI for practitioners) |
| Care Team Member Location | PractitionerRole, Practitioner | US Core PractitionerRole | location, address |
| Care Team Member Telecom | PractitionerRole, Practitioner | US Core PractitionerRole, Practitioner | telecom.system, telecom.value |
| Care Team Member Role | CareTeam | US Core CareTeam | participant.role, participant.member |
Clinical Notes
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Consultation Note | DocumentReference | US Core DocumentReference | type (LOINC 11488-4), content.attachment, subject |
| Discharge Summary Note | DocumentReference | US Core DocumentReference | type (LOINC 18842-5), content.attachment |
| History and Physical | DocumentReference | US Core DocumentReference | type (LOINC 34117-2), content.attachment |
| Imaging Narrative | DocumentReference, DiagnosticReport | US Core DocumentReference, DiagnosticReport for Report and Note Exchange | type, content.attachment, presentedForm |
| Procedure Note | DocumentReference, DiagnosticReport | US Core DocumentReference, DiagnosticReport | type (LOINC 28570-0), content.attachment |
| Progress Note | DocumentReference | US Core DocumentReference | type (LOINC 11506-3), content.attachment |
| Operative Note | DocumentReference | US Core DocumentReference | type (LOINC 11504-8), content.attachment |
| Emergency Department Note | DocumentReference | US Core DocumentReference | type (LOINC 34878-9), content.attachment |
Clinical Tests
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Clinical Test | Observation, DiagnosticReport | US Core Observation Clinical Result, DiagnosticReport | code, value, status, category, effectiveDateTime |
| Clinical Test Result/Report | Observation, DiagnosticReport | US Core Observation Clinical Result, DiagnosticReport | result, conclusion, presentedForm |
Diagnostic Imaging
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Diagnostic Imaging Test | Observation, DiagnosticReport | US Core Observation Clinical Result, DiagnosticReport | code (LOINC), category (imaging), status |
| Diagnostic Imaging Result/Report | Observation, DiagnosticReport | US Core Observation Clinical Result, DiagnosticReport | conclusion, presentedForm, media |
| Diagnostic Imaging Reference [NEW in v7] | DiagnosticReport, ImagingStudy | US Core DiagnosticReport | imagingStudy, media.link (reference to imaging study) |
Encounter Information
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Encounter Identifier | Encounter | US Core Encounter | identifier.system, identifier.value |
| Encounter Type | Encounter | US Core Encounter | type (CPT, SNOMED CT) |
| Encounter Diagnosis | Condition | US Core Condition Encounter Diagnosis | code, category (encounter-diagnosis), encounter |
| Encounter Time | Encounter | US Core Encounter | period.start, period.end |
| Encounter Location | Encounter | US Core Encounter | location.location (Reference to Location) |
| Encounter Disposition | Encounter | US Core Encounter | hospitalization.dischargeDisposition |
| Encounter Reason [NEW in v7] | Encounter | US Core Encounter | reasonCode (SNOMED CT), reasonReference |
| Encounter Participant [NEW in v7] | Encounter | US Core Encounter | participant.type, participant.individual |
Facility Information
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Facility Identifier | Location | US Core Location | identifier (NPI, CLIA) |
| Facility Type | Location | US Core Location | type (V3 ServiceDeliveryLocationRoleType) |
| Facility Name | Location | US Core Location | name |
| Facility Address | Location | US Core Location | address.line, address.city, address.state, address.postalCode |
Family Health History
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Family Health History | FamilyMemberHistory | US Core FamilyMemberHistory | relationship, condition.code, patient, status |
Goals and Preferences
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Patient Goals | Goal | US Core Goal | description, lifecycleStatus, subject, target |
| SDOH Goals | Goal | US Core Goal | description, category (sdoh), subject |
| Advance Directive Observation | Observation, DocumentReference | US Core Observation ADI Documentation, ADI DocumentReference | code, value, content.attachment |
| Treatment Intervention Preference | Observation | US Core Treatment Intervention Preference | code, valueString, subject |
| Care Experience Preference | Observation | US Core Care Experience Preference | code, valueString, subject |
| Goal Assessment [NEW in v7] | Observation | US Core Simple Observation | code (GAS, PHQ-9, GAD-7, PROMIS), value, derivedFrom |
Health Insurance Information
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Coverage Status | Coverage | US Core Coverage | status (active, cancelled, entered-in-error) |
| Coverage Type | Coverage | US Core Coverage | type (insurance type code) |
| Relationship to Subscriber | Coverage | US Core Coverage | relationship (self, spouse, child, other) |
| Member Identifier | Coverage | US Core Coverage | identifier (member ID) |
| Subscriber Identifier | Coverage | US Core Coverage | subscriberId |
| Group Number | Coverage | US Core Coverage | class (group).value |
| Payer Identifier | Coverage, Organization | US Core Coverage, Organization | payor (Reference to Organization), identifier |
| Plan Name [NEW in v7] | Coverage | US Core Coverage | class (plan).name |
| Plan Identifier [NEW in v7] | Coverage | US Core Coverage | class (plan).value |
Health Status Assessments
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Health Concerns | Condition | US Core Condition Problems and Health Concerns | code, category (health-concern), clinicalStatus |
| Functional Status | Observation, Condition, QuestionnaireResponse | US Core Simple Observation, Observation Screening Assessment | code, value, category |
| Disability Status | Observation, Condition, QuestionnaireResponse | US Core Simple Observation, Observation Screening Assessment | code (LOINC), value |
| Mental/Cognitive Status | Observation, Condition, QuestionnaireResponse | US Core Simple Observation, Observation Screening Assessment | code, value, effectiveDateTime |
| Pregnancy Status | Observation | US Core Observation Pregnancy Status, Pregnancy Intent | code (LOINC 82810-3), valueCodeableConcept |
| Alcohol Use | Observation, QuestionnaireResponse | US Core Simple Observation, Observation Screening Assessment | code (AUDIT-C LOINC), value |
| Substance Use | Observation, QuestionnaireResponse | US Core Simple Observation, Observation Screening Assessment | code, value, effectiveDateTime |
| Physical Activity | Observation, QuestionnaireResponse | US Core Simple Observation, Observation Screening Assessment | code, value |
| SDOH Assessment | Observation, QuestionnaireResponse | US Core Simple Observation, Observation Screening Assessment | code, value, category (sdoh) |
| Tobacco Use [REVISED in v7] (replaces Smoking Status) | Observation | US Core Smoking Status Observation (updated) | code (LOINC), valueCodeableConcept, effectiveDateTime (expanded to all tobacco products, duration, quit date) |
Healthcare Information Attributes [NEW Data Class in v7]
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Diagnostic Report Date [NEW in v7] | DiagnosticReport | US Core DiagnosticReport | effectiveDateTime, effectivePeriod |
| Reason Not Performed [NEW in v7] | Procedure, Immunization, Observation | US Core Procedure, Immunization | statusReason (SNOMED CT negation reason codes) |
| Indication (relocated) | MedicationRequest, ServiceRequest | US Core MedicationRequest, ServiceRequest | reasonCode, reasonReference |
| Performance Time (relocated) | Procedure, DiagnosticReport, Immunization | US Core Procedure, DiagnosticReport, Immunization | performedDateTime, performedPeriod, occurrenceDateTime |
Immunizations
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Immunizations | Immunization | US Core Immunization | vaccineCode (CVX), patient, occurrenceDateTime, status |
| Lot Number | Immunization | US Core Immunization | lotNumber |
Laboratory
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Tests | Observation, DiagnosticReport | US Core Laboratory Result Observation, DiagnosticReport | code (LOINC), category (laboratory), status |
| Values/Results | Observation | US Core Laboratory Result Observation | valueQuantity, valueCodeableConcept, valueString |
| Specimen Type | Specimen | US Core Specimen | type (SNOMED CT specimen hierarchy) |
| Result Status | Observation, DiagnosticReport | US Core Laboratory Result Observation | status (registered, preliminary, final, amended) |
| Result Unit of Measure | Observation | US Core Laboratory Result Observation | valueQuantity.unit, valueQuantity.code (UCUM) |
| Result Reference Range | Observation | US Core Laboratory Result Observation | referenceRange.low, referenceRange.high |
| Result Interpretation | Observation | US Core Laboratory Result Observation | interpretation (H, L, N, A, etc.) |
| Specimen Identifier | Specimen | US Core Specimen | identifier, accessionIdentifier |
| Specimen Source Site | Specimen | US Core Specimen | collection.bodySite (SNOMED CT) |
| Specimen Condition Acceptability | Specimen | US Core Specimen | condition (specimen condition codes) |
Medical Devices
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Unique Device Identifier (UDI) | Device | US Core Implantable Device | udiCarrier.deviceIdentifier, type, patient |
| Device Type [NEW in v7] | Device | US Core Implantable Device | type (SNOMED CT device type hierarchy) |
Medications
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Medications | Medication, MedicationRequest | US Core Medication, MedicationRequest | medicationCodeableConcept (RxNorm), status, intent |
| Dose | MedicationRequest | US Core MedicationRequest | dosageInstruction.doseAndRate.doseQuantity |
| Dose Unit of Measure | MedicationRequest | US Core MedicationRequest | dosageInstruction.doseAndRate.doseQuantity.unit (UCUM) |
| Route of Administration | MedicationRequest, MedicationDispense | US Core MedicationRequest, MedicationDispense | dosageInstruction.route (SNOMED CT) |
| Indication | MedicationRequest | US Core MedicationRequest | reasonCode, reasonReference |
| Medication Instructions | MedicationRequest | US Core MedicationRequest | dosageInstruction.text, dosageInstruction.patientInstruction |
| Medication Adherence | MedicationRequest | US Core MedicationRequest (adherence extension) | extension (medication-adherence) |
| Fill Status | MedicationDispense | US Core MedicationDispense | type (fill type), status, quantity |
| Medication Administration [NEW in v7] | MedicationAdministration | US Core MedicationAdministration (proposed) | medicationCodeableConcept, subject, effectiveDateTime, performer, status |
| Medication Dispense Quantity [NEW in v7] | MedicationDispense | US Core MedicationDispense | quantity.value, quantity.unit (UCUM) |
| Medication Status [NEW in v7] | MedicationRequest, MedicationStatement | US Core MedicationRequest | status (active, completed, stopped, on-hold, cancelled) |
Orders
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Medication Order | MedicationRequest | US Core MedicationRequest | status, intent (order), medicationCodeableConcept, subject |
| Laboratory Order | ServiceRequest | US Core ServiceRequest | code (LOINC), status, intent, subject, category (laboratory) |
| Diagnostic Imaging Order | ServiceRequest | US Core ServiceRequest | code (LOINC/CPT), category (imaging), status, intent |
| Clinical Test Order | ServiceRequest | US Core ServiceRequest | code, category, status, intent, subject |
| Procedure Order | ServiceRequest | US Core ServiceRequest | code (SNOMED CT/CPT), category, status, intent |
| Portable Medical Order | DocumentReference | US Core ADI DocumentReference | type (POLST LOINC), content.attachment |
| Referral Orders [NEW in v7] | ServiceRequest | US Core ServiceRequest | code (SNOMED CT), category (referral), performer, reasonCode |
| Medical Device Orders [NEW in v7] | ServiceRequest | US Core ServiceRequest | code (SNOMED CT), category (device-order), requester |
Patient Demographics
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| First Name | Patient | US Core Patient | name.given |
| Last Name | Patient | US Core Patient | name.family |
| Previous Name | Patient | US Core Patient | name (use: old) |
| Middle Name | Patient | US Core Patient | name.given (second occurrence) |
| Suffix | Patient | US Core Patient | name.suffix |
| Sex | Patient | US Core Patient (Individual Sex Extension) | extension (individual-sex), gender |
| Date of Birth | Patient | US Core Patient | birthDate |
| Date of Death | Patient | US Core Patient | deceasedDateTime |
| Race | Patient | US Core Patient (Race Extension) | extension (us-core-race): ombCategory, detailed, text |
| Ethnicity | Patient | US Core Patient (Ethnicity Extension) | extension (us-core-ethnicity): ombCategory, detailed, text |
| Tribal Affiliation | Patient | US Core Patient (Tribal Affiliation Extension) | extension (us-core-tribal-affiliation) |
| Preferred Language | Patient | US Core Patient | communication.language, communication.preferred |
| Interpreter Needed | Patient, Encounter | US Core Patient, Encounter (Interpreter Needed Extension) | extension (us-core-interpreter-needed) |
| Address | Patient | US Core Patient | address.line, address.city, address.state, address.postalCode |
| Previous Address | Patient | US Core Patient | address (use: old, period.end) |
| Patient | US Core Patient | telecom (system: email) | |
| Phone Number | Patient | US Core Patient | telecom (system: phone) |
| Related Person's Name | RelatedPerson | US Core RelatedPerson | name.family, name.given, patient |
| Related Person's Relationship | RelatedPerson | US Core RelatedPerson | relationship (code) |
| Occupation | Observation | US Core Observation Occupation | code (LOINC 11341-5), valueCodeableConcept (ODH) |
| Occupation Industry | Observation | US Core Observation Occupation | component (industry), valueCodeableConcept |
| Accommodations [NEW in v7] | Patient | US Core Patient (proposed extension) | extension (accommodations): type, description |
| Healthcare Agent [NEW in v7] | RelatedPerson | US Core RelatedPerson | relationship (healthcare agent code), name, telecom |
Problems
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Date of Resolution | Condition | US Core Condition Problems and Health Concerns | abatementDateTime |
| Date of Diagnosis | Condition | US Core Condition Problems and Health Concerns (assertedDate Extension) | extension (condition-assertedDate) |
| Date of Onset | Condition | US Core Condition Problems and Health Concerns | onsetDateTime |
| SDOH Problems/Health Concerns | Condition | US Core Condition Problems and Health Concerns | code (SNOMED CT/ICD-10), category (sdoh) |
Procedures
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Procedure | Procedure | US Core Procedure | code (SNOMED CT, CPT, HCPCS), status, subject, performedDateTime |
| Performance Time | Procedure, DiagnosticReport, Immunization | US Core Procedure, DiagnosticReport, Immunization | performedDateTime, performedPeriod |
| Reason for Referral | ServiceRequest, Procedure | US Core ServiceRequest, Procedure | reasonCode, reasonReference |
| SDOH Interventions | ServiceRequest, Procedure | US Core ServiceRequest, Procedure | code, category (sdoh), reasonReference |
Provenance
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Author | Provenance | US Core Provenance | agent.who (Reference to Practitioner, Organization, Patient) |
| Author Role | Provenance | US Core Provenance | agent.onBehalfOf, agent.type |
| Author Time Stamp | Provenance | US Core Provenance | recorded |
| Author Organization | Provenance | US Core Provenance | agent.who (Reference to Organization) |
Vital Signs
| USCDI Data Element | FHIR R4 Resource | US Core Profile | Key Must Support Fields |
|---|---|---|---|
| Diastolic Blood Pressure | Observation | US Core Blood Pressure | component (code: LOINC 8462-4), valueQuantity |
| Systolic Blood Pressure | Observation | US Core Blood Pressure | component (code: LOINC 8480-6), valueQuantity |
| Average Blood Pressure | Observation | US Core Average Blood Pressure | component (systolic avg, diastolic avg), valueQuantity |
| Body Height | Observation | US Core Body Height | code (LOINC 8302-2), valueQuantity (cm or [in_i]) |
| Body Weight | Observation | US Core Body Weight | code (LOINC 29463-7), valueQuantity (kg or [lb_av]) |
| Heart Rate | Observation | US Core Heart Rate | code (LOINC 8867-4), valueQuantity (/min) |
| Respiratory Rate | Observation | US Core Respiratory Rate | code (LOINC 9279-1), valueQuantity (/min) |
| Body Temperature | Observation | US Core Body Temperature | code (LOINC 8310-5), valueQuantity (Cel or [degF]) |
| Pulse Oximetry | Observation | US Core Pulse Oximetry | code (LOINC 2708-6 or 59408-5), valueQuantity (%) |
| Inhaled Oxygen Concentration | Observation | US Core Pulse Oximetry | component (LOINC 3151-8), valueQuantity (%) |
| BMI Percentile (2-20 years) | Observation | US Core Pediatric BMI for Age | code (LOINC 59576-9), valueQuantity (%) |
| Weight-for-Length Percentile (Birth-36 months) | Observation | US Core Pediatric Weight for Height | code (LOINC 77606-2), valueQuantity (%) |
| Head Circumference Percentile (Birth-36 months) | Observation | US Core Pediatric Head Occipital-Frontal Circumference Percentile | code (LOINC 8289-1), valueQuantity (%) |
Implementation Priority Guide: What to Build First
With 156 data elements spanning 27 data classes, implementation sequencing matters. Not every element carries the same regulatory urgency or clinical impact. Here is a prioritization framework based on the HTI-1 compliance timeline and real-world certification testing requirements.
Tier 1: Compliance Critical (USCDI v3 Baseline) — Implement Now
These are mandatory as of January 1, 2026 under HTI-1. If your certified system does not support these, you are in violation:
- Patient Demographics: All name fields, DOB, sex, race, ethnicity, address, phone, email, preferred language
- Allergies and Intolerances: Substance (all three types) and Reaction
- Problems: Problem list with SNOMED CT/ICD-10 codes, dates of diagnosis, onset, and resolution
- Medications: Active medications with dose, route, and indication
- Laboratory: Test codes (LOINC), values, units (UCUM), reference ranges, and interpretation
- Vital Signs: All blood pressure, height, weight, heart rate, respiratory rate, temperature, and pulse oximetry elements
- Clinical Notes: All eight note types via DocumentReference
- Procedures: Procedure codes with performance time
- Immunizations: Vaccine codes (CVX) and lot numbers
- Encounter Information: Type, time, diagnosis, identifier
- Provenance: Author, role, timestamp, organization
- Health Insurance Information: Coverage status, type, member ID, payer
Tier 2: Strategic Advantage (USCDI v4-v5 via SVAP) — Build in 2026
These elements are available for voluntary adoption through SVAP and will likely become mandatory in a future HTI rulemaking cycle. Early adoption differentiates your product:
- Orders: Medication, laboratory, imaging, clinical test, and procedure orders via ServiceRequest
- Goals and Preferences: Advance directives, treatment intervention preferences, care experience preferences
- Family Health History: FamilyMemberHistory with conditions and relationships
- Facility Information: Location identifiers, type, name, and address
- Health Status Assessments: Functional status, disability status, SDOH assessments, pregnancy status
- Specimen data: Specimen type, identifier, source site, condition
Tier 3: Forward Planning (USCDI v7 Draft) — Design in 2026, Build in 2027
These elements are in draft and will be finalized in July 2026. Start data modeling and schema work now, but do not block releases on them:
- Adverse Events: New data class requiring AdverseEvent resource support
- Medication Administration: MedicationAdministration resource (distinct from MedicationRequest)
- Medication Status and Dispense Quantity: Additional MedicationDispense fields
- Tobacco Use (revised): Expanded Smoking Status with broader tobacco product coverage
- Referral and Medical Device Orders: ServiceRequest category extensions
- Accommodations and Healthcare Agent: Patient profile extensions
- Healthcare Information Attributes: New contextual metadata class
USCDI + US Core IG: How They Relate
A common source of confusion: USCDI and US Core are not the same thing, but they are inseparable in practice.
USCDI is a policy document. It says "systems must be able to exchange a patient's allergies." It does not specify the wire format, the data model, or the API. It is owned by ONC (now ASTP).
US Core Implementation Guide is the FHIR implementation of USCDI. It says "allergies must be represented using the AllergyIntolerance resource, the code element must use a value from the RxNorm or SNOMED CT value sets, and the clinicalStatus element is Must Support." It is owned by HL7 International and balloted through the HL7 standards process.
FHIR R4 provides the base resource definitions that US Core profiles constrain. A US Core AllergyIntolerance profile is a FHIR R4 AllergyIntolerance resource with additional constraints (required elements, terminology bindings, cardinality restrictions).
Version Alignment
| US Core IG Version | FHIR Version | USCDI Version Supported | Certification Status |
|---|---|---|---|
| US Core 3.1.1 | R4 (4.0.1) | USCDI v1 | Retired from Inferno testing (2026) |
| US Core 5.0.1 | R4 (4.0.1) | USCDI v2 | Available for certification |
| US Core 6.1.0 | R4 (4.0.1) | USCDI v3 | HTI-1 mandatory baseline (Jan 2026) |
| US Core 7.0.0 | R4 (4.0.1) | USCDI v4 | Available via SVAP |
| US Core 8.0.1 | R4 (4.0.1) | USCDI v5 | Available via SVAP (Aug 2025) |
| US Core 9.0.0 (ballot) | R4 (4.0.1) | USCDI v6-v7 | In development |
The critical insight: US Core remains on FHIR R4. Despite FHIR R5 being published and R6 in development, the US regulatory ecosystem is firmly anchored to R4 through US Core. This will not change until ASTP explicitly adopts a newer FHIR version in a future rulemaking, which is unlikely before 2028 at the earliest.
Testing Your USCDI Compliance
Building the right FHIR profiles is necessary but not sufficient. ONC certification requires passing automated conformance tests that validate your API against US Core profiles.
Inferno: The Official ONC Test Tool
Inferno is the open-source testing framework maintained by ONC that serves as the official test method for the Section 170.315(g)(10) Standardized API criterion. The ONC Certification (g)(10) Standardized API Test Kit validates:
- SMART on FHIR authentication: Standalone launch, EHR launch, and backend services authorization
- US Core profile conformance: Every resource returned by your API is validated against the corresponding US Core profile
- USCDI data element coverage: Tests verify that your API can return data for each required USCDI data class
- Search parameter support: Required search parameters (patient, category, date, code, status) must return correct results
As of 2026, Inferno v8.0.0 has retired support for US Core 3.1.1 and 4.0.0. Testers can no longer select those older IG versions. The minimum testable version is now US Core 5.0.1 (USCDI v2), with US Core 6.1.0 (USCDI v3) required for HTI-1 compliance.
Testing Checklist
- Deploy Inferno locally using Docker (
docker-compose up) and run the g(10) test kit against your FHIR endpoint. - Select your target US Core version (6.1.0 minimum for HTI-1 compliance).
- Validate Must Support fields: Inferno checks that when data exists, Must Support elements are populated. The most common failure: returning a resource without a Must Support element that your database actually has data for.
- Check terminology bindings: Ensure codes come from the required value sets (RxNorm for medications, SNOMED CT for conditions, LOINC for labs, CVX for immunizations, UCUM for units).
- Test search parameters: US Core defines required search parameter combinations. For example, Condition must support search by
patientandpatient+category. Missing search support is a certification blocker. - Validate Provenance: Every resource must be returnable with its associated Provenance via the
_revinclude=Provenance:targetparameter.
Beyond Certification: Continuous Validation
Certification is a point-in-time event. Production systems must maintain conformance through ongoing validation. Integrate the FHIR Validator into your CI/CD pipeline to catch profile drift before it reaches production. Run Inferno tests as part of your regression suite whenever you modify FHIR resource serialization or search logic.
Regional Context: How National Data Standards Compare
USCDI is not the only national data standard driving health IT interoperability. Developers building for global markets or multinational health systems need to understand how these frameworks relate.
| Framework | Country/Region | Scope | FHIR Version | Enforcement Mechanism | Key Difference from USCDI |
|---|---|---|---|---|---|
| USCDI v7 | United States | 156 data elements, 27 data classes | R4 (via US Core IG) | ONC Certification (21st Century Cures Act) | Certification-driven; annual versioning; FHIR API mandate |
| ABDM FHIR IG | India | Health records exchange across ABHA-linked systems | R4 | NHA certification + ABDM sandbox compliance | Consent-based; patient-mediated sharing via ABHA; M1/M2/M3 milestone model |
| EU EHDS | European Union | Patient summaries, ePrescriptions, lab results, imaging, discharge reports | R4 (emerging; OMOP-on-FHIR for secondary use) | EU Regulation 2025/327 (effective March 2026) | Federated model; strong secondary use focus; SNOMED CT + ICD-10 multilingual |
| HL7 AU Core | Australia | Core clinical data for Australian healthcare | R4 | Australian Digital Health Agency guidelines | Aligned with International Patient Summary; PBS/MBS coding systems |
| TEFCA | United States | Network-to-network exchange framework | R4 (via QHIN requirements) | Sequoia Project + ONC designation | Complements USCDI; defines exchange network, not data content |
The convergence pattern is clear: every major national framework is building on FHIR R4 as the transport layer. The divergence is in what data is mandated (USCDI's 156 elements vs. EHDS's priority categories vs. ABDM's health record structure) and how exchange is governed (certification-driven in the US, consent-mediated in India, regulation-driven in the EU). For organizations building cross-border health IT, designing a FHIR-first architecture with locale-specific profile layers is the only sustainable approach.
Frequently Asked Questions
What is the difference between USCDI and US Core?
USCDI is a policy standard published by ONC/ASTP that defines which health data elements must be exchangeable (e.g., "patient allergies," "lab results"). US Core is a FHIR implementation guide published by HL7 that defines how those elements are represented in FHIR resources, including specific profiles, terminology bindings, Must Support constraints, and search parameters. USCDI is implementation-agnostic; US Core is FHIR-specific. In practice, the ONC certification program requires USCDI data to be exposed via a FHIR API conforming to US Core profiles, making them functionally inseparable for certified health IT.
Which USCDI version is required for ONC certification in 2026?
USCDI v3 is the mandatory baseline as of January 1, 2026, under the HTI-1 Final Rule. Systems certified to criteria referencing USCDI must support v3 data classes and elements at minimum. Through SVAP, developers can voluntarily adopt USCDI v4 (via US Core 7.0.0) or USCDI v5 (via US Core 8.0.1) for certification purposes. USCDI v7 is in draft (public comment closes April 13, 2026) and is expected to be finalized in July 2026, but will not become a certification requirement until a future rulemaking.
How many data elements are in USCDI v7?
Draft USCDI v7 contains 156 data elements across 27 data classes. This includes 126 elements carried forward from v6 and 30 proposed additions (29 new elements plus one significantly revised element, Tobacco Use, which replaces the narrower Smoking Status). Of the 30 new elements, 13 are already represented in exchange specifications used by certified health IT, meaning systems that implemented prior US Core profiles may already partially support them.
What FHIR resources do I need for USCDI v7?
Supporting all 156 USCDI v7 data elements requires implementing approximately 25-30 FHIR R4 resource types through their corresponding US Core profiles. The most heavily used resources are: Patient (demographics), AllergyIntolerance (allergies), Condition (problems, encounter diagnoses, health concerns), Observation (labs, vitals, clinical tests, health assessments), MedicationRequest (medications, medication orders), Encounter (encounters), Procedure (procedures), DocumentReference (clinical notes), ServiceRequest (orders), and Coverage (health insurance). V7 adds AdverseEvent and MedicationAdministration as new resource requirements.
What is the public comment deadline for USCDI v7?
The public comment period for Draft USCDI v7 closes on April 13, 2026, at 11:59 PM ET. Comments can be submitted through the Interoperability Standards Platform (ISP) at healthit.gov. ONC is targeting release of the final USCDI v7 in July 2026. Stakeholders should review the 30 proposed elements and provide feedback, particularly on the new Adverse Events data class and the Tobacco Use revision, where ONC has specifically requested input on the optimal approach for representing tobacco use information.
Can I use USCDI v7 data elements in my product before it is finalized?
Yes, but with caveats. Draft USCDI v7 elements may change based on public comments before the July 2026 final release. You can begin data modeling, schema design, and prototype development using the draft specifications. However, do not certify against v7 elements or represent v7 compliance in marketing materials until the final version is published and corresponding US Core profiles are balloted. For production systems, implement USCDI v3 (mandatory) and v5 (SVAP-available) elements first, then layer in v7 elements as they stabilize.
The USCDI Trajectory Is Clear. The Question Is Whether You Are Ahead of It.
USCDI v7 is the clearest signal yet that the US health data standard is accelerating. Thirty new elements in a single version -- including an entire new data class for adverse events, expanded medication lifecycle tracking, and care coordination attributes like accommodations and healthcare agents -- moves USCDI from a narrow clinical data exchange standard toward a comprehensive patient record specification.
For development teams, the mapping table in this guide is your implementation blueprint. Every data element has a defined FHIR resource, a published US Core profile with Must Support constraints, and a testing pathway through Inferno. The gap between "what USCDI requires" and "what your API exposes" is now measurable, testable, and auditable.
For compliance teams, the prioritization framework is your roadmap: USCDI v3 is mandatory today, v5 is available for competitive advantage through SVAP, and v7 previews the elements you will need to support within 18-24 months. Organizations that wait for each version to become mandatory before starting implementation will perpetually lag behind those that build forward-compatible FHIR infrastructure.
At Nirmitee, we build FHIR-native interoperability platforms that are designed for where USCDI is going, not just where it is today. From US Core profile implementation and FHIR API development to Inferno certification testing and TEFCA-ready exchange architecture, we help health IT teams close the gap between regulatory requirements and production-ready code. If your organization is planning USCDI v3 compliance, SVAP adoption, or forward-looking v7 implementation, let's build it right.
Ready to scale?
Talk to our healthcare engineering team about building, integrating, and shipping faster.
Frequently Asked Questions
What is USCDI v7?
What is the difference between USCDI and FHIR?
Which USCDI version is required for ONC certification?
What new data elements does USCDI v7 add?
How should developers prepare for USCDI v7 compliance?
How does Nirmitee.io approach healthcare software development?