FHIR Terminology Explained: Coding, CodeSystem, ValueSet, ConceptMap and $validate-code
How codes work in FHIR: Coding vs CodeableConcept, system URIs for LOINC, SNOMED CT and RxNorm, binding strengths, and $lookup, $validate-code and $expand.
By the FHIR Toolbox team, Omindra Labs · 5 min read ·
Checked against the official specifications listed under Standards and references at the end of this article.
Most of the meaning in clinical data lives in codes. "Observation with value 7.2" means nothing; "LOINC 4548-4 (Hemoglobin A1c) = 7.2 %" is a lab result any system can interpret. FHIR's terminology layer is how those codes are represented, constrained and checked. Getting it right is the difference between data that's interoperable and data that only *looks* interoperable.
Coding and CodeableConcept
A Coding is one code from one code system:
{
"system": "http://loinc.org",
"code": "4548-4",
"display": "Hemoglobin A1c/Hemoglobin.total in Blood"
}
system— the URI that identifies the code system. Without it,4548-4is just a string.code— the code itself. Codes are case-sensitive.display— the code system's text for the code. It's informational; systems match onsystem+code.version— optional, used when the meaning of a code depends on the code system version.
A CodeableConcept is a concept expressed by zero or more Codings plus optional free text. Most coded elements use it, because one real-world concept often has codes in several systems:
"code": {
"coding": [
{ "system": "http://snomed.info/sct", "code": "44054006", "display": "Diabetes mellitus type 2" },
{ "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9", "display": "Type 2 diabetes mellitus without complications" }
],
"text": "Type 2 diabetes"
}
text is what the user actually saw or typed. Keep it. When no code fits, a CodeableConcept with only text is still valid and more honest than a wrong code.
System URIs you'll use constantly
| Code system | system URI | Used for |
|---|---|---|
| LOINC | http://loinc.org | Lab tests, vital signs, document types, survey questions |
| SNOMED CT | http://snomed.info/sct | Conditions, procedures, findings, body sites |
| ICD-10-CM (US) | http://hl7.org/fhir/sid/icd-10-cm | Billing and reporting diagnoses |
| ICD-10 (WHO) | http://hl7.org/fhir/sid/icd-10 | International diagnosis coding |
| RxNorm | http://www.nlm.nih.gov/research/umls/rxnorm | Medications (US) |
| UCUM | http://unitsofmeasure.org | Units in Quantity (mg/dL, mm[Hg], /min) |
| CPT | http://www.ama-assn.org/go/cpt | US procedures and services (AMA-licensed) |
| CVX | http://hl7.org/fhir/sid/cvx | Vaccines (US) |
The most common mistake is using a web page URL instead of the official system URI — https://loinc.org/4548-4/, or http://www.snomed.org. The spec's terminology registry ("Using Codes in Resources") and terminology.hl7.org list the official URIs.
ICD-10 vs ICD-10-CM: they're different code systems. US claims and EHR problem lists use ICD-10-CM, which adds many codes WHO ICD-10 doesn't have. Labelling an ICD-10-CM code with the WHO system URI is a subtle but real error.
The terminology resources
CodeSystem
Defines a set of codes and their meaning. Large external systems like LOINC and SNOMED CT are usually *not* loaded as full CodeSystem resources. A server just knows about them. Small, FHIR-defined systems (http://hl7.org/fhir/administrative-gender) and your own local codes are published as CodeSystems.
ValueSet
Selects codes, often from several code systems, for a specific purpose. It has two parts:
compose— the rules: include these codes, all descendants of this SNOMED concept, everything matching this filter, exclude these.expansion— the computed list of codes the rules produce at a point in time.
{
"resourceType": "ValueSet",
"url": "http://example.org/fhir/ValueSet/diabetes-conditions",
"status": "active",
"compose": {
"include": [
{
"system": "http://snomed.info/sct",
"filter": [{ "property": "concept", "op": "is-a", "value": "73211009" }]
}
]
}
}
This includes SNOMED concept 73211009 (Diabetes mellitus) and all its descendants, such as type 1 and type 2 diabetes, without listing them one by one.
ConceptMap
Maps codes from one system or value set to another, for example local lab codes to LOINC, or SNOMED CT to ICD-10-CM. Each mapping has a relationship (equivalent, wider, narrower and others). Very few mappings are exactly equivalent, so read the relationship before you treat a mapped code as the same thing.
Bindings: how resources constrain codes
Every coded element in a resource definition is bound to a value set with a strength:
| Strength | Meaning | Example |
|---|---|---|
| required | Must use a code from the value set | Observation.status, Patient.gender |
| extensible | Use a code from the value set if any fits; otherwise another code is allowed | US Core Condition.code |
| preferred | Encouraged, not enforced | — |
| example | Just an illustration | Observation.code in the base spec |
Required bindings on simple code elements are where most validation errors come from ("status": "Final" instead of final). Extensible bindings are where most *interoperability* problems come from: an implementer uses a local code when a standard one existed.
Terminology operations
A terminology server exposes standard operations. All of these are plain HTTP calls:
$lookup — what does this code mean?
GET [base]/CodeSystem/$lookup?system=http://loinc.org&code=8867-4
$validate-code — is this code valid, and is it in this value set?
GET [base]/ValueSet/$validate-code?url=http://hl7.org/fhir/ValueSet/administrative-gender&system=http://hl7.org/fhir/administrative-gender&code=female
{
"resourceType": "Parameters",
"parameter": [
{ "name": "result", "valueBoolean": true },
{ "name": "display", "valueString": "Female" }
]
}
$expand — list the codes in a value set, optionally filtered. This is what powers code pickers and autocomplete:
GET [base]/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/observation-category&filter=vital
$translate — map a code through a ConceptMap:
GET [base]/ConceptMap/$translate?url=http://example.org/fhir/ConceptMap/local-to-loinc&system=http://lab.example.org/codes&code=GLU
$subsumes — is code A a kind of code B? Useful for "does this patient have any kind of diabetes" questions:
GET [base]/CodeSystem/$subsumes?system=http://snomed.info/sct&codeA=44054006&codeB=73211009
Which terminology server?
- tx.fhir.org — HL7's public server, used by the official validator. Fine for development and testing, but not a production dependency.
- Ontoserver (CSIRO), Snowstorm (SNOMED International, SNOMED CT only), HAPI FHIR with terminology loaded — common self-hosted choices.
- NLM VSAC — US value sets for quality measures. Requires a free UMLS license.
Licensing
Code systems aren't all free to use:
- LOINC — free, with a license agreement and attribution.
- SNOMED CT — free in SNOMED International member countries (including the US through NLM); elsewhere it needs a license.
- CPT — owned by the AMA. Using CPT descriptions in a product generally requires a license, even when the codes themselves appear in data you receive.
- ICD-10-CM, RxNorm, UCUM — free to use (RxNorm through NLM, with UMLS terms for some content).
Common terminology mistakes
- Missing
systemon a Coding. - Web URLs or OIDs where a canonical system URI exists.
- WHO ICD-10 system with ICD-10-CM codes.
- Wrong case in codes from required value sets.
- Putting the code in
displayand free text incode. - Dropping
CodeableConcept.textduring mapping, losing what the clinician actually wrote. - Treating a ConceptMap
wider/narrowermapping as equivalent.
Try it
The Code Lookup tool has a small, curated offline list of frequently used LOINC, SNOMED CT and ICD-10 codes and FHIR value set codes. It can copy them as ready-to-paste Coding JSON. It's a quick reference, not a terminology server; for full searches it links to the official browsers. To check that the codes in a resource are well-formed, run it through the FHIR Validator.
Standards and references
- FHIR R4: Using codes in resources
- FHIR R4: Terminology service operations
- FHIR R4: ValueSet $validate-code
- HL7 Terminology (THO)
- tx.fhir.org terminology server
- LOINC
- SNOMED International
- UCUM
FHIR Toolbox is a free collection of HL7 FHIR tools by Omindra Labs. The tools process your data in your browser; it is not uploaded for normal tool operations.