CodeSystem, ValueSet, and the $expand and $validate-code Operations

From terminology ideas to FHIR resources

The Terminologies course established a set of ideas that travel across every health data standard: large code systems such as SNOMED CT, LOINC, ICD, and RxNorm; the value sets that select codes for a particular use; the binding that ties a coded field to one of those value sets; and the “code + system + display” triplet that makes a coded value meaningful. FHIR does not replace any of that — it gives each idea a concrete representation as a resource or an operation. This lesson maps the familiar concepts onto the FHIR machinery that implements them.

Two resources carry the load. A CodeSystem declares codes and what they mean. A ValueSet selects a subset of codes for a use. A small family of terminology operations then does the runtime work: expanding a value set into its members, and validating whether a code belongs.

The CodeSystem resource

A CodeSystem resource declares a set of codes together with their meanings — their display text, definitions, and relationships ¹. Each code system has a canonical system URL that uniquely identifies it; this is the same system value that appears inside every Coding (the “system” half of the triplet).

A crucial design choice keeps FHIR practical: it does not re-publish the giant external terminologies. SNOMED CT, LOINC, and RxNorm are referenced by their canonical system URLs rather than copied into FHIR servers — a CodeSystem resource can describe such a system and point to it without enumerating its hundreds of thousands of codes ¹. Only small or local code systems are typically defined directly, with their codes listed inline in the concept element.

CodeSystem (small, defined inline)
  url:     http://example.org/fhir/CodeSystem/lab-priority
  content: complete
  concept:
    - code: R   display: "Routine"
    - code: S   display: "STAT"

The ValueSet resource

A ValueSet resource defines a selected set of codes for a particular use ¹. The selection lives in the compose element, which lists one or more include (and optional exclude) blocks. Each block draws from a code system identified by its system URL and either enumerates specific codes or selects them with filters (for example, all descendants of a SNOMED CT concept). This include/exclude composition is exactly the “select codes for a use” idea from the Terminologies course, expressed as data.

ValueSet.compose
  include:
    - system: http://loinc.org
      concept:
        - code: "789-8"   display: "Erythrocytes [#/volume] in Blood by Automated count"
        - code: "718-7"   display: "Hemoglobin [Mass/volume] in Blood"

A coded element in a resource is bound to a value set — the binding names which value set supplies the allowed codes for that field, and the binding strength says how strictly it applies. The codes themselves still arrive as Coding or CodeableConcept values carrying system + code + display, so the value set constrains which codings are acceptable, not how they are written down.

Terminology operations

Resources describe terminology; operations let a client act on it. FHIR groups these as a terminology service ¹. Three are worth knowing.

$expand runs on a ValueSet and produces the explicit, flat list of member codes — the expansion ¹. A value set defined with filters (such as “descendants of a SNOMED CT concept”) is not a usable pick-list until it is expanded; $expand resolves the rules against the underlying code systems and returns the concrete codes, which is what a user interface needs to populate a dropdown.

GET [base]/ValueSet/lab-tests/$expand

-> ValueSet with expansion.contains:
     [{ system: http://loinc.org, code: "789-8", display: "Erythrocytes..." },
      { system: http://loinc.org, code: "718-7", display: "Hemoglobin..." }]

$validate-code checks whether a given code is a valid member of a ValueSet or of a CodeSystem ¹. It answers a yes/no question — is this code allowed here? — and returns a result boolean plus a message. This is how a server enforces a binding when a resource is submitted.

GET [base]/ValueSet/lab-tests/$validate-code?system=http://loinc.org&code=789-8

-> Parameters: result = true

Finally, $lookup runs on a CodeSystem and returns details about a single code — its display name and properties — when you have a code and need to know what it means ¹.

Where value sets come from: VSAC

Authoring and governing value sets by hand does not scale across an enterprise, so the ecosystem relies on published, governed value sets. The U.S. National Library of Medicine’s Value Set Authority Center (VSAC) publishes curated value sets — drawn from SNOMED CT, LOINC, RxNorm, and other systems — that are maintained, versioned, and consumed directly in FHIR terminology workflows ². Rather than each project defining its own “diabetes diagnoses” or “blood glucose tests” list, teams reference a VSAC value set and let $expand and $validate-code operate against it — closing the loop between the terminology concepts you already know and the FHIR resources and operations that put them to work.