Editorial illustration in editorial-gouache style depicting single-resource vs Bundle validation scope side by side with cross-entry rules highlighted
by: Daniel Friedman

Single-Resource Validation vs Bundle Validation: Knowing the Boundary

FHIR validation looks like one topic and is really two. Validating a single resource — is this Patient well-formed? — and validating a Bundle — do these entries reference each other correctly? — share tooling and vocabulary and diverge sharply on scope. Confusing the two is where teams end up with validators that pass single resources and fail Bundles or vice versa. The site's R4 resource vetter is deliberately scoped to single resources. For the wider setting, more on CMS-0057-F compliance has more.

What Single-Resource Validation Covers

  • The JSON is well-formed
  • The resourceType is set and recognized
  • Every element conforms to the base spec's structure and cardinality
  • Every polymorphic value uses one of the allowed types
  • Every coded value uses the right binding (if terminology validation is on)
  • Every FHIRPath invariant on the base spec passes

Everything that lives inside one resource is in scope. Everything that requires reading a second resource is not.

What Bundle Validation Adds

  • Bundle.type semantics — transaction vs batch handling
  • Entry.request and entry.response shape rules
  • fullUrl consistency across entries
  • Reference resolution — can this Observation actually find its subject Patient?
  • Cross-entry integrity — no dangling references, no cycles in transactions
  • Per-entry outcomes rolled up into a single response

Single-resource validation is a subset of Bundle validation, but only in the sense that Bundle validation includes it plus cross-entry rules. Running a single-resource validator on a Bundle catches structural issues on the Bundle itself, not on the cross-entry relationships.

The Common Failure Mode

Teams write a validator that inspects each entry as if it were a standalone resource, then declare the Bundle valid if every entry is valid. That misses:

  • References between entries with mismatched fullUrl semantics
  • urn:uuid: references that fail to rewrite atomically
  • Bundle.type = "transaction" with an entry.request.method that violates the type
  • Duplicate ids across entries

Each is a Bundle-level check. Each hides behind valid-looking entries.

For the specific case of profile-based checks on top, profile-based validation without a full IG deploy is the entry.

When To Use Single-Resource Validation

  • Validating a payload before creating it in a client
  • Vetting a resource pasted into a support tool
  • Onboarding a producer that emits one-at-a-time
  • Any pipeline where the resource arrives standalone

The vetter at /console/vet-a-resource/ is exactly this shape. Paste a resource, get a report. That is enough for the majority of debugging tasks.

When To Use Bundle Validation

  • Validating a batch or transaction before submitting to a server
  • Verifying an export produces coherent cross-references
  • Testing a workflow that assembles multiple resources
  • Pre-flight for a bulk import

Bundle validators need more machinery: a fullUrl index, a reference walker, transaction-mode rules. For the pipeline shape, resource validation in a batch pipeline covers it.

The meta.profile Overlap

Both validators can read Resource.meta.profile claims. When set, the resource is asserting conformance to specific profiles beyond the base spec. A single-resource validator that respects meta.profile runs the profile rules; one that ignores it accepts payloads the profile would reject.

Enforcing meta.profile is a decision worth naming explicitly. For the trade-offs, meta.profile: what it claims and what it costs to enforce is the entry.

The Trap: Loose Validators

A validator that accepts every payload is not useful. A validator that rejects every payload for minor issues is worse — it teaches the caller to bypass it. The right middle is severity-graded output: fatal for spec violations, error for profile violations, warning for optional issues, information for context.

For the response shape, an OperationOutcome is the FHIR-native form.

The Short Version

Single-resource validation catches structural, cardinality, polymorphism, and invariant issues within one resource. Bundle validation adds cross-entry rules. Pick the right validator for the shape of your input. For the vetter that focuses on single-resource, /console/vet-a-resource/ is the tool.

Editorial-gouache diagram of single-resource validation scope on the left contrasted with Bundle validation scope on the right, with cross-entry rules highlighted as the added surface, in soft coral gouache tones on cream paper

Sources