build

Validating a FHIR payload: what a validator can prove, and what ours refuses to guess

Updated 2026-07-29 · Level 2

Validation sounds like a verdict. It is actually a stack of separate questions — is this parseable, is it structurally legal FHIR, does it conform to the profiles it claims, do the codes come from the right systems, does it make operational sense — and each layer can only answer with the evidence it has. The honest output of a validator is not "valid"; it is a list of findings, each carrying what it was checked against.

The engine is the same one everyone uses. The official HL7 validator — the engine inside HAPI, the IG Publisher, and our workbench's sidecar — checks a payload against packages: the exact IG versions you name. The single highest-leverage habit is validating against the exact package versions your partner declared, because cross-version errors read like your bug and are actually their changelog.

Why we run it as a sidecar. The engine is a JVM service, so our workbench keeps it in a container and orchestrates it from the app. That split is why the workbench can be honest when infrastructure wobbles: if the sidecar is unreachable, a run reports the standards layer as unavailable and the affected dimensions as indeterminate — it never converts an outage into a payload failure. Infrastructure failure and invalid FHIR are different facts, and a tool that blurs them teaches you to distrust both.

Every finding tells you where its evidence came from. Interpretation results in the workbench carry a provenance label a reader can act on: Observed payer behavior, Documented payer policy, Expected (not yet observed), or Simulated (synthetic lab) — and anything that fails to declare itself presents as simulated, never as observed. The raw OperationOutcome from the standards engine stays available untouched on its own tab, because ground truth for debugging should never be replaced by our summary of it.

What our workbench deliberately refuses: it does not determine medical necessity, issue authorizations, or predict a real payer's decision; on production it accepts paste only (no file upload, by security posture); and a version that is not pre-warmed on the hosted validator says so and reports a degraded run rather than silently substituting a version you did not ask for.

Where to go deeper: how to read a lab explanation covers the plain-language layer on top of these findings, and the conformance-testing landscape covers proving conformance to someone else — which is a different job from checking a payload.

Go to the source