validating-us-core

Validating US Core

Producing syntactically valid R4 (which exporting-to-fhir and assembling-fhir-bundles do) is not the same as conforming to US Core — the HL7 US realm profiles that EHRs (Epic, Cerner/Oracle Health) require for ingestion and that USCDI mandates for certified exchange. This skill validates OpenMed-produced FHIR against US Core before you submit it.

When to use

Use it as the gate right before submission, after you have assembled a Bundle. Reach for it when the user says "US Core", "USCDI", "must-support", "will Epic accept this", or "validate my FHIR". It is the conformance counterpart to the mechanical builders — OpenMed builds the JSON; the HL7 validator judges it.

Quick start: run the official validator

The reference implementation is the HL7 validator_cli.jar (the same engine behind https://validator.fhir.org). Validate against the US Core package by IG:

# One-time: get the validator
curl -L -o validator_cli.jar \
  https://github.com/hapifhir/org.hl7.fhir.core/releases/latest/download/validator_cli.jar

# Validate a resource/Bundle against the current US Core IG
java -jar validator_cli.jar condition.json \
  -version 4.0.1 \
  -ig hl7.fhir.us.core \
  -tx https://tx.fhir.org            # terminology server for code validation

-ig hl7.fhir.us.core pulls the current published US Core package; pin a version (e.g. -ig hl7.fhir.us.core#6.1.0) for reproducible CI. The validator exits non-zero on errors and prints issues with FHIRPath locations.

For ad-hoc checks without a JVM, paste the JSON into the public validator UI at https://validator.fhir.org (do not paste real PHI — validate synthetic or de-identified resources only).

Declare the profile you claim

US Core only validates against a profile if the resource claims it via meta.profile. Add the canonical URL for the profile you target:

{
  "resourceType": "Condition",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-condition-problems-health-concerns"
    ]
  }
}