A FHIRPath expression that passes on the demo resource in the spec often fails on the payload that actually arrives from a production server. Real resources carry extensions the demo does not have, empty collections in places the demo has populated, and coded values from local terminologies the demo does not model. Testing an expression against real payloads before shipping it is the difference between a robust invariant and one that starts flagging incidents on the second Tuesday. The site's FHIRPath live tryout is where you paste a real payload and watch the expression evaluate. For the wider FHIR framing, our FHIR reference shelf collects related material.
What "Real Production" Actually Means
- Payloads with unexpected extensions on nearly every resource
- Resources with missing optional elements the demo populated
- Coded values from local extensions and refsets
- Bundles with mixed resource types
- Contained resources with their own quirks
- Contextual references that resolve or don't
The demo Patient in the spec has clean data. The Patient your integration receives has fifteen extensions, a family name with a comma in it, three telecom entries with one blank system, and an identifier list with two MRN slices. Testing the expression against clean data proves nothing about the production case.
Collect a Small Corpus
Ten to twenty real payloads is enough for most testing. Pull them from a staging environment or a controlled slice of production, strip PHI, keep the shape. The corpus becomes the fixture that every new expression gets evaluated against.
The corpus does not need to be exhaustive — it needs to cover the shapes the profile is meant to accept. A payload without a family name, a payload with two names, a payload with a modifier extension, a payload with a coded value from a local extension. Each of those is a class of shape worth covering.
Test For Three Outcomes
- Positive: the payload is valid and the expression returns true
- Negative: the payload is invalid and the expression returns false
- Empty: the target field is absent and the expression behaves as intended
The third case is where most invariants leak. An expression that assumes the field is present quietly evaluates against empty on a payload that legitimately does not have it. For the mechanic, using FHIRPath in invariants without shooting yourself in the foot covers the pattern.
Run Against Multiple Engines
FHIRPath evaluators drift. Different implementations handle edge cases — order preservation, coercion between types, truthiness of empty collections — differently. An expression that passes on one engine may fail on another. Testing against at least two engines catches the drift.
The tryout at /toolbox/try-fhirpath-live/ runs a standards-compliant subset that is close to the canonical spec. Running the same expression against your target server's built-in evaluator is a good second check.
Log the Evaluation Path
When an expression fails, the useful diagnostic is not just "false" — it is where in the pipeline the collection became empty or the type diverged. A tryout that shows intermediate collection sizes at each step of the pipeline turns a mystery failure into a two-minute fix.
For the debugging pattern, reading a failing FHIRPath expression and finding the type mismatch is the entry.
Wire It Into CI
Every expression in a profile should be exercised in CI against the corpus. That way a change to a profile that breaks an existing payload gets caught before merge, not on the next validation run in production. Ten minutes of setup, a permanent shift in signal quality.
The Trap: Cleaned Payloads
Payloads that have been stripped and reformatted for storage may lose signals that the invariant depends on. Test against payloads captured before any post-processing — the ones that arrived on the wire. For the collection semantics that make this matter, the collection semantics that surprise you at first covers the ground.
The Short Version
Collect real payloads, test three outcomes, run against multiple engines, log the pipeline, wire it into CI. The invariant that survives production is the one that has already faced the shapes production emits.
Sources
- HL7 canonical FHIRPath specification - HL7 canonical FHIRPath specification
