SearchParameter — FHIR search discovery
Every FHIR search request (GET /Patient?birthdate=ge2020) is backed by a
SearchParameter. The resource describes what a parameter is: its HTTP name, type, and
FHIRPath expression on the target resource.
Purpose
The FHIR core spec defines roughly 1,500 standard SearchParameters (e.g.
Patient.birthdate, Observation.code,
Encounter.subject). Each has a short code (the URL name) and
a FHIRPath expression pointing to the indexed element(s).
A server may extend the standard parameters by publishing custom SearchParameters (typically in an Implementation Guide), or shrink the list via its CapabilityStatement.
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
url | uri | 1..1 | Mandatory. Canonical URL. |
name | string | 1..1 | Machine name. |
status | code | 1..1 | Publication status. |
code | code | 1..1 | HTTP code used in URLs (birthdate in ?birthdate=...). |
base | code[] | 1..* | Resource types the parameter applies to. |
type | code | 1..1 | Search type (see list). |
expression | string | 0..1 | FHIRPath of indexed node. |
processingMode | code | 0..1 | normal, phonetic, other. R5 (was xpathUsage). |
target | code[] | 0..* | For reference parameters: allowed target types. |
multipleOr | boolean | 0..1 | Several values combinable with ,? |
multipleAnd | boolean | 0..1 | Parameter repeatable in URL with implicit AND? |
comparator | code[] | 0..* | Allowed comparators (eq, gt, lt...). |
modifier | code[] | 0..* | Allowed modifiers (:exact, :contains, :not...). |
chain | string[] | 0..* | Chaining allowed on this parameter. |
component | BackboneElement[] | 0..* | For composite multi-element parameters. |
SearchParameter types
| Type | Semantics | Example |
|---|---|---|
number | Number | Observation?value-quantity=ge5 |
date | date / dateTime / Period | Patient?birthdate=ge1980 |
string | String (default: prefix match) | Patient?family=Dupont |
token | system|code, identifier | Patient?identifier=urn:oid:1.2|MRN123 |
reference | Reference to another resource | Observation?patient=Patient/123 |
composite | Combination of several parameters | Observation?code-value-quantity=8480-6$ge140 |
quantity | Value + unit | Observation?value-quantity=5.4|http://unitsofmeasure.org|mg |
uri | Canonical URL or URI | ValueSet?url=http://hl7.org/fhir/ValueSet/... |
special | Special behaviour | Location?near=43.6|7.04|10|km |
JSON example
The canonical Patient.birthdate SearchParameter:
{
"resourceType": "SearchParameter",
"id": "Patient-birthdate",
"url": "http://hl7.org/fhir/SearchParameter/Patient-birthdate",
"version": "5.0.0",
"name": "birthdate",
"status": "active",
"experimental": false,
"date": "2026-05-14",
"publisher": "HL7 (FHIR Project)",
"description": "The patient's date of birth",
"code": "birthdate",
"base": ["Patient"],
"type": "date",
"expression": "Patient.birthDate",
"xpath": "f:Patient/f:birthDate",
"xpathUsage": "normal",
"comparator": ["eq", "ne", "gt", "ge", "lt", "le", "sa", "eb", "ap"]
}Common pitfalls
- Invalid FHIRPath expression — a server can only index if the expression resolves to a valid node against the StructureDefinition.
- Confusing
codevsname—codeis the HTTP identifier used in URLs,nameis the machine name. - Duplicate SearchParameter on the server — two SPs with same
codeon samebasebut different expressions: undefined behaviour. - Search on non-indexable expression — a FHIRPath with heavy conditionals (
where,iif) may not be indexable: some servers refuse. - Unsupported modifiers — a client using
:containsor:exactmust check support declared in the CapabilityStatement.
Related resources
- CapabilityStatement — lists active SearchParameters per resource type.
- StructureDefinition — target of FHIRPath expressions.
- ImplementationGuide — package for custom SearchParameters.