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"
    ]
  }
}

Then java -jar validator_cli.jar condition.json -ig hl7.fhir.us.core checks it
against that profile's constraints, including must-support elements.

Common conformance gaps (from OpenMed output)

OpenMed NER gives you the clinical mention; US Core wants structured context.
The recurring gaps when going from raw spans to US Core:

"Must-support" means the producer must populate the element when the data
exists. The validator flags must-support omissions as warnings; certified
systems may reject them.

Workflow

1. Export + assemble the Bundle (exporting-to-fhir, assembling-fhir-bundles).
2. Add meta.profile for the US Core profile each resource targets.
3. Run validator_cli.jar with -ig hl7.fhir.us.core and a -tx server.
4. Read the issues: error = will be rejected; warning = must-support /

best practice. Fix errors in the exporter, not by hand-editing JSON.

1. Re-validate until clean; wire the validator into CI on synthetic fixtures.
2. Submit (assembling-fhir-bundles for the transaction POST).

Turn validator output into an OperationOutcome

If you run validation programmatically, adapt the result into a FHIR
OperationOutcome with OpenMed's helper so the rest of your pipeline speaks one
shape:

from openmed.clinical.exporters.fhir import from_validation_result

# `result` exposes issues, or errors/warnings/information buckets
outcome = from_validation_result(result)   # -> R4 OperationOutcome dict

from_validation_result understands either an issues collection or
errors/warnings/information buckets (strings or issue objects) and emits a
clean R4 OperationOutcome (all-ok when empty). It only reads structural
metadata — keep diagnostics PHI-free.

Hand-off to / from OpenMed

• Validate OpenMed-produced FHIR: the input is the Bundle from

assembling-fhir-bundles; the output is conformance issues you fix back in
exporting-to-fhir.

• OperationOutcome bridge: from_validation_result /

to_operation_outcome / OperationOutcomeIssue (all in
openmed.clinical.exporters.fhir) convert validator findings to R4.

• No PHI in validation: validate synthetic or de-identified resources. If a

narrative might carry PHI, run openmed.interop.fhir_operations.de_identify_bundle
first.

Edge cases & gotchas

• No meta.profile, no profile check. The validator validates base R4 only

unless the resource claims the profile (or you force it with -profile <url>).

• Terminology binding needs a -tx server. Without -tx, code-system /

value-set bindings are not fully checked; many US Core required bindings
will be missed. Point -tx at https://tx.fhir.org or your own Ontoserver.

• Pin the IG version in CI (hl7.fhir.us.core#<version>). US Core revisions

change must-support and bindings; an unpinned run drifts.

• Reference resolution in Bundles. Validate the whole Bundle so

urn:uuid references resolve; validating a lone resource flags references it
cannot see.

• USCDI ≠ US Core. USCDI is the data-element regulation; US Core is the FHIR

profile set that implements it. Conform to the US Core profile for the
matching USCDI class.

• Warnings can still block ingestion. Some EHRs reject must-support

omissions even though the validator calls them warnings. Treat must-support as
required for production.

Standards & references

• US Core Implementation Guide: https://hl7.org/fhir/us/core/
• US Core profiles list: https://hl7.org/fhir/us/core/profiles-and-extensions.html
• USCDI: https://www.healthit.gov/isp/united-states-core-data-interoperability-uscdi
• HL7 FHIR validator (CLI + docs): https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator
• Public validator: https://validator.fhir.org
• Public terminology server: https://tx.fhir.org