The FHIR Searches That Look Correct But Are Wrong

FHIR search is permissive on the way in. The server accepts the parameters, returns a searchset Bundle, and reports no error. That combination hides a category of queries that are syntactically valid, semantically wrong, and produce results that pass smoke tests until they hit real workloads. The site's FHIR search query auditor catches most of them at author time. For the wider setting, the FHIR integration playbook collects related material.

The Silent Failure Modes

Search parameter names that look like the FHIR canonical but are not (patient vs subject)
Modifier suffixes that are ignored because the server does not implement them
Date values without explicit timezone that get interpreted in the server's zone
Values with unencoded reserved characters that get truncated at the first & or ,
Composite parameters where the ordering of the two halves is wrong
Chained parameters that reference a non-searchable element on the target resource

Every one of these produces a 200 OK. The result set is wrong, not empty, and that is the trap.

Parameter Names Are Case-Sensitive And Canonical

FHIR search parameters have canonical names published in the CapabilityStatement per resource type. Observation.subject is queried by ?subject=, not ?patient=. A search that uses a made-up parameter is silently ignored on many servers — they return all Observations, not the filtered subset the caller intended.

Check the CapabilityStatement for the resource type. Every real search parameter is declared there. If the name is not in the list, the server will not filter on it. For the deeper set of rules, linter rules to catch the ten most common search mistakes enumerates them.

Modifiers Vary By Server

:contains, :exact, :not, :in, :missing are all defined by the spec, but not every server implements every modifier for every parameter. A query with :contains against a server that does not support it may be silently downgraded to a plain equality search — the result changes, no error surfaces. For the mechanic, modifier stacking: :not, :in, :missing without foot-guns covers the safe patterns.

Reserved Characters In Values

Commas separate multiple values. Ampersands separate parameters. Pipes separate system from code in token searches. Any of those characters in a raw value truncates the parameter unless properly encoded. ?name=O'Brien,Smith returns two results, not one. For the deeper picture, reserved characters in search values that break silently walks through the encoding.

Date Values Without Timezone

?date=2026-07-11 matches everything on July 11 in the server's timezone. ?date=2026-07-11T00:00:00Z is different. Callers who assume UTC while the server assumes local time end up with results that shift by up to a full day. For the mechanics, date search precision and the range it implicitly covers is the entry.

What The Auditor Catches

The auditor at /dev-tools/audit-fhir-query/ inspects the query string and calls out unrecognised modifiers, dodgy prefixes, deprecated names, and duplicate parameters. It does not run the query — it audits the shape. That is enough to prevent most of the wrong-but-quiet queries in this list.

The Short Version

FHIR search fails quietly by design. Every search parameter has a canonical name, every modifier has server-specific support, every value with reserved characters needs encoding, every date needs a timezone. The auditor is the fast check; the discipline is what keeps the queries correct in production.