USCDI vs US Core: how the data rules and the FHIR profiles map, version by version
USCDI and US Core are named together but do different jobs. USCDI lists the data classes and elements that US certified health IT must support. HL7 US Core defines the FHIR profiles, search rules and terminology that carry that data over an API. Each USCDI version gets a matching US Core release, and certified APIs are tied to specific versions by regulation.
What is the difference between USCDI and US Core, and how do the versions map?
Quick answer
USCDI vs US Core is not a choice between two standards. USCDI defines which data must be exchangeable, and HL7 US Core defines how that data is represented in FHIR R4. Each USCDI version maps to a US Core release, such as USCDI v3 to US Core 6.1.0. Agnotic Technologies builds FHIR apps and servers that handle several versions.
| Criterion | USCDI | US Core |
|---|---|---|
| Version 1 | USCDI v1 (July 2020 Errata). Its adoption in 45 CFR 170.213(a) expired on January 1, 2026 | US Core 3.1.1, named in 45 CFR 170.215 until January 1, 2026. US Core 4.0.0 also maps to v1, with clearer Must Support guidance |
| Version 2 | USCDI v2. Not named in 45 CFR 170.213 | US Core 5.0.1 |
| Version 3 | USCDI v3, the version 45 CFR 170.213(b) adopts for certification | US Core 6.1.0, adopted in 45 CFR 170.215(b)(1)(ii). HL7's mapping table lists it against USCDI v3.1 |
| Version 4 | USCDI v4. Not named in 45 CFR 170.213 | US Core 7.0.0 |
| Version 5 | USCDI v5. Not named in 45 CFR 170.213 | US Core 8.0.1, the technical correction of 8.0.0 |
| Version 6 | USCDI v6, published by ASTP in July 2025. Not named in 45 CFR 170.213 | US Core 9.0.0, published May 31, 2026, the current HL7 release |
| Base standard | None: USCDI names data elements, not a format | FHIR R4 (4.0.1) for every release in this table |
| What a new version changes for you | New data elements to capture, store and expose | New or changed profiles, Must Support elements, search parameters and value sets to implement |
What they are
What is USCDI
The United States Core Data for Interoperability is a standardized set of health data classes and data elements, such as allergies, medications, laboratory results and clinical notes, published in versions by ONC (ASTP). 45 CFR 170.213 adopts the versions used in certification. USCDI names data, not a format or technology.
What is US Core
The HL7 US Core Implementation Guide is built on FHIR R4. It defines the minimum constraints on FHIR resources that make up the US Core profiles, the elements and value sets that must be supported, and the RESTful interactions used to access patient data. HL7 updates it each year for the latest USCDI version.
Key differences
Why does each USCDI version need a new US Core release?
HL7 describes USCDI as defining high-level data requirements and US Core as providing the detailed FHIR profiles that meet them, and notes that an interpretation of USCDI is needed to make it implementable in FHIR. When a USCDI version adds an element, US Core decides which profile carries it: a new profile, a new Must Support element or an extension. The two move together but are published separately.
Which versions must a certified API support today?
45 CFR 170.213 adopts USCDI v3, and the adoption of USCDI v1 expired on January 1, 2026. 45 CFR 170.215 names FHIR R4.0.1 as the API base standard and US Core 6.1.0 as the profile set, and the adoption of US Core 3.1.1 also expired on January 1, 2026. A certified server can still offer newer versions through the Standards Version Advancement Process.
What does the Standards Version Advancement Process allow?
Under 45 CFR 170.405(b)(8), a certified developer may update a Health IT Module to a newer version of an adopted standard once the National Coordinator approves that version for certification. Under 170.405(b)(9), a developer may certify directly to an approved newer version. Confirm which versions are approved before you promise a newer US Core release to customers.
What breaks when an app meets servers on different versions?
Three things cause most failures. Elements that are Must Support in a newer US Core release may be missing on an older server, so the app must treat them as optional. Profiles added in a newer release may not exist at all, so searches return nothing. Changed value sets and search parameters can make a query that works on one server fail on another. A server's CapabilityStatement shows what it claims; our headless EHR comparison explains how to read it.
Should a new FHIR app target the regulatory version or the newest one?
Treat the regulatory version as the floor and the newest as an option. Build the read path against US Core 6.1.0, which certified servers support, then add newer elements behind a check that the server declares them. On the server side the logic reverses: meet the required version first, then add newer profiles when customers ask for them.
When to use each
When to use USCDI
- You are deciding which data your product must capture, store and share for certification or customer requirements.
- You are scoping a certified health IT module and need the data classes and elements in scope.
- You are checking whether a data element is in a published USCDI version or still only proposed.
- You are writing requirements that must hold across formats, including C-CDA documents and FHIR APIs.
When to use US Core
- You are building or testing a FHIR API that exposes USCDI data.
- You need the exact profiles, Must Support elements, search parameters and value sets a server or client must handle.
- You connect an app to several EHRs and need to know what each server's declared US Core version means.
- You are building on FHIR R4 and want the US baseline that other US implementation guides build on.
How do you build a FHIR app or server that handles more than one US Core version?
1. Record the US Core version each connected server declares in its CapabilityStatement, and store it with the connection.
2. Map USCDI elements to profiles per version in a configuration table, not in code, so a new release is a data change.
3. Treat every element added after US Core 6.1.0 as optional, and show users when data is not available instead of showing it as empty.
4. Validate responses against the profile version the server declares, not against the newest release.
5. Run the same test patients against servers on each supported version before every release.
6. Track HL7's yearly US Core releases and the certification rules, and plan an upgrade when a newer version is adopted or approved.
Which sources does this comparison rely on?
- 45 CFR 170.213, United States Core Data for Interoperability (eCFR)
- 45 CFR 170.215, Application Programming Interface Standards (eCFR)
- 45 CFR 170.405(b)(8) and (b)(9), Standards Version Advancement Process (eCFR)
- US Core Implementation Guide, USCDI to US Core version table (HL7)
- US Core publication history, including 9.0.0 (HL7)