CodeSystem — The FHIR code repository
Every coded FHIR value — a gender, a diagnosis, a medication — comes from a CodeSystem. SNOMED CT, LOINC, RxNorm, ATC, ICD-10, local codes: all are declared via this resource.
Purpose
CodeSystem declares a code system: its canonical URL (which acts as a universal identifier), its version, case sensitivity, optional concept hierarchy, the properties qualifying each code, and the explicit or implicit list of concepts.
Three modes of completeness (content):
not-present— only metadata is published, concepts live externally (typical for SNOMED).example— a non-exhaustive sample.fragment— an explicit subset (partial extensions).complete— every concept listed (FHIR core CodeSystems).supplement— supplement to an existing CodeSystem.
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
url | uri | 0..1 | Canonical URL (= system in Coding). |
version | string | 0..1 | CodeSystem version. |
name | string | 0..1 | Machine name. |
status | code | 1..1 | Publication status. |
caseSensitive | boolean | 0..1 | Code case sensitivity. |
content | code | 1..1 | Completeness (see above). |
count | integer | 0..1 | Total concept count. |
hierarchyMeaning | code | 0..1 | grouped-by, is-a, part-of, classified-with. |
valueSet | canonical | 0..1 | The ValueSet matching all codes of the CS. |
property | BackboneElement[] | 0..* | Concept property definitions. |
concept | BackboneElement[] | 0..* | Concepts in the CodeSystem. |
concept.code | code | 1..1 | Concept code. |
concept.display | string | 0..1 | Preferred label. |
concept.definition | string | 0..1 | Narrative definition. |
concept.designation | BackboneElement[] | 0..* | Synonyms and translations. |
concept.property | BackboneElement[] | 0..* | Property values. |
concept.concept | BackboneElement[] | 0..* | Child concepts (hierarchy). |
Common code systems
| System | Canonical URL | Usage |
|---|---|---|
| SNOMED CT | http://snomed.info/sct | Diagnoses, procedures, anatomy. |
| LOINC | http://loinc.org | Lab tests, document sections. |
| RxNorm | http://www.nlm.nih.gov/research/umls/rxnorm | US medications. |
| ATC | http://www.whocc.no/atc | WHO medication classification. |
| ICD-10 | http://hl7.org/fhir/sid/icd-10 | Diagnoses. |
| ICD-10-CM | http://hl7.org/fhir/sid/icd-10-cm | US diagnoses. |
| UCUM | http://unitsofmeasure.org | Units of measure. |
| HL7 v2 tables | http://terminology.hl7.org/CodeSystem/v2-XXXX | Reused HL7 v2 tables. |
| HL7 v3 ActCode | http://terminology.hl7.org/CodeSystem/v3-ActCode | v3 codes. |
JSON example
The canonical administrative-gender CodeSystem:
{
"resourceType": "CodeSystem",
"id": "administrative-gender",
"url": "http://hl7.org/fhir/administrative-gender",
"version": "5.0.0",
"name": "AdministrativeGender",
"title": "AdministrativeGender",
"status": "active",
"experimental": false,
"date": "2026-05-14",
"publisher": "HL7 International (FHIR Project)",
"description": "The gender of a person used for administrative purposes.",
"caseSensitive": true,
"valueSet": "http://hl7.org/fhir/ValueSet/administrative-gender",
"content": "complete",
"count": 4,
"concept": [
{ "code": "male", "display": "Male", "definition": "Male." },
{ "code": "female", "display": "Female", "definition": "Female." },
{ "code": "other", "display": "Other", "definition": "Other." },
{ "code": "unknown", "display": "Unknown", "definition": "Unknown." }
]
}Common pitfalls
- Confusing
url(system) andid— theurlis the identifier used inCoding.system. - Editing a CodeSystem without bumping
version— breaks the reproducible-expansion promise. - Hierarchy declared
is-abut inconsistent — a child concept must logically inherit from the parent. - Codes case-insensitive in practice but
caseSensitive=true— violates the declaration and breaks server-side comparisons. - SNOMED CT distributed in
concept[]— SNOMED is huge and licensed: usecontent=not-presentwith an external terminology server.
Related resources
- ValueSet — selects a subset of the CodeSystem.
- ConceptMap — inter-system mapping.
- NamingSystem — alternate identifiers (OID, URI).
- TerminologyCapabilities — server terminology capabilities.