SearchParameter — Découverte des recherches FHIR

Toute requête de recherche FHIR (GET /Patient?birthdate=ge2020) repose sur un SearchParameter. La ressource décrit ce qu'est un paramètre, son nom HTTP, son type, et son expression FHIRPath sur la ressource cible.

Objet de la ressource

Le core spec FHIR définit environ 1 500 SearchParameter standards (par exemple Patient.birthdate, Observation.code, Encounter.subject). Chacun a un code court (le nom dans l'URL) et une expression FHIRPath qui pointe vers le ou les éléments indexés.

Un serveur peut étendre les paramètres standard en publiant des SearchParameter personnalisés (typiquement dans un Implementation Guide), ou en restreindre la liste via la CapabilityStatement.

Champs clés

Champ	Type	Cardinalité	Rôle
`url`	uri	1..1	Obligatoire. URL canonique.
`name`	string	1..1	Nom machine.
`status`	code	1..1	État de publication.
`code`	code	1..1	Code HTTP utilisé dans l'URL (`birthdate` dans `?birthdate=...`).
`base`	code[]	1..*	Types de ressource auxquels s'applique le paramètre.
`type`	code	1..1	Type de recherche (voir liste).
`expression`	string	0..1	FHIRPath du nœud indexé.
`processingMode`	code	0..1	`normal`, `phonetic`, `other`. R5 (auparavant `xpathUsage`).
`target`	code[]	0..*	Pour les paramètres `reference` : types cibles autorisés.
`multipleOr`	boolean	0..1	Plusieurs valeurs combinables avec `,` ?
`multipleAnd`	boolean	0..1	Paramètre répétable dans l'URL avec ET implicite ?
`comparator`	code[]	0..*	Comparateurs autorisés (`eq`, `gt`, `lt`…).
`modifier`	code[]	0..*	Modifiers autorisés (`:exact`, `:contains`, `:not`…).
`chain`	string[]	0..*	Chaining autorisé sur ce paramètre.
`component`	BackboneElement[]	0..*	Pour les paramètres composites multi-éléments.

Types de SearchParameter

Type	Sémantique	Exemple
`number`	Nombre	`Observation?value-quantity=ge5`
`date`	Date / dateTime / Period	`Patient?birthdate=ge1980`
`string`	Chaîne (préfixe par défaut)	`Patient?family=Dupont`
`token`	system\|code, identifiant	`Patient?identifier=urn:oid:1.2\|MRN123`
`reference`	Référence vers une autre ressource	`Observation?patient=Patient/123`
`composite`	Combinaison de plusieurs paramètres	`Observation?code-value-quantity=8480-6$ge140`
`quantity`	Valeur + unité	`Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg`
`uri`	URL canonique ou URI	`ValueSet?url=http://hl7.org/fhir/ValueSet/...`
`special`	Comportement spécial	`Location?near=43.6\|7.04\|10\|km`

Exemple JSON

SearchParameter canonique Patient.birthdate :

json searchparameter-birthdate.json

{
  "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"]
}

Pièges courants

Expression FHIRPath invalide — un serveur ne pourra indexer que si l'expression résout un nœud valide sur la base de la StructureDefinition.
Confusion code vs name — le code est l'identifiant HTTP utilisé dans l'URL, name est le nom machine.
SearchParameter dupliqué côté serveur — deux SP avec le même code sur la même base mais expressions différentes : comportement indéterminé.
Recherche sur expression non indexable — un FHIRPath qui contient des conditionnels lourds (where, iif) peut ne pas être indexable : certains serveurs refusent.
Modifiers non supportés — un client qui utilise :contains ou :exact doit vérifier le support déclaré dans la CapabilityStatement.

Ressources liées

CapabilityStatement — liste les SearchParameter actifs par type de ressource.
StructureDefinition — la cible des expressions FHIRPath.
ImplementationGuide — package des SearchParameter custom.

Fondamentaux

Standards

Messages phares

Outils