Clinical terminology is the backbone of interoperable healthcare data. The FHIR Terminology module defines how coded values, the codes and systems used to describe clinical concepts, are represented, validated, and exchanged in FHIR resources. Smile CDR provides a comprehensive set of terminology services built on the HAPI FHIR JPA server's terminology engine.
Terminology can be loaded into Smile CDR in three ways: uploading CodeSystems, installing IG packages, or delegating to a Remote Terminology Service.
The FHIR specification defines three core resource types for managing terminology:
A CodeSystem defines a collection of codes and their meanings. Examples include LOINC, SNOMED CT, ICD-10, and organization-specific local code systems.
A ValueSet selects a subset of codes from one or more CodeSystems for a specific purpose. ValueSets are used extensively in FHIR profiles to constrain which codes are valid for a given element.
A ConceptMap defines mappings between concepts in different CodeSystems. For example, mapping a proprietary local code to its LOINC equivalent.
For a detailed explanation of how codes are used in FHIR resources, see Using Codes in Resources in the FHIR specification.
Smile CDR bundles all FHIR-specification CodeSystems, ValueSets, and ConceptMaps out of the box, and these can be seeded into the repository at startup. For standard vocabularies such as LOINC, SNOMED CT, and ICD-10, as well as for custom organization-specific code systems, Smile CDR provides upload operations and a command-line tool (smileutil) that handle large files without loading them fully into memory. See Uploading CodeSystems for details.
ValueSets are defined by composition rules, which Smile CDR pre-calculates into a flat expansion and stores in dedicated database tables. This enables fast $expand and $validate-code responses, membership testing during resource validation, and paginated expansion of very large ValueSets. See ValueSet Expansion for details.
Smile CDR supports mapping codes between different CodeSystems via ConceptMap resources and the $translate operation. This is commonly used to translate between standard vocabularies (e.g. local codes to LOINC) or between institution-specific and standardized code sets. See Terminology Mapping for details.
Smile CDR can apply ConceptMap $translate mappings automatically as resources are stored, adding translated codings directly to the resource before it is persisted. This mapping-on-the-way-in approach ensures that downstream consumers always see standardized codes. Currently this is limited to a single fixed mapping: Observation.code translated to LOINC. See In-Place Code Translation for details.
As an alternative to in-place translation, Smile CDR can apply terminology mappings to FHIR responses as they are served, without modifying the stored data. This mapping-on-the-way-out approach centralizes mapping management: when mappings change, there is a single source of truth to update. See FHIR Response Terminology Enhancement for details.
When full-text indexing is enabled, $expand gains additional filter support including display-name filtering, hierarchy filters (parent, child, ancestor, descendant), regex filtering, and LOINC-specific filters. This is especially useful for large hierarchical terminologies e.g. LOINC, SNOMED, RxNorm. See Terminology and Full-Text Indexing for details.
Smile CDR supports the following FHIR terminology operations:
| Operation | Resource | Description |
|---|---|---|
$lookup | CodeSystem | Look up a code and return its display name, properties, and designations |
$validate-code | CodeSystem, ValueSet | Validate whether a code is valid in a CodeSystem or is a member of a ValueSet |
$expand | ValueSet | Expand a ValueSet into its full flat list of codes; supports pagination and display filters |
$translate | ConceptMap | Translate a code from one CodeSystem to another using a ConceptMap |
$subsumes | CodeSystem | Test whether one concept subsumes another (hierarchy / is-a testing) |
In addition to the standard FHIR operations, Smile CDR exposes the following HAPI FHIR-specific operations:
| Operation | Resource | Description |
|---|---|---|
$invalidate-expansion | ValueSet | Invalidate the pre-calculated expansion for a ValueSet and trigger a fresh background recalculation. See ValueSet Expansion. |
$hapi.fhir.expansion-status | ValueSet | List ValueSets filtered by their pre-expansion status (e.g. EXPANDED, FAILED_TO_EXPAND) without requiring database access. See Checking Expansion Status. |
$reindex-terminology | System | Recreate the free-text indexes for terminology resources. See the smileutil reindex-terminology command for an automated alternative. |
$hapi.fhir.add-mapping | ConceptMap | Add a single concept mapping to an existing ConceptMap resource. See Terminology Mapping. |
$hapi.fhir.remove-mapping | ConceptMap | Remove a single concept mapping from an existing ConceptMap resource. See Terminology Mapping. |
Uploading a large external CodeSystem is not a single operation but a sequence of four CodeSystem-level operations invoked in order. Each step feeds the job created in step 1, and the final step polls the resulting background batch job to completion. See Upload Terminology Operations for full details.
$hapi.fhir.upload-terminology.create-job creates an upload job and returns a job ID.$hapi.fhir.upload-terminology.attach-file attaches a terminology distribution file to the job.$hapi.fhir.upload-terminology.start-job starts processing the attached files as a background batch job.$hapi.fhir.upload-terminology.poll-for-status polls the status of the running job until it completes.Smile CDR does not currently support the following terminology operations:
You are about to leave the Smile Digital Health documentation and navigate to the Open Source HAPI-FHIR Documentation.