FHIR Bootcamp - Registrations now open for the July batch!

Register Now

What is a FHIR Terminology Service?

Kritika Goyal

Kritika Goyal

Business Development

Terminologies on Fhir

A FHIR terminology service is just a set of functions based on the definitions supplied by a collection of CodeSystem, ValueSet, and ConceptMap resources, with assistance from other generally known terminologies. The terminology service expands on the fundamental concepts for utilizing terminologies in FHIR.

Check out our video to know more

Terminologies in FHIR

What are the different FHIR terminology resources available?

1. Code System

Code System states and explains the existence of a code system or code system supplement, as well as its important attributes, and optionally defines a portion or all of its content. Ontology, Terminology, and Enumeration are other terms that describe the same thing. For e.g.: SNOMED CT and LOINC to name a few.

Code System has three identifiers:

  1. CodeSystem.id: This is the id that contains the CodeSystem resource instance in the system. It is expected to change as the resource moves from server to server.
  2. CodeSystem.url: This is the canonical URL for the code system that remains same for every copy. The element is designated as URL rather than URI because of legacy reasons and for promoting the use of resolvable URL wherever possible. This canonical URL refer to all instances of this particular CodeSystem on all the servers and platforms.
  3. CodeSystem.identifier: A system/value pair that is used to identify the code system in other contexts.
"resourceType": "CodeSystem", "id": "au-jurisdictions", "url": "http://csiro.au/cs/au-jurisdictions", "identifier": [ {
"system": "urn:ietf: rfc: 3986", "value": "http://csiro.au/cs/au-jurisdictions"
"version": "0.0.2", "name": "Australian jurisdictions", "status": "draft", "experimental": true, "caseSensitive": false, "valueSet": "http://csiro.au/vs/au-jurisdictions", "hierarchyMeaning": "is-a", "versionNeeded": false, "content": "complete",
"property": [
"code": "capital",
"uri": "http://csiro.au/cs/jurisdiction-capital", "description": "Capital city of the jurisdiction", "type": "string"
"code": "neighbour",
"uri": "http://csiro.au/cs/jurisdiction-neighbour", "description": "Neighbouring jurisdiction", "type": "code"
"concept": [ {
"display": "Australia", "definition": "Australian jurisdiction", "concept": [ {
"code": "AU-state", "display": "Australian state", "definition": "Australian state jurisdiction", "concept": [ {
"code": "WA",
"display": "Western Australia", "definition": "Western Australia jurisdiction", "designation": [ {
"use": {
"system": "http://snomed.info/sct", "code": "900000000000013009"
}, "value": "West Australia"
"property": [
"code": "capital", "valueString": "Perth"
"code": "neighbour", "valueCode": "NT"
}, {
"code": "neighbour", "valueCode": "SA"

2. Value Sets

A ValueSet resource instance describes a collection of codes from one or more code systems that are designed for usage in a certain context. Value sets serve as a bridge between CodeSystem definitions and their use in coded components.

Value Sets also have three identifiers similar to CodeSystem:

  1. ValueSet.id
  2. ValueSet.url
  3. ValueSet.identifier
    "resourceType": "ValueSet",
    "url": "https://medblocks.in/values/appendix",
    "name": "appendix",
    "compose": {
        "include": [
                "system": "http://snomed.info/sct",
                "concept": [
                        "code": "80146002",
                        "display": "Appendicectomy"
                        "code": "38102005",
                        "display": "Cholecystectomy"
                        "code": "765472003",
                        "display": "Left nephrectomy"
                "system": "http://snomed.info/sct",
                "filter": [
                        "property": "concept",
                        "op": "is-a",
                        "value": "49795001"

There are two types of ValueSet intensional and extensional based on mathematical logic and set theory respectively.

3. Intensional ValueSet

An intensional value set is often defined algorithmically. In other words, the code group is specified as a rule, such as all codes including the word hypertension in their description. The benefit of these groups is that they can be dynamically updated meaning whenever a new drug or any codes for diseases hit the market then the codes in the beta blockers get updated as a new beta blocker code automatically.

4. Extensional ValueSet

These sets are ordered lists of codes in which each code is listed separately. These codes give the author and user more flexibility as they have more control over the ValueSet but it increases the burden of keeping them up to date.

5. ConceptMap

A concept map defines a mapping between a collection of ideas specified in one code system (the "system") to one or more concepts defined in other code systems. Mappings are done in one way i.e. from the source system to the target system. The reverse mappings are valid in many circumstances, but this cannot be assumed.

It is worth noting that all code systems (explicit or implicit) provided in FHIR include URI IDs for value sets that encompass the complete code system and these "all codes" value sets can be used for mappings that are acceptable in all use contexts that are appropriate for the code system.

"sourceUri": "http://csiro.au/vs/australian-mainland-states", "targetUri": "http://snomed.info/sct?fhir_vs",
"group" : [
"source": "http://csiro.au/cs/au-jurisdictions", "target": "http://snomed.info/sct",
"code": "QLD", "target" : [
"code": "223778006", "equivalence": "equivalent"
"code": "WA", "target" : [
"code": "223782008", "equivalence": "equivalent"

6. Naming System

It is a process of providing specific names to specific code systems so that they can be recorded in a registry and can be used by other systems while locating and comprehending an identifier.

7. Terminologies Capabilities

It is a resource document that contains a set of capabilities of the FHIR Terminology Server. This document can be used to describe current server functionality or to describe necessary or intended server implementation.

How to set up SNOMED CT on HAPI FHIR?

You can easily set up SNOMED CT on a HAPI FHIR JPA server running locally. The examples below use a HAPI FHIR server running on port 9999.

Clone this repository:

git clone https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git

Run HAPI FHIR JPA by compiling from source using:

mvn -Djetty.port=9999 jetty:run


If you're on macOS:

brew install hapi-fhir-cli

For other operating systems, refer to the official documentation.

Upload SNOMED CT on your FHIR server

Download your SNOMED CT RF2 file. Use the following command:

hapi-fhir-cli upload-terminology -d ./SnomedCT_InternationalRF2_PRODUCTION_20210131T120000Z.zip -t http://localhost:9999/fhir -u http://snomed.info/sct -v r4
💡 Note: The CLI and HAPI FHIR should be on the same machine for this to work. If you're using docker, you'll need to have the CLI installed along with the HAPI FHIR JAR and have access to the same /tmp directory.

How to use FHIR terminology service REST APIs?

1. Types of operations on CodeSystem:

1. Operation $lookup on CodeSystem: It is used to obtain information about a code (such as code/system/version or Coding) and is also capable of retrieving specific/all properties/designations. It may be used to see if a code exists in the CodeSystem.

For example, the following URL can be used for looking up a code/system.


2. Operation $validate-code on CodeSystem: It is used to validate a coded value in the CodeSystem. The operation produces a result (true or false), an error message, and the code's suggested display.

For example, the following URL can be used to request a simple code validation against a defined code system.


3. Operation $subsumes on CodeSystem: It is used to determine whether or whether there is a subsumption connection between two codes, such as codeA and codeB, as code/system/version or codingA and codingB. The outcome will be shown as "equivalent", "subsumes", "subsumed by", or "not subsumed." It is determined by the 'hierarchyMeaning' of the coding system.

For example, the following URL can be used to request - Using simple parameters: is 'Viral hepatitis' (3738000) a 'Disorder of liver' (235856003)?


4. Operation $find-matches on CodeSystem: This method takes a set of properties and searches the code system for codes that match a set of known properties.

When looking for matches, there are three categories of matches to consider:
A complete match - a code that accurately reflects all of the specified characteristics.

A partial match - a code that accurately reflects some of the specified characteristics but not others.

A possible match - a code that may nearly approximate the specified attributes while capturing less or more detailed information for some of the properties.


2. Types of operations on ValueSets:

Operation $expand on ValueSet: It is used to obtain the ValueSet's expansion given a set of parameters. As a consequence, a ValueSet with a 'expansion' element is created.
The parameters include: filter, count, offset, includeDesignations, includeDefinition, activeOnly, excludeNested, excludeNotForUI, excludePostCoordinated, display Language, limited
Expansion, profile. This is the best way to search for codes.

$expand with filter: It is used for searching the ValueSet using the filter.
For example:




1. What is the terminology module of FHIR?

The terminology module of FHIR is a foundational component designed to standardize and manage healthcare-related terminologies and vocabularies within the FHIR framework. It includes resources like CodeSystem, ValueSet, and ConceptMap that enable the representation, linking, and use of various standardized codes and classifications, ensuring consistent interpretation of data across systems.


2. What is a FHIR terminology service?

FHIR REST APIs can be used to interact with multiple Terminologies like SNOMED, LOINC, ICD10 and more. The advantage of using FHIR to interface with these terminologies is that it provides a unified API and data schema for clients to interact with various terminologies without deep knowledge of the inner workings of each ontology.


3. Why is terminology required?

Terminology is essential in healthcare as it provides a consistent, standardized language for recording, sharing, and analyzing health data. Without standardized terminology, communication between healthcare providers, data interoperability, and patient care quality could be compromised due to misunderstandings and inconsistencies in data interpretation.


4. How does terminology affect my work in FHIR?

In FHIR, standardized terminology ensures that data exchanged between systems is interpretable and actionable. It impacts various aspects of healthcare IT, including clinical decision support, data analysis, and patient record management, by enhancing data accuracy and interoperability.


5. How to use FHIR terminology service REST APIs?

  • To use FHIR terminology service REST APIs, developers must interact with endpoints provided by a FHIR server that supports terminology services. These APIs allow operations such as searching within a ValueSet, validating a code, or translating codes between different systems. Familiarity with FHIR resource structures and HTTP methods is essential for effective implementation.
  • Identify the base URL of the FHIR terminology service you intend to use.
  • Use the appropriate HTTP methods (GET, POST, PUT) to interact with the service, specifying the required resource type (e.g., ConceptMap, ValueSet) and call the appropriate operation (like $lookup, $validate-code, $expand) on the resource. Include necessary headers and parameters in your API calls to define the scope, filters, and operations you want to perform.
  • Process the responses from the API to extract and utilize the terminology data in your application or service.


6. When to use FHIR terminology service APIs?

FHIR terminology service APIs should be used whenever there is a need to incorporate, validate, or translate standardized medical codes and vocabularies within healthcare applications. This is crucial for tasks like validating diagnostic codes, interoperating between different healthcare systems, or enhancing clinical decision support systems.  These APIs are particularly useful in scenarios involving electronic health records exchanges where uniformity and accuracy of clinical data are critical.


7. What is the FHIR terminology service for VSAC resources?

The FHIR terminology service for VSAC (Value Set Authority Center) resources allows users to access and manage value sets that are used in clinical quality measures and decision support in the US and is hosted by the National Institutes of Health (NIH). It enables the retrieval, validation, and manipulation of these value sets via FHIR APIs, ensuring that applications use up-to-date and authoritative clinical data.


8. What is a FHIR terminology server?

A FHIR terminology server is a server that implements the FHIR standard to provide services related to healthcare terminologies. It supports operations such as validating codes, expanding value sets, translating between different code systems, and managing terminology resources.


9. What does a terminology server do?

A terminology server provides a centralized mechanism to manage, validate, and query terminology information. It processes requests to look up and validate codes, maps between different terminology systems, and supports the integration of these functions into healthcare applications.


10. Are there any Java based terminology server implementations?

Yes, there are Java-based implementations of FHIR terminology servers, such as HAPI FHIR. HAPI FHIR is an open-source framework that provides a comprehensive implementation of the FHIR specification, including services for managing and interacting with healthcare terminologies.


11. How to set up your FHIR terminology server?

To set up a FHIR terminology server, follow these steps - 

  • Choose a server framework that supports FHIR, such as HAPI FHIR for Java.

  • Install the necessary software and dependencies on your server.

  • Configure the server to handle FHIR resources and terminology services according to your requirements.

  • Load the necessary terminology data sets, such as SNOMED CT, ICD-10, or LOINC.

  • Ensure the server is properly secured, especially if it will handle sensitive health information.

  • Test the server thoroughly to ensure it responds correctly to FHIR terminology requests.


Become a FHIR Expert Today — Join Our Free Webinar

Unlock the secrets to mastering FHIR in our exclusive, free live webinar. Discover why now is the prime time to excel and how you can become an expert.