Terminologies on FHIR

Kritika Goyal

Kritika Goyal

Business Development

Terminologies on FHIR

Terminology serves as the foundation for common meaning among diverse systems. If definitions are the roots/branches, the language is the leaves/fruit. Having terminologies as a single point of reference in a big integrated system makes them extremely useful for interoperability. The main objective behind having healthcare standards is to make the system interoperable, so that data can be shared making healthcare affordable and increasing the effectiveness of medical care across countries. Terminology (particularly ValueSets) is a critical component of profile definition.

Check out our video to know more:

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.

The Terminologies include various resources. The resources are:

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"

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.

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.

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.


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"

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.

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.



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.

REST Operations

A) Operation on CodeSystem: There are four types of operations that we can perform on CodeSystem. These are done to explore a set of concepts and
how they relate to one another.

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.

1. Request: Looking up a code/system
2. URL:


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.

1. Request: Simple code validation against a defined code system.
2. URL:


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.

1. Request: Using simple parameters: is 'Viral hepatitis' (3738000) a 'Disorder of liver' (235856003)?
2. URL:


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.

Types of operations on ValueSets:

1. 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.


So these are the REST operations performed on terminologies.

Why do we require terminologies in FHIR?

The use of terminology in FHIR has several advantages.

  1. We can rapidly locate the appropriate code to record in a certain scenario during data entry.
  2. The biggest benefit is that it aids with validation. We may check to see if the code we provided is appropriate for the circumstance or not.
  3. By presenting all of a code's attributes, it aids in comprehending the many facets of a code or collection of codes from a CodeSystem.
  4. It assists in code mapping from one set of codes to another.
  5. By categorizing coded data into groups that are considerably simpler to interpret and analyze, it aids in analytics.
  6. It grants you the power to create your own CodeSystem, ValueSet, and ConceptMap.