USCDI v4 Implementation Guide — What's New and How to Implement It

USCDI stands for United States Core Data for Interoperability. It's a standard set of health data classes and data elements that healthcare organizations and certified EHRs are required to be able to exchange.

It's published and maintained by the Office of the National Coordinator for Health Information Technology (ONC) — the federal agency responsible for health IT standards in the US.

USCDI matters because it has real regulatory teeth. ONC-certified EHRs must support the current adopted version of USCDI. Health information networks participating in TEFCA must support it. Payer-provider data exchange under CMS rules references it. If you're building anything in US healthcare that touches clinical data, USCDI tells you the minimum data set you need to handle.

The practical impact: if your application or platform integrates with EHRs, your FHIR endpoints — both inbound and outbound — need to support every USCDI data class and element in the version your trading partners require. That's what this version of the standard is for and that's why Mirth Connect support teams end up doing so much USCDI-aware work.

These three things show up together constantly. Here's how they relate.

The 21st Century Cures Act is the federal law passed in 2016 that, among many other things, mandates health information interoperability and prohibits information blocking. It directs ONC to certify EHRs against interoperability requirements.

USCDI is the data standard ONC uses to specify what data must be exchangeable. It's a list of data classes (patient demographics, clinical notes, lab results, etc.) and the specific elements within each class.

FHIR (R4) is the technical standard ONC requires for how the data must be exchanged. Specifically, the FHIR US Core Implementation Guide specifies which FHIR resources and profiles correspond to each USCDI data element.

Put together: the Cures Act says "you must interoperate." USCDI says "these are the data elements that have to be exchangeable." US Core specifies "this is the FHIR way to represent those data elements." You implement all three by building a FHIR R4 endpoint that conforms to US Core profiles for every USCDI data class. Background reading: our FHIR Integration Guide covers the broader FHIR landscape this all sits inside.

USCDI evolves on an annual cycle. Each version adds data classes and data elements; ONC adopts new versions on a slower regulatory cycle.

USCDI v1 established the initial set — patient demographics, problems, medications, allergies, immunizations, lab results, vital signs, smoking status, care plans, clinical notes, procedures, and the fundamental document types.

USCDI v2 added data classes including clinical tests, encounter information, social determinants of health (SDOH), and additional patient demographic elements.

USCDI v3 expanded SDOH significantly, added more granular sex/gender/sexual orientation elements, and refined several existing classes.

USCDI v4 continues this trajectory. Specific additions are detailed in the next section.

A new USCDI version doesn't immediately become mandatory. ONC formally adopts versions through rulemaking, and the adopted version applies to certifications and to information exchange requirements over a defined timeline. Check the current ONC certification criteria for which version applies to your specific use case.

USCDI v4 builds on v3 with additional data classes and elements focused on more complete patient context and improved interoperability with non-clinical data sources.

The general areas of expansion in v4 typically include:

Expanded social determinants of health. Additional SDOH data elements that align with the Gravity Project's vocabulary work. SDOH continues to be one of the most-expanded areas across versions.

Encounter information refinements. More granular encounter context including additional encounter types, more complete location information, and refined encounter identifiers.

Diagnostic imaging. Additional imaging-related data classes for radiology and diagnostic imaging exchange.

Patient-reported outcomes. Movement toward including standardized patient-reported data elements.

Care coordination data. Enhanced care team information and care coordination data classes.

Additional clinical data classes. Specific clinical areas like substance use, mental health, and behavioral health get expanded data classes.

A note on specifics: ONC publishes the authoritative list of USCDI v4 data classes and elements directly. Before implementation, always pull the current data elements from the official ONC USCDI website rather than relying on any secondary source — including this article. The data element details change as ONC refines the standard between publication and adoption.

A common point of confusion. They're related but serve different purposes.

USCDI is the core baseline standard required for general health information exchange and ONC certification. Every certified EHR must support it. It's the floor.

USCDI+ is a framework for use-case-specific data extensions to USCDI. There are several USCDI+ instances — USCDI+ Cancer, USCDI+ Quality, USCDI+ Public Health, USCDI+ Behavioral Health, and others. Each one adds data elements specific to that domain.

If you're building a general-purpose healthcare application, target USCDI itself.

If you're building something domain-specific (a cancer registry, a public health reporting tool, a behavioral health platform), check whether there's a USCDI+ instance for your domain and consider supporting it in addition to base USCDI.

The relationship: USCDI+ instances extend USCDI without replacing it. Supporting a USCDI+ instance always includes supporting baseline USCDI.

This is where implementation gets concrete. Each USCDI data class maps to one or more FHIR R4 resources, profiled under US Core.

The high-level mapping pattern:

Each US Core profile specifies must-support elements, required value sets, and conformance requirements. Implementation means conforming to the profile, not just instantiating the FHIR resource.

For the full current mapping including all USCDI v4 additions, consult the HL7 US Core Implementation Guide directly. It's the authoritative technical reference. For the upstream side — translating HL7 v2 messages into these FHIR resources — see our HL7 v2 to FHIR R4 Mapping Reference.

The high-level architecture for a USCDI-compliant FHIR endpoint:

1. Inventory your source data. Map every USCDI data element you need to support to its source in your existing systems. Identify gaps — every USCDI element you can't source from somewhere is a data acquisition problem you'll need to solve.

2. Build FHIR resources that conform to US Core profiles. Don't just instantiate generic FHIR resources. Profile conformance requires specific must-support elements, specific terminology bindings, and specific extensions. Use FHIR validators to check conformance before going live.

3. Implement the standard FHIR REST API operations — read, search, history at minimum. Most USCDI-relevant interactions also need _include and _revinclude parameters working correctly for resource linking.

4. Implement SMART on FHIR authentication. ONC certification requires OAuth-based authorization with specific scopes. SMART on FHIR is the standard for this. Use the SMART App Launch Framework v2.

5. Support FHIR Bulk Data export. USCDI exchange increasingly uses the Bulk Data IG for population-level data export. Implement $export operations on Patient and Group endpoints. Our FHIR Bulk Data Implementation Guide 2026 covers the implementation in detail.

6. Test against published test suites. ONC's Inferno test suite tests FHIR endpoints against US Core and USCDI requirements. Run it continuously in CI before any release that touches FHIR endpoints.

7. Document your capability statement. Your FHIR server's CapabilityStatement resource should explicitly declare US Core conformance and the USCDI version supported.

If you already have a USCDI v3 implementation, the migration to v4 is incremental rather than wholesale.

Step 1 — Gap analysis. Compare your current data class coverage against USCDI v4. Identify the new data classes and new elements in existing data classes.

Step 2 — Source data assessment. For each new USCDI v4 element, identify whether your existing systems capture that data. New elements often require data acquisition changes upstream, not just FHIR endpoint changes.

Step 3 — Update FHIR profiles. Pull the latest US Core IG. Compare current profile versions to new versions. Identify resources where profile conformance requirements have tightened.

Step 4 — Update terminology bindings. Some USCDI v4 elements use updated value sets. Verify your terminology services support the new value sets, or update local terminology where you maintain it.

Step 5 — Update capability statement. Once new endpoints are in place, update the CapabilityStatement to declare USCDI v4 support.

Step 6 — Re-run Inferno test suite. Make sure all existing tests still pass and add tests for newly-supported elements.

Step 7 — Communicate to trading partners. If you have downstream consumers of your FHIR data, let them know which USCDI version you support and when you transition.

Most teams can complete the migration in 6–12 weeks depending on how many new data classes affect their existing data acquisition pipeline. The endpoint changes are usually faster than the source-system changes. For organizations that want a fixed-price, fixed-scope path through this work, the FHIR R4 Adapter Sprint handles exactly this kind of build-out.

If you're pursuing or maintaining ONC Health IT Certification, USCDI conformance is mandatory. The specific version required depends on the certification criteria edition.

A few practical notes for certified product developers:

ONC's certification edition rules specify the adopted USCDI version. Track ONC rulemaking carefully because adoption timing affects your release planning.

The Inferno test suite is mandatory for many certification criteria. Build it into your CI pipeline early — failing Inferno tests during the formal certification process is expensive to fix.

Certification covers more than USCDI itself. Patient access APIs, single patient launch, multi-patient launch, bulk data, and other criteria all have their own conformance requirements that intersect with USCDI.

If you're not pursuing formal certification but you integrate with certified EHRs, you don't directly need to certify — but you do need to interoperate with certified products, which effectively means supporting the same USCDI version they support.

Mistake 1 — Instantiating FHIR resources without conforming to US Core profiles. Generic FHIR conformance is not US Core conformance. Profile conformance requires specific must-support elements, specific terminology, and specific extensions. Validate against US Core, not just base FHIR.

Mistake 2 — Hardcoding USCDI version in your capability statement. New versions ship regularly. Make the supported version configurable so you can update without redeploying core logic.

Mistake 3 — Forgetting about Provenance. Many USCDI elements require Provenance resources alongside the primary data resource. Skipping Provenance fails US Core conformance and breaks downstream consumers that depend on data lineage.

Mistake 4 — Treating USCDI as a static set. The standard evolves annually. Build update processes into your engineering rhythm. USCDI v5 is on the roadmap and will require another round of changes.

Mistake 5 — Ignoring terminology services. USCDI requires conformance to specific value sets (SNOMED, LOINC, RxNorm, ICD-10, etc.). Many teams discover too late that their source data doesn't use the required vocabularies and needs translation through a terminology service.

Mistake 6 — Underestimating the data acquisition problem. Adding a USCDI element to your FHIR endpoint is the easy part. Getting your source systems to capture the data, with the right granularity and the right vocabulary, is where most of the real work happens.

Mistake 7 — Skipping bulk data export. Modern USCDI workflows increasingly assume bulk data capability. Single-patient read APIs alone aren't enough for population-level use cases like payer-provider exchange.

ONC Inferno test suite. The official test suite for USCDI and US Core conformance. Free, open source, runs as a web application or in CI. Mandatory for many ONC certification criteria. Run it continuously.

HAPI FHIR Validator. General-purpose FHIR resource validator. Useful for validating individual resources against US Core profiles outside of full endpoint testing.

FHIR Test Sandboxes. SMART Health IT, HAPI FHIR's public test server, and various vendor sandboxes (Epic, Oracle Health, athenahealth) let you test client integrations against reference USCDI implementations.

US Core Implementation Guide. The authoritative technical reference. Read it in detail before implementing. The narrative sections explain conformance requirements that aren't always obvious from the profile definitions alone.

FHIR Pathology Validator. For lab-specific USCDI elements, this specialized validator catches issues that general FHIR validators miss.

Mirth Connect or another integration engine. For most healthcare integration teams, the FHIR endpoint sits in front of HL7 v2 source systems. The integration engine handles the HL7 v2 to FHIR translation. We've written a separate HL7 v2 to FHIR R4 Mapping Reference on exactly this.

USCDI v5 is on the development roadmap. ONC publishes draft versions for public comment well before adoption, so you can track what's coming and plan accordingly.

General trajectory across upcoming versions:

More SDOH coverage. SDOH continues to be the fastest-growing area of the standard. Expect more elements, finer granularity, and stronger alignment with Gravity Project vocabulary.

Behavioral health expansion. Mental health and substance use data classes are expanding to support better behavioral health interoperability.

Healthcare equity data. Race, ethnicity, language, sexual orientation, gender identity, and disability status are all areas of ongoing refinement.

Patient-generated and device data. Patient-reported outcomes, remote monitoring data, and wearable-device data are increasingly represented in the standard.

Genomic and precision medicine data. Longer-term inclusion of genomic data classes is on the roadmap.

If you're building infrastructure that will need to support multiple USCDI versions over time, design for it from day one. Version negotiation, profile-driven validation, and configurable terminology services are all worth investing in early.

The specifics of USCDI data classes and data elements change as ONC refines the standard. Before implementation:

• Pull the current authoritative data class list directly from ONC's USCDI website.
• Reference the latest published US Core Implementation Guide from HL7.
• Verify which USCDI version applies to your specific certification or trading partner requirements.
• Run the current version of Inferno against your implementation.

This article describes the structural approach to USCDI v4 implementation, but the exact data element enumeration must come from the official ONC publication.

Implementing USCDI v4 well is part of a larger interoperability strategy that touches your data architecture, your FHIR infrastructure, your integration engine, and your certification posture.

If your organization is building this from scratch or upgrading from v3 to v4, our FHIR R4 Adapter Sprint is the fixed-price, fixed-scope way to get a USCDI-conformant endpoint into production. For ongoing operations after build, see our Mirth Connect support tiers.

For related context, see our FHIR Integration Guide, our HL7 v2 to FHIR R4 Mapping Reference, and our FHIR Bulk Data Implementation Guide 2026.

To estimate the cost of a USCDI implementation project, run our pricing calculator.