Introduction: Why FHIR US Core Matters for US Healthcare APIs
If you are building healthcare APIs for the US market, FHIR US Core is not optional. It is the implementation guide that translates regulatory requirements into concrete technical specifications. Every certified Electronic Health Record (EHR) system, every patient-facing application, and every health information exchange operating in the United States must conform to US Core profiles to meet interoperability mandates set by the Office of the National Coordinator for Health Information Technology (ONC).
The FHIR US Core Implementation Guide (currently at version 8.0.1, STU 8) defines a minimum set of constraints on FHIR R4 resources. These constraints establish a floor, not a ceiling, for interoperability. They ensure that when a patient's data moves between systems, a consistent, predictable structure carries it. Without US Core compliance, your API cannot participate in the regulated US healthcare ecosystem.
This guide walks through everything a US healthtech developer needs to build compliant FHIR APIs: the profiles themselves, the USCDI data elements they encode, the validation tools that prove compliance, and the regulatory framework that makes all of it mandatory.
The Regulatory Foundation: 21st Century Cures Act and ONC Certification
Before examining the technical profiles, it is essential to understand why they exist. The 21st Century Cures Act, signed into law in 2016, fundamentally reshaped healthcare data exchange in the United States. Its key provisions created the legal framework that makes FHIR US Core compliance a business necessity.
Information Blocking Rule
Effective April 2021, the Information Blocking Rule prohibits healthcare providers, health IT developers, and health information exchanges from practices that unreasonably limit the access, exchange, or use of electronic health information (EHI). As of October 2022, this applies to all EHI, not just the USCDI data set. Failure to provide standardized API access can trigger enforcement actions from the OIG, with civil monetary penalties reaching up to $1 million per violation for health IT developers.
Standardized API Requirements
The ONC Health IT Certification Program requires certified health IT modules to support standardized APIs using FHIR R4 and the US Core Implementation Guide. This means any EHR vendor seeking or maintaining ONC certification must implement US Core profiles. The current certification criteria reference US Core 3.1.1 as the baseline, with US Core 6.1.0 and newer versions adopted for updated certification requirements under the HTI-1 final rule.
CMS Interoperability Rules
The Centers for Medicare and Medicaid Services (CMS) issued complementary rules requiring CMS-regulated payers (Medicare Advantage, Medicaid, CHIP, and Qualified Health Plan issuers on the exchanges) to implement Patient Access APIs, Provider Directory APIs, and Payer-to-Payer data exchange, all built on FHIR R4 with US Core profiles. The CMS Interoperability and Prior Authorization Final Rule (CMS-0057-F) further expanded these requirements through 2027.
Understanding USCDI: The Data Standard Behind US Core
The United States Core Data for Interoperability (USCDI) defines which data elements must be exchangeable between health IT systems. USCDI is not a technical specification; it is a standardized set of health data classes and data elements that ONC requires for interoperability. US Core profiles are the FHIR-based technical implementation of USCDI requirements.
USCDI Version Evolution
ONC publishes new USCDI versions regularly, each expanding the required data set:
USCDI v1 established the baseline with core data classes: Patient Demographics, Allergies and Intolerances, Assessment and Plan of Treatment, Care Team Members, Clinical Notes, Goals, Health Concerns, Immunizations, Laboratory, Medications, Problems, Procedures, Provenance, Smoking Status, Unique Device Identifiers, and Vital Signs.
USCDI v3 added significant new data classes including Health Insurance Information, Specimen, Encounter Information, and expanded clinical notes categories. It introduced data elements for Average Blood Pressure, Clinical Tests, Diagnostic Imaging, Facility Information, and Gender Identity.
USCDI v4 (finalized in 2024) further expanded the standard with new data elements for Advance Directives, Treatment Intervention Preferences, Care Experience Preferences, Disability Status, Mental/Cognitive Status, Physical Function, Laboratory Result Status, Specimen Type and Condition, and expanded encounter disposition data. USCDI v4 is the version referenced by the HTI-1 final rule for updated ONC certification criteria.
How USCDI Maps to US Core Profiles
Each USCDI data class maps to one or more US Core FHIR profiles. For example:
- Patient Demographics maps to the US Core Patient Profile
- Allergies and Intolerances maps to the US Core AllergyIntolerance Profile
- Laboratory maps to US Core Observation Laboratory Result, US Core DiagnosticReport for Laboratory Results Reporting, and US Core Specimen
- Medications maps to US Core MedicationRequest and US Core MedicationDispense profiles
- Clinical Notes maps to US Core DocumentReference and US Core DiagnosticReport for Report and Note Exchange
- Vital Signs maps to 10+ US Core Observation profiles (Blood Pressure, BMI, Body Height, Body Weight, Body Temperature, Heart Rate, Respiratory Rate, Pulse Oximetry, Head Circumference, and Pediatric profiles)
- Health Insurance Information maps to the US Core Coverage Profile
- Encounter Information maps to the US Core Encounter Profile
Core US Core Profiles: A Technical Deep Dive
US Core v8.0.1 defines over 50 profiles across 25+ FHIR resource types. Here we examine the most critical profiles every US healthcare API must implement, with conformant JSON examples you can use as starting templates.
US Core Patient Profile
The Patient profile is foundational. Every other clinical resource references a Patient. US Core adds constraints beyond base FHIR that reflect US-specific requirements.
Required elements: identifier (with system), name (family + given), gender. Must Support elements: race (US Core Race Extension), ethnicity (US Core Ethnicity Extension), birthDate, communication.language, telecom, address, birthsex, gender identity, and previous name and suffix.
{
"resourceType": "Patient",
"id": "example-patient",
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
]
},
"extension": [
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
"extension": [
{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2106-3",
"display": "White"
}
},
{
"url": "text",
"valueString": "White"
}
]
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
"extension": [
{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2186-5",
"display": "Not Hispanic or Latino"
}
},
{
"url": "text",
"valueString": "Not Hispanic or Latino"
}
]
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
"valueCode": "M"
}
],
"identifier": [
{
"system": "http://hospital.example.org/patients",
"value": "12345"
}
],
"name": [
{
"use": "official",
"family": "Smith",
"given": ["John", "Robert"]
}
],
"telecom": [
{
"system": "phone",
"value": "555-123-4567",
"use": "home"
},
{
"system": "email",
"value": "john.smith@example.com"
}
],
"gender": "male",
"birthDate": "1980-07-15",
"address": [
{
"use": "home",
"line": ["123 Main Street"],
"city": "Springfield",
"state": "IL",
"postalCode": "62701",
"country": "US"
}
],
"communication": [
{
"language": {
"coding": [
{
"system": "urn:ietf:bcp:47",
"code": "en",
"display": "English"
}
]
},
"preferred": true
}
]
}US Core Condition Profile
US Core defines two Condition profiles: Encounter Diagnosis (conditions documented during an encounter) and Problems and Health Concerns (the patient's active problem list). Both require a clinicalStatus, verificationStatus, category, code (from SNOMED CT or ICD-10-CM), and a subject reference to a US Core Patient.
{
"resourceType": "Condition",
"id": "example-condition",
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-condition-problems-health-concerns"
]
},
"clinicalStatus": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
"code": "active",
"display": "Active"
}
]
},
"verificationStatus": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
"code": "confirmed",
"display": "Confirmed"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/condition-category",
"code": "problem-list-item",
"display": "Problem List Item"
}
]
}
],
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "44054006",
"display": "Type 2 diabetes mellitus"
}
],
"text": "Type 2 diabetes mellitus"
},
"subject": {
"reference": "Patient/example-patient",
"display": "John Smith"
},
"onsetDateTime": "2020-03-15"
}US Core Observation Profiles
Observations represent the largest family of US Core profiles. The guide defines specialized profiles for different observation types, each with specific coding requirements and value constraints.
Laboratory Result Observation requires a category of "laboratory", a code from LOINC, and a value (typically valueQuantity with UCUM units or valueCodeableConcept). The status must be from a required value set (registered, preliminary, final, amended, corrected, cancelled, entered-in-error, unknown).
{
"resourceType": "Observation",
"id": "example-lab-result",
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-observation-lab"
]
},
"status": "final",
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "laboratory",
"display": "Laboratory"
}
]
}
],
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "4548-4",
"display": "Hemoglobin A1c/Hemoglobin.total in Blood"
}
],
"text": "HbA1c"
},
"subject": {
"reference": "Patient/example-patient",
"display": "John Smith"
},
"effectiveDateTime": "2026-03-01T10:30:00Z",
"valueQuantity": {
"value": 6.8,
"unit": "%",
"system": "http://unitsofmeasure.org",
"code": "%"
},
"referenceRange": [
{
"low": {
"value": 4.0,
"unit": "%",
"system": "http://unitsofmeasure.org",
"code": "%"
},
"high": {
"value": 5.6,
"unit": "%",
"system": "http://unitsofmeasure.org",
"code": "%"
},
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/referencerange-meaning",
"code": "normal",
"display": "Normal Range"
}
]
}
}
]
}Vital Signs Observations follow the base FHIR Vital Signs profile with additional US Core constraints. Blood Pressure, for example, requires component elements for systolic and diastolic readings, each with specific LOINC codes:
{
"resourceType": "Observation",
"id": "example-blood-pressure",
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-blood-pressure"
]
},
"status": "final",
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "vital-signs",
"display": "Vital Signs"
}
]
}
],
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "85354-9",
"display": "Blood pressure panel with all children optional"
}
]
},
"subject": {
"reference": "Patient/example-patient"
},
"effectiveDateTime": "2026-03-01T09:00:00Z",
"component": [
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8480-6",
"display": "Systolic blood pressure"
}
]
},
"valueQuantity": {
"value": 120,
"unit": "mmHg",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
},
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8462-4",
"display": "Diastolic blood pressure"
}
]
},
"valueQuantity": {
"value": 80,
"unit": "mmHg",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
}
]
}US Core MedicationRequest Profile
MedicationRequest captures prescription and medication order data. US Core requires status, intent, a medication reference or codeable concept (using RxNorm codes), subject reference, and authoredOn date. The requester element (the prescribing practitioner) is Must Support.
{
"resourceType": "MedicationRequest",
"id": "example-medication-request",
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-medicationrequest"
]
},
"status": "active",
"intent": "order",
"medicationCodeableConcept": {
"coding": [
{
"system": "http://www.nlm.nih.gov/research/umls/rxnorm",
"code": "860975",
"display": "Metformin Hydrochloride 500 MG Oral Tablet"
}
],
"text": "Metformin 500mg tablet"
},
"subject": {
"reference": "Patient/example-patient",
"display": "John Smith"
},
"authoredOn": "2026-03-01",
"requester": {
"reference": "Practitioner/example-practitioner",
"display": "Dr. Sarah Johnson"
},
"dosageInstruction": [
{
"text": "Take one tablet by mouth twice daily with meals",
"timing": {
"repeat": {
"frequency": 2,
"period": 1,
"periodUnit": "d"
}
},
"route": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "26643006",
"display": "Oral route"
}
]
}
}
]
}Must Support: What It Actually Means
One of the most misunderstood concepts in US Core is "Must Support." Developers frequently confuse Must Support with "required." They are different obligations with different implications for servers and clients.
Server (US Core Responder) Obligations
A server claiming US Core conformance SHALL be capable of populating all Must Support data elements as part of query results when that data exists in the system. If data is not available and the reason is unknown, the server SHALL NOT include the element. If the reason for missing data is known (for example, the patient declined to share), the server SHOULD communicate the reason using a Data Absent Reason extension.
Client (US Core Requestor) Obligations
A client claiming US Core conformance must be capable of processing resource instances containing Must Support elements without generating an error or causing the application to fail. The client must interpret missing data elements as data not present in the server's system. The client may choose not to use a resource if its content does not meet the client's business requirements, but it must not crash.
Complex and Reference Elements
For complex Must Support elements (elements with sub-elements), the server must be capable of providing at least one sub-element value. If individual sub-elements are flagged as Must Support, each must independently meet the obligation. For reference elements with Must Support and a single target profile, that target profile must be supported. With multiple target profiles and no specific Must Support flags, the system must support at least one target profile.
SMART on FHIR Scopes for US Core
US Core APIs are not just about data structure; they must also implement proper authorization. The SMART on FHIR authorization framework defines the scopes that control access to US Core resources. Understanding how scopes interact with US Core profiles is critical for building compliant and secure APIs.
Scope Syntax and Structure
SMART on FHIR v2 scopes follow the pattern: patient/[ResourceType].[cruds] or user/[ResourceType].[cruds]. The "patient" context limits access to a single patient's data (the launch context patient), while "user" context grants access based on the authenticated user's permissions.
For a typical patient-facing application accessing US Core data, the required scopes include:
launch/patient
openid
fhirUser
offline_access
patient/Patient.read
patient/Condition.read
patient/Observation.read
patient/MedicationRequest.read
patient/AllergyIntolerance.read
patient/Immunization.read
patient/Procedure.read
patient/CarePlan.read
patient/CareTeam.read
patient/DiagnosticReport.read
patient/DocumentReference.read
patient/Encounter.read
patient/Goal.read
patient/Provenance.readGranular Scopes in SMART v2
SMART on FHIR v2 (required by US Core 6.1.0+) introduces granular scopes that allow filtering by category and other search parameters. For example, patient/Observation.rs?category=vital-signs restricts access to only vital signs observations. This enables more privacy-preserving authorization by limiting data exposure to only what the application needs.
Token Introspection and US Core
Servers must validate that the granted scopes match the requested resources. If an application requests patient/Observation.read but then queries /Condition, the server must return an appropriate error (typically 403 Forbidden). US Core compliance requires servers to enforce scope-based access control on every API request.
Required Search Parameters
US Core mandates specific search parameters that every conformant server must support. These search parameters are critical for Inferno testing and ONC certification. Missing search parameter support is one of the most common reasons APIs fail validation.
Patient Search Parameters
The US Core Patient profile requires support for searching by: _id, identifier, name, birthdate + name, gender + name, and birthdate + family. Servers must return a Bundle containing matching Patient resources. The search must support exact and partial matching as specified in the profile.
Observation Search Parameters
Observation resources require search by: patient + category, patient + category + date, patient + code, and patient + category + status. The category parameter is essential because US Core uses different Observation profiles for different categories (laboratory, vital-signs, social-history, etc.).
Condition Search Parameters
Condition resources require: patient, patient + category, patient + clinical-status, patient + onset-date, and patient + code. The category search differentiates encounter-diagnosis from problem-list-item and health-concern categories.
Example: CapabilityStatement Search Parameter Declaration
Your server's CapabilityStatement must declare support for these search parameters. Here is an excerpt showing Observation search parameter declarations:
{
"type": "Observation",
"supportedProfile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-observation-lab",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-blood-pressure",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-bmi",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-body-height",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-body-weight",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-heart-rate",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-respiratory-rate",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-body-temperature",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-pulse-oximetry",
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-smokingstatus"
],
"interaction": [
{ "code": "read" },
{ "code": "search-type" }
],
"searchParam": [
{
"name": "patient",
"type": "reference"
},
{
"name": "category",
"type": "token"
},
{
"name": "code",
"type": "token"
},
{
"name": "date",
"type": "date"
},
{
"name": "status",
"type": "token"
}
]
}Validating with the Inferno Test Suite
The Inferno Framework is the ONC-approved testing tool for validating US Core compliance. It is the same tool used in the ONC certification process, which means passing Inferno tests is a strong indicator that your API will pass certification. Every development team building US healthcare APIs should integrate Inferno testing into their CI/CD pipeline.
Setting Up Inferno
Inferno can run locally via Docker or be accessed through the hosted instance at inferno.healthit.gov. For local development, the Docker setup is preferred:
git clone https://github.com/inferno-framework/inferno-core.git
cd inferno-core
docker-compose up -d
# Access at http://localhost:4567For US Core testing specifically, you will want the US Core test kit:
git clone https://github.com/inferno-framework/us-core-test-kit.git
cd us-core-test-kit
setup_inferno.sh
# Select US Core v8.0.1 test suiteKey Test Categories
The Inferno US Core test suite validates your server across several categories:
1. Capability Statement Validation: Inferno checks that your server returns a valid CapabilityStatement at /metadata, declares support for the correct US Core profiles, and lists required search parameters. This is the first test that runs and a prerequisite for all subsequent tests.
2. SMART on FHIR Authorization: Tests the full OAuth 2.0 authorization flow including discovery (via /.well-known/smart-configuration), authorization endpoint, token exchange, refresh tokens, and scope enforcement. This includes both standalone launch and EHR launch sequences.
3. Resource Validation: For each US Core profile, Inferno reads resource instances from your server and validates them against the profile's StructureDefinition. It checks required elements, Must Support elements, terminology bindings, and invariants.
4. Search Validation: Inferno tests every required search parameter combination for each resource type. It sends search requests and validates that the returned Bundle contains correctly filtered results. Search parameter chaining and modifiers are also tested.
5. Provenance: Tests that your server includes Provenance resources when _revinclude=Provenance:target is specified in search requests.
Running Inferno Against Your Server
When configuring Inferno for US Core testing, you need to provide:
- FHIR Server URL: Your FHIR base URL (e.g.,
https://fhir.example.com/fhir) - SMART Configuration: Authorization URL, token URL, client credentials
- Patient ID: A patient ID with sufficient test data across all US Core resource types
A common development strategy is to create a dedicated test patient seeded with comprehensive data covering every US Core profile. This patient should have at least one instance of every required resource type: conditions, observations (vital signs and labs), medications, allergies, immunizations, procedures, encounters, care plans, and care team members.
Common Validation Failures and How to Fix Them
After testing hundreds of FHIR implementations, we have identified the most frequent validation failures that trip up US Core developers. Here is a practical troubleshooting guide.
1. Missing meta.profile Declaration
Problem: Resources do not include meta.profile declaring which US Core profile they conform to. Inferno cannot determine which profile to validate against.
Fix: Always include the canonical URL of the US Core profile in meta.profile:
{
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
]
}
}2. Invalid Terminology Bindings
Problem: Using codes from incorrect code systems. The most common offenders are using free-text where a coded value is required, using local codes instead of standard terminologies, or using codes from the wrong version of a code system.
Fix: Always verify the binding strength (required, extensible, preferred, example) and use codes from the specified code systems. For required bindings, you must use a code from the specified value set. For extensible bindings, use a code from the value set if an appropriate one exists, but you may use an alternate code system if no suitable code exists.
3. Missing Must Support Elements
Problem: Server does not populate Must Support elements even when the data exists in the system. A common mistake is filtering out elements during serialization or not mapping internal fields to US Core Must Support elements.
Fix: Audit your data mapping to ensure every Must Support element in each US Core profile has a corresponding mapping from your internal data model. Use the Data Absent Reason extension when data is genuinely unavailable:
{
"birthDate": {
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
}4. Search Parameter Non-Compliance
Problem: Server does not support all required search parameter combinations or returns incorrect results. For example, supporting patient search on Observation but not the required patient + category combination.
Fix: Review each US Core profile's Quick Start section, which lists all required search parameter combinations. Implement each combination and verify that your search logic correctly filters results. Test with both existing and non-existing parameter values to ensure proper empty Bundle responses.
5. Incorrect Date Handling
Problem: Date search parameters do not support the required precision. US Core requires date searches to support comparators (eq, ne, gt, lt, ge, le, sa, eb, ap) and partial dates.
Fix: Implement date search with comparator support. A search for date=ge2025-01-01 should match all dates on or after January 1, 2025. A search for date=2025 should match all dates within the year 2025.
6. CapabilityStatement Mismatches
Problem: The CapabilityStatement declares support for profiles or search parameters that the server does not actually implement, or vice versa. Inferno cross-references the CapabilityStatement against actual behavior.
Fix: Generate your CapabilityStatement dynamically from your actual server configuration rather than maintaining it as a static document. This ensures it always reflects the server's true capabilities.
Migration Path: From Base FHIR to US Core
If you already have a FHIR R4 server and need to add US Core compliance, the migration follows a structured approach. This is a common scenario for teams that initially built a FHIR API for internal use and now need to meet ONC certification requirements. For organizations migrating from HL7 v2, the path involves both format conversion and profile conformance.
Step 1: Profile Your Resources
Add meta.profile declarations to all resources. Audit each resource type against the corresponding US Core profile to identify gaps in required and Must Support elements.
Step 2: Fix Terminology Bindings
Map all coded fields to the terminologies required by US Core. Patient.gender must use the AdministrativeGender value set. Condition.code should use SNOMED CT or ICD-10-CM. Observation codes should use LOINC. MedicationRequest medications should use RxNorm.
Step 3: Implement Required Extensions
Add US Core extensions to Patient resources: us-core-race, us-core-ethnicity, and us-core-birthsex at minimum. These are US-specific extensions that do not exist in base FHIR.
Step 4: Implement Search Parameters
Add support for all required search parameter combinations. This is typically the most labor-intensive step, as it requires building search logic for composite parameters and ensuring proper indexing.
Step 5: Add SMART on FHIR Authorization
Implement the SMART on FHIR authorization framework. This includes OAuth 2.0 endpoints, scope enforcement, launch context support, and the /.well-known/smart-configuration discovery document.
Step 6: Validate with Inferno
Run the Inferno test suite iteratively. Fix failures, re-test, and repeat until all applicable tests pass. Document any tests that are intentionally not applicable (for example, TLS tests in HTTP development environments).
Production Readiness Checklist
Before deploying a US Core-compliant API to production, verify the following:
- TLS 1.2+: All production endpoints must use HTTPS with TLS 1.2 or higher. This is a hard ONC requirement and Inferno tests for it.
- CapabilityStatement: Available at
/metadata, declares all supported US Core profiles, search parameters, and interactions. - SMART Configuration: Published at
/.well-known/smart-configurationwith authorization, token, and management endpoints. - All US Core Profiles: Every resource returned by the API conforms to the applicable US Core profile and includes
meta.profile. - Must Support Coverage: All Must Support elements are populated when data is available. Data Absent Reason extensions are used when data is unavailable but the reason is known.
- Search Parameter Support: All required search parameter combinations work correctly and return properly filtered Bundles.
- Provenance: Provenance resources are available via
_revincludefor all supported resource types. - Error Handling: Proper OperationOutcome resources are returned for errors, with meaningful issue codes and diagnostics.
- Rate Limiting: Implement rate limiting to prevent abuse while ensuring legitimate clinical workflows are not disrupted.
- Audit Logging: Log all API access for HIPAA compliance, including who accessed what data and when.
Frequently Asked Questions
What is the difference between FHIR R4 and FHIR US Core?
FHIR R4 is the base standard that defines resource types and their general structure. US Core is an Implementation Guide that adds US-specific constraints on top of FHIR R4. It mandates specific elements, terminologies (SNOMED CT, LOINC, RxNorm, ICD-10-CM), extensions (race, ethnicity, birthsex), and search parameters. You cannot be US Core compliant without first being FHIR R4 compliant, but being FHIR R4 compliant alone is not sufficient for the US market.
Is US Core compliance mandatory for all US healthcare APIs?
US Core compliance is mandatory for any health IT system seeking ONC certification, which includes EHR vendors, health information exchanges, and health IT modules used by CMS-regulated entities. Even if certification is not legally required for your product, most healthcare organizations will only purchase or integrate with US Core-compliant systems because it is the de facto standard for data exchange in the US.
How long does it take to implement US Core compliance from scratch?
For a team experienced with FHIR, implementing a US Core-compliant server from scratch typically takes 3 to 6 months depending on the number of profiles supported and the complexity of the underlying data model. Adding US Core compliance to an existing FHIR R4 server is faster, typically 4 to 8 weeks. The longest phases are usually search parameter implementation and Inferno test remediation.
What happens if my API fails Inferno tests?
Failing Inferno tests means your API does not meet US Core conformance requirements. For ONC certification, all applicable tests must pass. For non-certified systems, Inferno failures indicate interoperability gaps that will prevent successful data exchange with other US Core-compliant systems. Treat Inferno failures as bugs: identify the root cause, fix the implementation, and re-test.
How often does US Core get updated, and do I need to support multiple versions?
US Core publishes approximately one new STU version per year. ONC certification criteria specify which version to implement. Currently, implementations should support US Core 3.1.1 (the existing certification baseline) and prepare for US Core 6.1.0 or 7.0.0 (referenced in HTI-1). In practice, most systems implement the latest version and maintain backward compatibility. Inferno supports testing against multiple US Core versions.
Building US Core APIs with Confidence
FHIR US Core is the backbone of healthcare interoperability in the United States. It transforms broad regulatory mandates into actionable technical specifications. The path to compliance is well-documented, the validation tools are freely available, and the community support through HL7 and Inferno is robust.
The key to success is treating US Core compliance as a first-class engineering requirement, not an afterthought. Design your data models with US Core profiles in mind from day one. Map your internal terminologies to standard code systems early. Implement search parameters comprehensively. Run Inferno tests continuously, not just before certification.
If your team is building healthcare APIs for the US market and needs guidance on FHIR US Core implementation, our engineers have deep experience with US Core profiles, Inferno validation, and ONC certification requirements. Reach out to discuss your interoperability needs.
