Adding validation to an existing FHIR endpoint is not usually a greenfield decision. There is already an endpoint, already producers sending to it, already downstream systems consuming from it. Introducing validation means picking a place to run it, a severity policy that does not break existing flows, and a response shape that helps rather than confuses. Doing it well is a two-week project; doing it poorly is a two-month incident. The site's R4 resource vetter is where teams stage validation logic before shipping it inline. For the wider FHIR framing, related Prior Auth API guides have more.
Where To Run The Validator
- At the edge — before the resource hits business logic
- Inline — as a step in the write path, with the ability to reject
- Async — post-write, with a separate feedback loop
- Batched — periodically, across payloads that already landed
Each shifts different trade-offs. Edge validation is the strictest and the most likely to break existing producers. Async is safe to add without breaking anything but does not prevent bad data from landing.
Most existing endpoints add async first, iterate on the rules, then move to edge once the rules are stable.
Start With Structural Only
Terminology validation and profile validation are heavier and more likely to reject well-intentioned payloads. Structural validation — schema, cardinality, polymorphism — is the safe first step.
For the mechanics of when structural is enough, when structural validation is enough for your risk profile is the entry.
Log Before Enforcing
The right rollout sequence:
- Log-only for two weeks — see what real payloads produce
- Warn to sender for two weeks — surface without blocking
- Enforce on a subset — pilot with willing producers
- Enforce for everyone — after the pilot succeeds
Each phase gives you a chance to catch overly-strict rules before they block business traffic. Skipping phases is how validators end up rolled back within a week of launch.
Route By Producer
Different producers may have different maturity. An internal service may be ready for strict validation before an external partner is. Route rules by producer identity when possible — reject on the strict path, warn on the lenient path.
That is a small piece of infrastructure and a significant political convenience. For the base pattern of what a validator is checking, single-resource validation vs Bundle validation: knowing the boundary is the entry.
Choose Where meta.profile Fits
An existing endpoint may already receive meta.profile claims. The validator's meta.profile policy matters:
- Accept claim → verify against claimed profile
- Ignore claim → verify against configured profile
- Both → surface divergence
For the deeper trade-offs, meta.profile: what it claims and what it costs to enforce is the entry.
Response Shape Matters
Every rejection needs an OperationOutcome that tells the sender what to fix. Blanket 400 with a text message does not scale — senders cannot triage across a fleet of similar responses.
Structured OperationOutcome with severity, code, expression, and diagnostics is the FHIR-native form. For the design side, OperationOutcome design for validator responses covers it.
The Backward Compatibility Trap
An endpoint that used to accept everything now rejects some payloads. Producers that never validated their output see errors. That is a real backward-compatibility break, even when the payloads were technically wrong.
Communicate before launching. Provide a validator producers can use before submission. The vetter is exactly this shape — external producers paste their payload, see what would fail, fix before sending.
The Short Version
Introduce validation gradually. Log before enforce. Route by producer. Choose profile behavior deliberately. Emit structured OperationOutcome. Provide senders a way to check before submitting. That is how a validator lands without incident.
Sources
- HL7 canonical FHIR validation chapter - HL7 canonical FHIR validation chapter