ediverse

Type to search across standards, messages, tools and glossary.

ediverse Explore the platform

Spotlight PEPPOL BIS Billing 3.0 The EU e-invoicing mandate is here — France Sept 2026, Belgium Jan 2026, Germany 2025.

— 01

Foundations

— 02

Standards

— 03

Flagship messages

— 04

Tools

ValueSet — Code selection for a binding

Every FHIR code or CodeableConcept field is tied to a ValueSet through a binding. ValueSet is therefore the cornerstone of FHIR clinical terminology.

Purpose

ValueSet selects a subset of codes from one or more CodeSystems, to be used as a binding by FHIR elements (Patient.gender, Observation.code, Condition.severity...). A ValueSet has two faces:

  • Definition (compose) — membership rules: "all SNOMED codes descending from 386053000".
  • Expansion (expansion) — the actual list of codes at a given moment.

The $expand operation computes the expansion from the definition, accounting for the version of each CodeSystem (SNOMED 2026-03, LOINC 2.78, etc.).

Key fields

FieldTypeCardinalityRole
urluri0..1Canonical URL of the ValueSet.
versionstring0..1ValueSet version.
namestring0..1Machine name.
statuscode1..1Publication status.
immutableboolean0..1Is the ValueSet stable forever? If yes, expansion stable.
composeBackboneElement0..1Inclusion / exclusion rules.
compose.includeBackboneElement[]0..*Source(s) to include.
compose.include.systemuri0..1Canonical URL of source CodeSystem.
compose.include.conceptBackboneElement[]0..*Codes listed explicitly.
compose.include.filterBackboneElement[]0..*Property-based filter (e.g. "is-a 386053000").
compose.include.valueSetcanonical[]0..*Include another ValueSet.
compose.excludeBackboneElement[]0..*Exclusions.
expansionBackboneElement0..1Actual list of codes (computed).
expansion.timestampdateTime1..1When expansion was computed.
expansion.containsBackboneElement[]0..*Actual codes.

Binding strength

In a StructureDefinition, a ValueSet binding is qualified by a strength (binding strength):

StrengthMeaning
requiredCode MUST come from the ValueSet.
extensibleCode SHOULD come from the ValueSet, unless no suitable code exists: then provide text or another system.
preferredThe ValueSet is recommended but not enforced.
exampleThe ValueSet is illustrative, free choice.

JSON example

The canonical administrative-gender ValueSet used for 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" }
      ]
    }]
  }
}

$expand and $validate-code

  • GET [base]/ValueSet/123/$expand — computes the expansion.
  • GET [base]/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/administrative-gender — expand by canonical URL.
  • GET [base]/ValueSet/123/$validate-code?code=male&system=http://hl7.org/fhir/administrative-gender — checks a code belongs to the ValueSet.

These operations are declared by OperationDefinition and exposed by terminology servers (TX server) like tx.fhir.org, Ontoserver, HAPI FHIR.

Common pitfalls

  • Confusing url and identifier — url is the unique canonical URL, which is also the binding target.
  • is-a filter on a CodeSystem without hierarchy — check CodeSystem.hierarchyMeaning before using an is-a filter.
  • Expansion without CodeSystem version — expansion MUST pin the version (system.version) for reproducibility.
  • ValueSet too broad (full SNOMED) — a required binding to a multi-million-code ValueSet slows every validation.
  • Code listed in concept[] but outside the source CodeSystem — inconsistency: the code must exist in the cited CodeSystem.
  • CodeSystem — source of codes used by the ValueSet.
  • ConceptMap — mapping between two ValueSets.
  • NamingSystem — alternate identifiers of systems.
  • StructureDefinition — where bindings are declared.