What is a FHIR Terminology Service?

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

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:

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.
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.
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": [ {
"code":"AU",
"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"
}
1,
"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:

ValueSet.id
ValueSet.url
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",
"element":[
{
"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

Setup HAPI CLI:

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.

http://localhost:9999/fhir/CodeSystem/$lookup?system=http://snomed.info/sct&code=49495001

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.

http://localhost:9999/fhir/ValueSet/3/$validate-code?system=http://snomed.info/sct&code=49795001

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)?

/CodeSystem/$subsumes?system=http://snomed.info/sct&codeA=3738000&codeB=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:

http://localhost:9999/fhir/ValueSet/$expand?url=https://example.com/values/procedures$filter=lung

FAQs:

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.