Not every FHIR endpoint needs profile validation. Not every endpoint needs terminology validation. Some workloads are served fully by structural validation — checking that the JSON is well-formed, that elements have the right cardinality, that polymorphic values are one of the allowed types. Adding more validation on top of that is either useful or overhead depending on the risk profile. Knowing which category your endpoint is in saves months of unnecessary work. The site's R4 resource vetter runs structural validation by default. For the wider FHIR framing, more FHIR for health plans has more.
What Structural Validation Actually Catches
- Malformed JSON
- Missing or misspelled resourceType
- Required elements missing
- Repeating elements holding scalars instead of arrays
- Elements with the wrong datatype
- Polymorphic value[x] using an unsupported type
- FHIRPath invariants declared on the base spec
That is a lot. For many endpoints, that is enough.
When Structural Is Enough
- Analytical workloads that only need the shape to be parseable
- Endpoints that store the resource and let downstream consumers apply their own rules
- Pilot integrations where the producers are early-stage and the rules would break them
- Any workload where the resource is a signal, not a contract
Each of these tolerates payloads that a profile-strict validator would reject. The trade-off is downstream systems have to be defensive.
When Structural Is Not Enough
- Endpoints supporting regulated workflows (CMS-0057, TEFCA, US Core)
- Endpoints where downstream logic depends on specific coded values
- Endpoints where profile conformance is contractual
- Endpoints where the response cost of processing bad data is high
Regulated workflows are the clearest case. If the regulation requires US Core conformance, structural validation is insufficient. For the profile-validation side, profile-based validation without a full IG deploy is the entry.
The Cost Trade-off
Structural validation is cheap — a schema pass and a small invariant check. Profile validation adds StructureDefinition loading, terminology lookups, and invariant expression evaluation. Full profile validation on every payload can be 10x the cost of structural alone.
For endpoints handling millions of writes per day, that cost matters. For endpoints handling thousands, it does not.
The Terminology Overhead Specifically
Terminology validation is the largest single cost of full validation. Value set expansion, code system membership checks, code-to-display resolution — each is a lookup. For the mechanics, terminology validation and the tradeoffs of enabling it covers the details.
You can validate structure without validating terminology. That is the common middle path.
The Risk-Based Frame
The right question is not "how much validation should we do" but "what is the cost of a payload that passes validation and is wrong?"
- Low cost — structural is enough
- Medium cost — structural plus specific coded-value checks
- High cost — full profile validation with terminology
That framing turns validation from an engineering trade-off into a risk trade-off. Both matter; the risk lens usually wins.
For introducing validation to an existing endpoint, validating incoming resources on an existing endpoint is the entry.
The Right Structural Baseline
Even for endpoints where structural is enough, the structural baseline should include:
- Base-spec cardinality
- Base-spec invariants
- Polymorphism checks
- resourceType verification
Skipping any of these produces the "well-formed JSON that is not really valid FHIR" case. Do not skip.
The Short Version
Structural validation covers a lot of real workloads. Profile and terminology validation are add-ons for endpoints where the risk of bad data is high. Frame the decision by risk, not by engineering ambition. For the boundary case, single-resource validation vs Bundle validation: knowing the boundary covers when validation is even in scope.
Sources
- HL7 canonical FHIR validation chapter - HL7 canonical FHIR validation chapter