FHIR terminology resources

Draft. This monograph is an unreviewed draft. Its sources have not been checked by a named person and no domain reviewer has approved it. Treat every claim as provisional.

Definition and scope

HL7 FHIR (Fast Healthcare Interoperability Resources, pronounced "fire") is a standard for exchanging healthcare information as discrete resources over a web interface. Among its resources are three that exist specifically to carry terminology: CodeSystem, ValueSet, and ConceptMap. Together with a small set of named operations they define what the specification calls a terminology service. This monograph describes those three resources and the operations around them as they are defined in FHIR Release 5, version 5.0.0, published by HL7 in 2023. Later releases exist or are in preparation; where a detail differs between releases, this page states R5 behavior and says so.

The reason to pin the release is not pedantry. ConceptMap in particular changed between Release 4 and Release 5: the element that records how a source code relates to a target code was renamed and its permitted values were revised. A page that said "ConceptMap has an equivalence element" would be describing R4. This page describes R5 (HL7, ConceptMap R5).

The scope is deliberately narrow. The page does not describe FHIR as a whole, does not describe how a clinical resource such as Observation binds to a value set beyond what the example needs, and does not describe any NucLex server, because none exists. All codes in the worked example are local teaching identifiers invented for this page.

Key distinctions

A code system defines; a value set selects; a concept map relates. A Code system is the authority for a set of codes and what each means. A Value set is a selection from one or more code systems for a particular use, such as the permitted answers to one field on a form. A Concept map is a set of statements that a code in one system corresponds, in some stated way, to a code in another. Confusing the first two is the most common error in practice: a value set does not define codes, it borrows them.

Exchange resource and ontology. The three resources are containers designed so that a terminology can travel between systems in a predictable shape. An ontology, in the sense developed in the Ontology monograph, is a formal account of what kinds of things exist and how they relate, usually with definitions a reasoner can process. A CodeSystem resource can carry a hierarchy and properties, and can point to a code system that is an ontology, but the resource is a transport for the terminology, not the theory behind it. A reader who wants to know whether lutetium-177 is a kind of radionuclide needs the source terminology's definition, not the FHIR wrapper around it.

Logical identity and version. Each of the three resources has a canonical URL that identifies it across servers and a version string. The same canonical URL with two different versions is two different artifacts. A ValueSet that says it includes "all codes from code system X" means all codes from the version of X that the server resolves at expansion time, unless a version is stated. This is where silent drift enters, and the Identifier concept page explains why an identifier without a version is incomplete.

Direction. A ConceptMap goes from a source to a target. The relationship recorded on each mapping is stated from the source's point of view. A map from A to B does not automatically yield a map from B to A, because a source code that is narrower than its target has a target that is broader than its source, and because many-to-one mappings cannot be reversed without loss.

Historical development

FHIR grew out of work by Grahame Grieve beginning around 2011, under HL7 International, as a reaction to the implementation difficulty of HL7 Version 3. The first Draft Standard for Trial Use appeared in 2014. Release 4, the first with normative content, was published at the end of 2018, and Release 5 followed in 2023 (HL7, FHIR R5). The terminology resources were present from the early drafts in some form; ValueSet came first, and CodeSystem was separated from it as a distinct resource so that a code system's definition and a selection from it would no longer be conflated.

The design draws on older experience. Cimino's desiderata (1998) for controlled vocabularies include explicit versioning, nonsemantic identifiers, and concept permanence, and the FHIR terminology resources encode those requirements as structure: a version element, a canonical URL distinct from any display text, and a status field that lets a concept be retired without being removed. The terminology service operations reflect the operations that earlier terminology servers already offered in proprietary forms. Bodenreider, Cornet, and Vreeman (2018) describe how the major clinical terminologies came to be distributed and consumed through FHIR interfaces, and SNOMED International's own Snowstorm server exposes a FHIR terminology API alongside its native one (Snowstorm repository).

Philosophical or technical account

One example, three resources

The following example is synthetic. Suppose a nuclear medicine department maintains a small local code system for the radiopharmaceutical administrations it records on its own forms. The department's informatics group publishes it as a FHIR CodeSystem with canonical URL http://teaching.nuclex.example/CodeSystem/nm-administrations and version 2026-10. The URL is a teaching address; it does not resolve.

The CodeSystem contains, among others, these concepts:

Code	Display	Property: role
NXT-001	Therapeutic administration of a lutetium-177 labelled radioligand	therapeutic
NXT-002	Therapeutic administration of a radium-223 containing agent	therapeutic
NXT-003	Diagnostic administration of a gallium-68 labelled PSMA ligand for PET	diagnostic
NXT-004	Diagnostic administration of fluorine-18 fluorodeoxyglucose for PET	diagnostic

Synthetic example: four concepts in a local teaching CodeSystem. Codes and displays are invented and are not mappings to any released terminology.

In R5 terms the CodeSystem resource declares its url, version, status, content (here complete, meaning every concept is listed in the resource), and a list of concept entries each with code, display, optionally definition, and property values. The property role is declared in the resource's property list with a type, so that a consumer knows therapeutic is a code from a small permitted set and not free text. A CodeSystem may also declare that its concepts form a hierarchy and what the hierarchy means (hierarchyMeaning: is-a, part-of, grouped-by, or classified-with), which is one of the places where the resource acknowledges that not every hierarchy is a subsumption hierarchy.

The department's therapy consent form needs a dropdown of therapeutic administrations only. It publishes a ValueSet with URL http://teaching.nuclex.example/ValueSet/therapeutic-administrations, version 2026-10, whose compose.include names the CodeSystem URL and the version 2026-10 and filters on role = therapeutic. The ValueSet does not restate the codes. If the department had instead listed NXT-001 and NXT-002 explicitly, the ValueSet would have the same expansion today but different behavior when NXT-005 is added next year with role therapeutic: the filter-based definition would include it, the enumerated one would not. Neither choice is wrong; the author must know which was intended.

The hospital's enterprise record uses a different local system, http://teaching.nuclex.example/CodeSystem/enterprise-procedures, with a single coarse code, EP-RNT, "Radionuclide therapy, unspecified agent," and a separate code EP-PET, "PET imaging procedure." The department publishes a ConceptMap from its administrations system (source) to the enterprise system (target):

Source code	Relationship (R5 value)	Target code	Comment
NXT-001	source-is-narrower-than-target	EP-RNT	Agent identity is lost in the target
NXT-002	source-is-narrower-than-target	EP-RNT	Agent identity is lost in the target
NXT-003	source-is-narrower-than-target	EP-PET	Tracer identity is lost in the target
NXT-004	source-is-narrower-than-target	EP-PET	Tracer identity is lost in the target

Synthetic example: a ConceptMap from a fine-grained local system to a coarse enterprise system. All codes are local teaching identifiers.

In R5 the ConceptMap resource records this in group entries, one per source and target system pair, each containing element entries for source codes and, under each, target entries with a code and a relationship. The permitted relationship values in R5 are related-to, equivalent, source-is-narrower-than-target, source-is-broader-than-target, and not-related-to (HL7, ConceptMap R5). The map also carries sourceScope and targetScope, which can name the value sets the map is meant to cover, and a version and status of its own. The map from NXT to EP is not the map from EP to NXT: a system holding EP-RNT cannot recover which agent was given, so the reverse map would have to say that EP-RNT is broader than each of several sources, and a translator asked to go from EP-RNT to NXT would have to return several candidates or none.

The operations

The FHIR terminology service page defines a set of operations, named with a leading dollar sign, that a server supporting these resources is expected to offer (HL7, Terminology Service R5). Four are central.

$lookup, invoked on CodeSystem, takes a system and code (or a Coding) and returns the display, definition, designations, and properties for that concept. In the example, a lookup of NXT-003 returns its display and the property role = diagnostic.

$validate-code, available on both CodeSystem and ValueSet, answers whether a given code is valid in a code system or is a member of a value set, and returns a result with a message. Validating NXT-003 against the therapeutic administrations ValueSet returns false, with a reason, which is exactly what the consent form's validator needs.

$expand, invoked on ValueSet, computes the list of codes the value set currently denotes, given the code system versions in force. For the therapeutic administrations ValueSet the expansion is NXT-001 and NXT-002. The expansion carries a timestamp and may record which code system versions were used, so that a later reader can tell whether the expansion is still current.

$translate, invoked on ConceptMap, takes a source code and returns the target codes and the relationship recorded for each. Translating NXT-001 returns EP-RNT with source-is-narrower-than-target. A receiving system that drops the relationship and stores only EP-RNT has thrown away the fact that information was lost.

Two other operations deserve a mention. $subsumes on CodeSystem asks whether one code subsumes another, which requires the server to know the code system's hierarchy and its meaning. And $closure maintains a subsumption table for a client. Both depend on the code system having a real subsumption hierarchy, which the local teaching system in the example does not.

What the resources do not do

A CodeSystem resource can say that NXT-001 has a property and a parent. It cannot say what makes something an instance of NXT-001, in the way that a description logic definition does (see Description logics). The resource can carry a reference to an external definition, and when the code system is SNOMED CT the FHIR specification describes how SNOMED CT's own semantics, including its Expression Constraint Language, are used in ValueSet filters (HL7, Using SNOMED CT with FHIR R5). But the reasoning happens in the terminology, not in FHIR. The W3C OWL 2 overview (2012) describes what a formal ontology language provides; FHIR is designed to interoperate with such content, not to replace it.

Likewise, a ConceptMap records that someone asserted a relationship between two codes. It does not record, in the base resource, the evidence for that assertion, the reviewer, or the confidence, beyond free-text comments and the resource's own metadata. Communities that need richer mapping provenance have proposed formats such as SSSOM, the Simple Standard for Sharing Ontological Mappings (Matentzoglu and colleagues 2022), which records predicate, justification, author, and confidence per mapping and can be exported to or from ConceptMap with some loss. The Provenance and evidence monograph takes up what a mapping's evidence record needs to hold.

Biomedical relevance

The practical importance of the three resources is that they make terminology a first-class object that can be versioned, validated, and moved, rather than a spreadsheet attached to an email. A laboratory information system, an electronic health record, a registry, and a research database can each retrieve the same ValueSet by canonical URL and version and expand it on the same terminology server, and when their results differ, the difference is traceable to a stated version.

The same machinery exposes where Semantic interoperability fails. A ValueSet that binds a field to "any code from SNOMED CT" is syntactically valid and semantically almost empty. A ConceptMap with every relationship set to equivalent because the author did not want to think about the alternatives is a liability disguised as an asset. The resources make the author's choices visible; they do not make them correct.

For a terminology that is itself an ontology, FHIR offers a way to deliver the terminology to systems that will never load an OWL file. The cost is that only the parts the resource can carry are delivered: codes, displays, properties, a hierarchy, and designations. The definitions that make the ontology an ontology remain in the source, and a consumer that needs them must go there.

Nuclear medicine relevance

Return to the synthetic department. Its own forms use NXT codes; the enterprise record uses EP codes; a national registry it reports to uses a third system; and a clinical trial it participates in uses a sponsor's case report form vocabulary. Four code systems describe one administration of one radioligand on one afternoon.

The question that matters for a nuclear medicine physician is not which system is "right" but which transformations lose what. Consider a single administration recorded as NXT-001. Mapped to the enterprise system it becomes EP-RNT, and the agent is gone. Mapped to the registry it may become a code for "lutetium-177 therapy" that preserves the radionuclide but not the targeting ligand. Mapped to the trial vocabulary it may become a protocol-specific code that preserves everything but is meaningless outside the trial. Each ConceptMap, if written honestly, records source-is-narrower-than-target on the first two and something closer to equivalent on the third, with a comment that the equivalence holds only within the protocol.

The consequence appears months later, when someone asks the enterprise data warehouse how many patients received a PSMA-targeted radioligand. The honest answer from EP-RNT alone is "unknown; the enterprise code does not distinguish agents." A warehouse that answers with a count has either gone back to the NXT source, which is correct, or has silently assumed that EP-RNT means PSMA, which is wrong. The $translate operation, with its relationship value, is the point at which the loss was declared; whether anyone read the declaration is a governance question, not a technical one.

This is also where the ontology role becomes concrete. If the department's code system were backed by definitions that said NXT-001 is an administration whose agent has a lutetium-177 radionuclide and a PSMA-targeting ligand, then a query for "PSMA-targeted" could be answered by the terminology, and the ConceptMap to the registry could be generated rather than hand-written, with its relationship values derived from the definitions. That is what the SNOMED CT and the NucLex niche monograph describes SNOMED CT's stated definitions as offering in principle. FHIR would then be the delivery channel for the result. NucLex has not built this; it is the kind of thing the NucLex discussion proposed (discussion record, sections 1 and 2), and the demonstration that would establish it is a server that expands a definition-based ValueSet correctly on a named edition.

Disagreements and limitations

NucLex has no live terminology endpoints. The discussion proposed FHIR terminology endpoints on a Snowstorm server and versioned CodeSystem, ValueSet, and ConceptMap resources for nuclear medicine content (discussion record, section 2). At the time of writing none of this is deployed. The teaching URLs on this page do not resolve, and no reader should attempt to call them. This page describes the specification, not a NucLex capability.

The release is pinned to R5, and R5 is not the only release in use. Much deployed software implements Release 4, in which ConceptMap uses an equivalence element with a different value set. Implementation guides also profile these resources in ways that constrain or extend what this page describes. A reader working against a specific server must read that server's capability statement and the release it implements.

Operation behavior varies between servers. The specification defines inputs and outputs for $expand, $validate-code, $lookup, and $translate, but leaves room in how servers resolve versions, handle large expansions, and report partial results. Conformance to the specification does not guarantee that two servers expand the same ValueSet identically if their loaded code system versions differ.

The example is deliberately small and the relationships are deliberately lossy. Real mappings between nuclear medicine procedure codes and enterprise or registry codes are more varied, include many-to-many cases, and are maintained by people under time pressure. The example shows the shape of the problem, not its scale.

Mapping provenance is thin in the base resources. The ConceptMap resource records assertions, not the evidence behind them. Whether that is a defect or an appropriate separation of concerns is argued both ways; SSSOM exists partly because the ontology community wanted the evidence in the same file. NucLex's own position, developed in the provenance monograph, is that a mapping without an evidence record is a proposal, not a fact.

The page has not been checked against the live specification text. Every element name and relationship value above is stated from the R5 specification as the writer understood it. The source check must confirm each against the pages listed in the references, and any discrepancy is a correction to this page, not to the specification.

FHIR, Code system, Value set, and Concept map: the lexicon entries for the four central terms.
Terminology server: what a server offering these operations is, independent of FHIR.
SNOMED CT and the NucLex niche: the terminology most often delivered through these resources, and the NucLex reuse question.
Controlled vocabularies: why a code list, a terminology, and an ontology are different, which is the distinction the CodeSystem resource straddles.
Semantic interoperability: the argument that identifiers and transport do not by themselves preserve meaning.
Provenance and evidence: what should travel with a mapping assertion.
Semantic interoperability and Identifier: the concept pages for the two ideas this monograph leans on most.

References

HL7. FHIR Release 5 (version 5.0.0). Terminology module. https://www.hl7.org/fhir/R5/terminology-module.html. Supports: the existence and purpose of the three terminology resources and the terminology service.
HL7. FHIR R5. Resource CodeSystem. https://www.hl7.org/fhir/R5/codesystem.html. Supports: CodeSystem elements including url, version, content, concept, property, and hierarchyMeaning.
HL7. FHIR R5. Resource ValueSet. https://www.hl7.org/fhir/R5/valueset.html. Supports: compose, include, filter, and expansion.
HL7. FHIR R5. Resource ConceptMap. https://www.hl7.org/fhir/R5/conceptmap.html. Supports: group, element, target, relationship values, sourceScope and targetScope, and the change from R4 equivalence.
HL7. FHIR R5. Terminology Service. https://www.hl7.org/fhir/R5/terminology-service.html. Supports: the set of named operations and their roles.
HL7. FHIR R5. Operation $lookup on CodeSystem. https://www.hl7.org/fhir/R5/codesystem-operation-lookup.html. Supports: lookup inputs and outputs.
HL7. FHIR R5. Operation $validate-code on ValueSet. https://www.hl7.org/fhir/R5/valueset-operation-validate-code.html. Supports: validation behavior.
HL7. FHIR R5. Operation $expand on ValueSet. https://www.hl7.org/fhir/R5/valueset-operation-expand.html. Supports: expansion behavior and version recording.
HL7. FHIR R5. Operation $translate on ConceptMap. https://www.hl7.org/fhir/R5/conceptmap-operation-translate.html. Supports: translation inputs and the returned relationship.
HL7. FHIR R5. Using SNOMED CT with FHIR. https://www.hl7.org/fhir/R5/snomedct.html. Supports: the use of SNOMED CT expression constraints in ValueSet filters.
HL7. FHIR R5. Resource Observation. https://www.hl7.org/fhir/R5/observation.html. Consulted for orientation on how clinical resources bind to value sets; not directly cited for a claim.
Matentzoglu N, Balhoff JP, Bello SM, et al. A Simple Standard for Sharing Ontological Mappings (SSSOM). Database. 2022;2022:baac035. Supports: the existence of a richer mapping provenance format.
Bodenreider O, Cornet R, Vreeman DJ. Recent developments in clinical terminologies: SNOMED CT, LOINC, and RxNorm. Yearbook of Medical Informatics. 2018;27(1):129-139. Supports: the distribution of major terminologies through FHIR interfaces.
Cimino JJ. Desiderata for controlled medical vocabularies in the twenty-first century. Methods of Information in Medicine. 1998;37(4-5):394-403. Supports: the desiderata the resources encode as structure.
W3C. OWL 2 Web Ontology Language Document Overview (Second Edition). 2012. https://www.w3.org/TR/owl-overview/. Supports: what a formal ontology language provides that an exchange resource does not.
SNOMED International. Snowstorm terminology server. https://github.com/IHTSDO/snowstorm. Supports: the existence of a server exposing a FHIR terminology API for SNOMED CT.