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-4 is 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 on system + 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 systemsystem URIUsed for
LOINChttp://loinc.orgLab tests, vital signs, document types, survey questions
SNOMED CThttp://snomed.info/sctConditions, procedures, findings, body sites
ICD-10-CM (US)http://hl7.org/fhir/sid/icd-10-cmBilling and reporting diagnoses
ICD-10 (WHO)http://hl7.org/fhir/sid/icd-10International diagnosis coding
RxNormhttp://www.nlm.nih.gov/research/umls/rxnormMedications (US)
UCUMhttp://unitsofmeasure.orgUnits in Quantity (mg/dL, mm[Hg], /min)
CPThttp://www.ama-assn.org/go/cptUS procedures and services (AMA-licensed)
CVXhttp://hl7.org/fhir/sid/cvxVaccines (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:

StrengthMeaningExample
requiredMust use a code from the value setObservation.status, Patient.gender
extensibleUse a code from the value set if any fits; otherwise another code is allowedUS Core Condition.code
preferredEncouraged, not enforced—
exampleJust an illustrationObservation.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

  1. Missing system on a Coding.
  2. Web URLs or OIDs where a canonical system URI exists.
  3. WHO ICD-10 system with ICD-10-CM codes.
  4. Wrong case in codes from required value sets.
  5. Putting the code in display and free text in code.
  6. Dropping CodeableConcept.text during mapping, losing what the clinician actually wrote.
  7. Treating a ConceptMap wider/narrower mapping 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 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.