CodeSystem

FHIR CodeSystem resource definition, content types, and examples of external references, complete definitions, supplements, and hierarchical systems

A CodeSystem resource defines a set of codes and their meanings within a specific terminology domain. Think of it as a dictionary that establishes what codes exist and what they mean, providing the foundation for consistent data interpretation across healthcare systems.

CodeSystems serve multiple purposes: they declare the existence of terminology systems, describe their key properties, and optionally define the actual concepts and codes within the system. This flexibility allows FHIR to work with both massive external terminologies like SNOMED CT and simple custom code sets defined for specific implementations.

See also: FHIR CodeSystem Specification

Examples

External CodeSystem Reference - Large established terminologies are typically referenced without including their full content, as they're maintained externally. These CodeSystem resources usually have content: not-present.

{
  "resourceType": "CodeSystem",
  "url": "http://loinc.org", 
  "version": "3.1.0",
  "name": "LOINC",
  "title": "Logical Observation Identifiers, Names and Codes (LOINC)",
  "status": "active",
  "date": "2022-11-22",
  "publisher": "LOINC and Health Data Standards, Regenstrief Institute, Inc.",
  "content": "not-present"
}

Complete CodeSystem Definition - Smaller, well-defined code sets can include their full content within the FHIR resource.

{
  "resourceType": "CodeSystem",
  "url": "http://hl7.org/fhir/administrative-gender",
  "version": "6.0.0-ballot2", 
  "content": "complete",
  "concept": [
    {
      "code": "male",
      "display": "Male"
    },
    {
      "code": "female", 
      "display": "Female"
    },
    {
      "code": "other",
      "display": "Other"
    },
    {
      "code": "unknown",
      "display": "Unknown"
    }
  ]
}

Supplement CodeSystem - Adds translations or additional properties to existing code systems without modifying the original.

{
  "resourceType": "CodeSystem",
  "url": "http://example.org/fhir/administrative-gender-es",
  "content": "supplement",
  "supplements": "http://hl7.org/fhir/administrative-gender",
  "concept": [
    {
      "code": "male",
      "designation": [
        {
          "language": "es",
          "value": "Masculino"
        }
      ]
    },
    {
      "code": "female",
      "designation": [
        {
          "language": "es", 
          "value": "Femenino"
        }
      ]
    }
  ]
}

Complex CodeSystem with Properties - Demonstrates advanced features like filters, properties, and hierarchical concepts.

{
  "resourceType": "CodeSystem",
  "url": "http://www.nlm.nih.gov/research/umls/rxnorm",
  "version": "04072025",
  "content": "complete",
  "filter": [
    {
      "code": "concept",
      "operator": ["is-a", "generalizes", "descendent-of"],
      "value": "comma-separated list of concept codes for direct equality testing"
    },
    {
      "code": "NDC", 
      "operator": ["=", "in", "exists"],
      "value": "NDC code"
    }
    ...
  ],
  "property": [
    {"code": "tty", "type": "string"},
    {"code": "NDC", "type": "string"},
    {"code": "RXN_STRENGTH", "type": "string"}
    ...
  ],
  "concept": [
    ...
    {
      "code": "5640",
      "display": "ibuprofen",
      "property": [
        {
          "code": "tty",
          "valueString": "IN"
        },
        {
          "code": "has_tradename", 
          "valueCode": "1100067"
        }
      ]
    }
    ...
  ]
}

Hierarchical CodeSystem - Shows how CodeSystems can represent complex taxonomies with parent-child relationships.

{
  "resourceType": "CodeSystem",
  "url": "http://hl7.org/fhir/sid/icd-10-cm",
  "version": "2025",
  "content": "complete", 
  "concept": [
    {
      "code": "Chapter-1",
      "display": "Certain infectious and parasitic diseases (A00-B99)",
      "concept": [
        {
          "code": "Section-A00-A09",
          "display": "Intestinal infectious diseases (A00-A09)",
          "concept": [
            {
              "code": "A00",
              "display": "Cholera",
              "concept": [
                {
                  "code": "A00.0",
                  "display": "Cholera due to Vibrio cholerae 01, biovar cholerae"
                }
              ]
            }
          ]
        }
      ]
    }
    ...
  ]
}

Note: The content field indicates how much of the CodeSystem is actually defined: not-present for external references, complete for full definitions, supplement for extensions to existing systems, and example or fragment for partial representations. This flexibility allows FHIR to work efficiently with both massive external terminologies and focused local code sets.

Operations

$lookup

Retrieves detailed information about a specific code within a CodeSystem, including its display name, definition, and additional properties.

Request

GET /fhir/CodeSystem/$lookup?system=http://loinc.org&code=1751-7

Response

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "name",
      "valueString": "LOINC"
    },
    {
      "name": "display",
      "valueString": "Albumin [Mass/volume] in Serum or Plasma"
    },
    {
      "name": "definition",
      "valueString": "Albumin measurement in serum or plasma by mass per volume"
    },
    {
      "name": "property",
      "part": [
        {
          "name": "code",
          "valueCode": "COMPONENT"
        },
        {
          "name": "value",
          "valueString": "Albumin"
        }
      ]
    }
  ]
}

$validate-code

Validates whether a given code exists in the CodeSystem and optionally checks if the provided display name is correct.

Valid Code Request

GET /fhir/CodeSystem/$validate-code?url=http://hl7.org/fhir/administrative-gender&code=male&display=Male

Valid Code Response

{
  "resourceType": "Parameters", 
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "display",
      "valueString": "Male"
    }
  ]
}

Invalid Code Request

GET /fhir/CodeSystem/$validate-code?url=http://hl7.org/fhir/administrative-gender&code=invalid

Invalid Code Response

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result", 
      "valueBoolean": false
    },
    {
      "name": "message",
      "valueString": "Code 'invalid' is not found in code system 'http://hl7.org/fhir/administrative-gender'"
    }
  ]
}