ValueSet — Sélection de codes pour un binding

Tout champ FHIR de type code ou CodeableConcept est lié à un ValueSet par un binding. ValueSet est ainsi la pierre angulaire de la terminologie clinique FHIR.

Objet de la ressource

ValueSet sélectionne un sous-ensemble de codes parmi un ou plusieurs CodeSystem, pour être utilisé comme binding par les éléments FHIR (Patient.gender, Observation.code, Condition.severity…). Un ValueSet a deux faces :

Définition (compose) — les règles d'appartenance : « tous les codes de SNOMED descendants de 386053000 ».
Expansion (expansion) — la liste effective des codes à un instant donné.

L'opération $expand calcule l'expansion à partir de la définition, en tenant compte de la version de chaque CodeSystem (SNOMED 2026-03, LOINC 2.78, etc.).

Champs clés

Champ	Type	Cardinalité	Rôle
`url`	uri	0..1	URL canonique du ValueSet.
`version`	string	0..1	Version du ValueSet.
`name`	string	0..1	Nom machine.
`status`	code	1..1	État de publication.
`immutable`	boolean	0..1	Le ValueSet ne change-t-il jamais ? Si oui, expansion stable.
`compose`	BackboneElement	0..1	Règles d'inclusion / exclusion.
`compose.include`	BackboneElement[]	0..*	Source(s) à inclure.
`compose.include.system`	uri	0..1	URL canonique du CodeSystem source.
`compose.include.concept`	BackboneElement[]	0..*	Codes explicitement listés.
`compose.include.filter`	BackboneElement[]	0..*	Filtre par propriété (ex : « is-a 386053000 »).
`compose.include.valueSet`	canonical[]	0..*	Inclusion d'un autre ValueSet.
`compose.exclude`	BackboneElement[]	0..*	Exclusions.
`expansion`	BackboneElement	0..1	Liste effective de codes (calculée).
`expansion.timestamp`	dateTime	1..1	Quand l'expansion a été calculée.
`expansion.contains`	BackboneElement[]	0..*	Codes effectifs.

Binding strength

Dans une StructureDefinition, un binding ValueSet est qualifié par une force (binding strength) :

Force	Sens
`required`	Le code DOIT venir du ValueSet.
`extensible`	Le code DEVRAIT venir du ValueSet, sauf si aucun code adapté : alors fournir un texte ou un autre système.
`preferred`	Le ValueSet est recommandé mais non imposé.
`example`	Le ValueSet est un exemple, libre.

Exemple JSON

Le ValueSet canonique administrative-gender utilisé pour Patient.gender :

json valueset-administrative-gender.json

{
  "resourceType": "ValueSet",
  "id": "administrative-gender",
  "url": "http://hl7.org/fhir/ValueSet/administrative-gender",
  "version": "5.0.0",
  "name": "AdministrativeGender",
  "title": "AdministrativeGender",
  "status": "active",
  "experimental": false,
  "date": "2026-05-14",
  "publisher": "HL7 International (FHIR Project)",
  "description": "The gender of a person used for administrative purposes.",
  "immutable": true,
  "compose": {
    "include": [{
      "system": "http://hl7.org/fhir/administrative-gender",
      "concept": [
        { "code": "male",    "display": "Male" },
        { "code": "female",  "display": "Female" },
        { "code": "other",   "display": "Other" },
        { "code": "unknown", "display": "Unknown" }
      ]
    }]
  }
}

Opérations $expand et $validate-code

GET [base]/ValueSet/123/$expand — calcule l'expansion.
GET [base]/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/administrative-gender — expand par URL canonique.
GET [base]/ValueSet/123/$validate-code?code=male&system=http://hl7.org/fhir/administrative-gender — valide qu'un code appartient au ValueSet.

Ces opérations sont décrites par OperationDefinition et exposées par les serveurs de terminologie (TX server) comme tx.fhir.org, Ontoserver, Hapi FHIR.

Pièges courants

Confondre url et identifier — l'url est l'URL canonique unique, qui est aussi la cible des bindings.
Filter is-a sur un CodeSystem qui n'expose pas la hiérarchie — vérifier CodeSystem.hierarchyMeaning avant d'utiliser un filtre is-a.
Expansion sans version de CodeSystem — l'expansion DOIT figer la version (system.version) pour reproductibilité.
ValueSet trop large (SNOMED full) — un binding required à un ValueSet de plusieurs millions de codes ralentit toute validation.
Code dans concept[] mais hors CodeSystem source — incohérence : le code doit exister dans le CodeSystem cité.

Ressources liées

CodeSystem — source de codes utilisés par le ValueSet.
ConceptMap — mapping entre deux ValueSet.
NamingSystem — identifiants alternatifs des systèmes.
StructureDefinition — où les bindings sont déclarés.

Fondamentaux

Standards

Messages phares

Outils