Using a Terminology-server

Overview

The recommended approach for implementing the IPS Terminology within a software application is to use a terminology server. In a service-oriented architecture, software like Electronic Health Records and Data Analytics tools can delegate all terminology operations to a terminology server. The IPS Terminology can be loaded into Snowstorm, the open-source terminology server developed by SNOMED International.

• Download the IPS Terminology

• Download the Terminology Server

• Load the IPS Terminology into Snowstorm

• Access the IPS Terminology via the FHIR API

• Use the IPS Terminology in a software application

• Store IPS Terminology codes in FHIR resources

• Update the IPS Terminology to a New Version

• Request New Content for the IPS Terminology

Download the IPS Terminology

Before you can start using the IPS Terminology, you must first download the IPS Terminology package from the IPS Terminology website. The IPS Terminology package uses the same format as the RF2 (Release format 2) release file specification. However, the IPS Terminology package is a subset of the complete SNOMED CT international release, containing only active components in the SNAPSHOT release format. It does not include historical content, complete metadata values, or stated Description Logic axiom definitions. All these features are available in any complete SNOMED CT Edition.

The IPS Terminology's RF2 zip package will be used in the terminology server import process described below, using Snowstorm as an example. Please refer to your terminology server documentation for further instructions.

Download Snowstorm

Snowstorm is an open-source terminology server developed and maintained by SNOMED International. To download the most recent release of Snowstorm, please visit Snowstorm's GitHub repository releases page, and follow the installation instructions.

Load the IPS Terminology into Snowstorm

The IPS Terminology package is designed to be loaded into an empty terminology server instance. Follow the standard steps described in the Snowstorm configuration guide to import the IPS Terminology package into the MAIN branch as the only terminology in the Snowstorm instance.

After the import process is complete, the IPS Terminology content will be available for access through the terminology server's APIs.

Access the IPS Terminology via the FHIR API

Snowstorm offers a standard FHIR API that implements the HL7 FHIR Terminology Module specification. This provides access to the terminology using FHIR Operations and returning content structured as FHIR Resources, the full specification of the SNOMED CT representation in FHIR is available in the FHIR documentation.

Base URL

The terminology server API will be exposed through the server that the Snowstorm instance is running. For example, if the server is using port 8080 on your local machine - i.e.

http://localhost:8080

Then the base URL for the FHIR API would be:

http://localhost:8080/fhir

FHIR Operations

The FHIR terminology services API can support a range of common implementation use cases, including powering searches in a user interface, filtering content for specific clinical fields (by applying an ECL constraint to the terms entered by the user), and restricting results to a particular clinical domain (e.g., diseases, procedures, substances). In the following sections, we explain some common FHIR terminology operations that can be used for these implementation purposes.

CodeSystem.$lookup

The FHIR CodeSystem lookup operation returns information about a concept (e.g. definition status and descriptions) based on the given SNOMED CT concept identifier (code). For example:

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

The parameters include the "system" (i.e. "sct") and the "code" to look for (e.g. "900000000000508004"). One of the use cases for the lookup operation is to retrieve terms and properties for a concept id received from another system.

CodeSystem.$validate-code

The validate-code operation is used to validate if a code is included in the given code system. For example:

http://localhost:8080/fhir/CodeSystem/$validate-code?system=http://snomed.info/sct&code=155574008

The parameters include the "system" (i.e. "sct") and the "code" to validate (e.g. "155574008"). One example of a use case for validation is to check if a given conceptId is a valid SNOMED CT concept.

ValueSet.$expand

The expand operation retrieves a list of concepts that are part of a value set, with the option of filtering by a text string. For example:

http://localhost:8080/fhir/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/%3C%2071388002&count=20&includeDesignations=true&filter=append

In this example, the URL parameters include an implicit value set (i.e. "fhir_vs=ecl/") defined using an ECL Expression, with a text filter using the "filter" parameter (i.e. "filter=append"). The example above will find the procedures ("< 71388002"), which match the search string "append".

Examples

The following example URLs use the public Snowstorm API provided by SNOMED International. Please click on these links to see an example of each response.

• Lookup: https://snowstorm.snomedtools.org/fhir/CodeSystem/$lookup?system=http://snomed.info/sct&code=900000000000508004

• Validate: https://snowstorm.snomedtools.org/fhir/CodeSystem/$validate-code?system=http://snomed.info/sct&code=155574008

• Expand: https://snowstorm.snomedtools.org/fhir/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/%3C%2071388002&count=20&includeDesignations=true&filter=append

Use the IPS Terminology in a software application

Using the HL7 FHIR terminology services API, as described in the previous section, a clinical application can enable the user to search for clinical elements in the IPS Terminology. The search can be constrained to a specific domain (e.g. Conditions or Procedures) using the ECL query language. For example, as shown below, a Procedure data entry field can be bound to the procedure codes in the IPS terminology using the ECL query "< 71388002 |Procedure|" in a ValueSet.$expand operation. Note: The ECL query is shown in its terse, percent-encoded form within the URL below (i.e. "%3C%2071388002")

http://localhost:8080/fhir/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/%3C%2071388002&count=20&includeDesignations=true&filter=append

This API call (which includes the term filter "append") can be used to create a user interface similar to this one:

The terminology code system and code system version used to refer to the IPS Terminology are shown below:

• Code system

  • coding.system = "http://snomed.info/sct"

• Code system version

  • coding.version = "http://snomed.info/sub/999991001000101"

  • coding.version = "http://snomed.info/sub/999991001000101/version/"

    • e.g., "http://snomed.info/sub/999991001000101/version/20220430"

If a terminology server is not available, it is possible to create a plain list from the RF2 files, but the most advanced features described in this guide (e.g., concept hierarchies and ECL queries) are not supported by the HL7 IPS Free Set. Users without access to a terminology server can also browse the IPS Terminology and execute ECL queries (for design-time use) in the IPS Terminology browser provided by SNOMED International.

Store IPS Terminology codes in FHIR resources

The FHIR IPS Implementation Guide describes the FHIR resources that are collected into an IPS bundle. Some data elements in these resources use the datatype "CodeableConcept" and are bound to a SNOMED CT value set. These data elements can be populated with codes from the IPS Terminology via a Terminology Server. For example, a response for a ValueSet.$expand operation, which selects all procedures, may look like this:

The "expansion.contains" property lists all the matches, and each one includes the necessary values for populating a CodableConcept data element. For example, this might be used to populate the "code" data element in a [FHIR Procedure resource](https://www.hl7.org/fhir/procedure.html).

The [CodableConcept](https://www.hl7.org/fhir/datatypes.html#CodeableConcept) data type uses a [Coding](https://www.hl7.org/fhir/datatypes.html#Coding) property to represent the details of the concept. Using SNOMED CT, the properties "System", "Code" and "Display" of a [Coding](https://www.hl7.org/fhir/datatypes.html#Coding) should always be completed. For example, this is a fragment of a [FHIR Procedure resource instance](https://www.hl7.org/fhir/procedure-example-colonoscopy.json.html):

The "version" property of the Coding data type is optional and can be completed if this value is obtained from the terminology server.

Update the IPS Terminology to a New Version

As SNOMED CT evolves, some concepts might be inactivated, and some new concepts may appear. A full SNOMED CT edition will include the complete history tracking of these changes, including inactive content and historical associations with proposed replacements. However, any future versions of the IPS Terminology will include only the content that is active at the time of release. Therefore, to update the IPS Terminology in the terminology server, it is necessary to remove all indices and reimport the new IPS content.

To do this using the command-line tool of Snowstorm, the import parameters should include "–delete-indices":

java -Xms2g -Xmx4g -jar target/snowstorm*.jar --delete-indices --import=<Absolute-path-of-SNOMED-CT-RF2-zip>

If the Snowstorm instance is updated to a complete SNOMED CT edition, the first import should delete indexes in the same way. However, the second and subsequent imports of a complete SNOMED CT edition can be performed as usual. These will result in incremental updates since the previous edition.

Request New Content for the IPS Terminology

The content of the IPS Terminology is defined by the terminology bindings created by the HL7 FHIR IPS group. All inquiries about the content of the IPS Terminology should be directed to [e-mail] or [e-mail].

Provide Feedback