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: ```bash # 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: ```json { "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: | Gap | US Core expects | Fix in the exporter | | --- | --- | --- | | Missing `code.coding` | A coded value (SNOMED/ICD-10 for Condition; LOINC for Observation; RxNorm for medication) | Ground the span; `codeable_concept([...])` with a real `coding`, not just `text` | | Missing `category` | `encounter-diagnosis`/`problem-list-item` (Condition), `laboratory`/`vital-signs` (Observation) | Set `category` in the resource shell | | Missing `clinicalStatus` / `status` | Required status fields | Set them per the `exporting-to-fhir` cheat-sheet | | Missing `subject` | A resolvable Patient reference | Reference an in-Bundle Patient; let `to_bundle` rewrite it | | Unbound `valueQuantity.code` | UCUM unit code | Use `system: http://unitsofmeasure.org` + UCUM code | | Vital signs not on the vitals profile | `us-core-vital-signs` shape (LOINC code, `vital-signs` category) | Use the vitals LOINC + category | "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. 5. Re-validate until clean; wire the validator into CI on synthetic fixtures. 6. 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: ```python 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