1 of 75

9.x

Introduction

Snow Owl® is a highly scalable terminology server with revision-control capabilities and collaborative authoring platform features. It allows you to store, search, and author high volumes of terminology artifacts quickly and efficiently.

If you’d like to see Snow Owl in action, the 🌎 provides a managed terminology server and high-quality terminology content management from your web browser.

Quick Start

This guide shows you how to quickly set up a Snow Owl deployment using docker to store, search, and edit any healthcare terminology data. Start here if you are interested in evaluating its core features.

TL;DR

Here is how to deploy Snow Owl in less than a minute:

Create your first Resource

Snow Owl is now running but does not contain any content whatsoever. To be able to import or author terminology data a resource has to be created beforehand. There are three major resource types in the system:

Code Systems (e.g. SNOMED CT, ATC, LOINC, ICD-10)
Value Sets
Concept Maps

For the sake of this quick start guide, we will follow along the path of how to create a SNOMED CT code system, import content and query concepts based on different criteria.

Create a Code System

If we take a look at eg. the list of known code systems, we get an empty result set:

To import SNOMED CT content, we have to create a code system first using the following request:

Use of SNOMED CT is subject to additional conditions not listed here, and the full copyright notice has been shortened for brevity in the request above. Please see for details.

The request body includes:

The code system identifier (SNOMEDCT)
Various pieces of metadata offering a human-readable title, status, contact information, URL and OID for identification, etc.
The tooling identifier snomed

If the request succeeds the server returns a 201 Created response with a Location header value pointing to the created terminology resource's location.

We can verify that the code system has been registered correctly when following that Location header value (ℹ️ NOTE: pretty is added to the request to format the response):

The expected response is:

In addition to the submitted values, you will find that additional administrative properties also appear in the output. One example is branchPath which specifies the working branch of the code system within the repository.

The code system now exists but is empty. To verify this claim, we can list concepts using either Snow Owl's native API tailored for SNOMED CT or the standardized FHIR API for a representation that is uniform across different kinds of code systems – for the sake of simplicity, we will use the former on the next page.

Import SNOMED CT from RF2

Before importing an RF2 file you can check existing content by for example looking up the available SNOMED CT Concepts in the created SNOMED CT resource:

As the response also indicates, the terminology is empty:

Let's import an archive using its SNAPSHOT content (see release types ) so that we can further explore the available SNOMED CT APIs. To start the import process, send the following request:

Curl will display the entire interaction between it and the server, including many request and response headers. We are interested in these two (response) rows in particular:

The first one indicates that the file was uploaded successfully and a job has been created to track the progress of the import, while the second row indicates the location of this import job.

Find concepts by ID or term

Search by identifier

Now that SNOMED CT content is present in the code system (identified by the unique id SNOMEDCT) it is time to take a deeper dive. A frequent interaction is to retrieve properties of a concept identified by its SNOMED CT Identifier. To do so, execute the following command:

curl -u "test:test" 'http://localhost:8080/snowowl/snomedct/SNOMEDCT/concepts/138875005?expand=pt()&pretty'

The response should look something like this:

We used the expand query parameter to include the concept's Preferred Term (PT) in the response. The concept in question is the root concept of the SNOMED CT hierarchy.

Search by term

Snow Owl also allows users to retrieve concepts matching a specific search term or phrase. See what happens if we try to find the concepts associated with the condition "Méniere's disease":

This time more than one concept can be present in the response, so we receive a collection of items. Results are sorted by relevance, indicated by the field score:

The total number of matching concepts is shown in the property named total.

Find concepts using ECL

One of Snow Owl's powerful features is the ability to list concepts matching a user-specified query expression using SNOMED International's Expression Constraint Language (ECL) syntax. If you would like to know more about the language itself, visit on the official site.

In this example, we list the direct descendants of the root concept using the ECL expression <!138875005 (via the ecl query parameter), and also limit the result set to a single item using the limit query parameter:

As no query parameter in this request would make Snow Owl differentiate between "better" and "worse" results (eg. a search term to match), concepts in the response will be sorted by identifier.

The item returned is, indeed, one of the top-level concepts in SNOMED CT:

Next steps

Now that we have our instance up and running, the next step is to understand how to communicate with it. Fortunately, Snow Owl provides very comprehensive and powerful APIs to interact with your instance.

REST API

Among the few things that can be done with the API are as follows:

Perform CRUD (Create, Read, Update, and Delete) and search operations against your terminology resources
Execute advanced search operations such as paging, sorting, filtering, scripting, aggregations, and many others
Administer your instance data
Check your instance health, status, and statistics

Conclusion

Snow Owl is both a simple and complex product. We’ve so far learned the basics of what it is, how to look inside of it, and how to work with it using some of the available APIs. Hopefully, this tutorial has given you a better understanding of what Snow Owl is and more importantly, inspired you to further experiment with the rest of its great features!

Setup and Administration

This guide contains all the necessary details for installing the Snow Owl Terminology Server in a production environment. The following sections will guide you on how to:

Select the appropriate hardware and software environment to host the service
Download, install, and configure the entire technology stack necessary for operating the server

Plan your deployment

Technology stack

The technology stack behind the Terminology Server consists of the following components:

The Terminology Server application
Elasticsearch as the data layer

Software requirements

Operating System

The Terminology Server is recommended to be installed on x86_64 / amd64 Linux operating systems where Docker Engine is available. See the list of supported architectures by Docker.

Here is the list of distributions that we suggest in the order of recommendation:

Ubuntu LTS releases
Debian LTS releases
CentOS 7 (deprecated)

It is possible to install the server release package on other distributions but bear in mind that there might be limitations.

Software packages

Before starting the production deployment of the Terminology Server make sure that the following packages are installed and configured properly:

Docker Engine
ability to execute bash scripts

Firewall

In case a reverse proxy is used, the Terminology Server requires two ports to be opened either towards the intranet or the internet (depending on usage):

http: port 80
https: port 443

In case there is no reverse proxy installed, the following port must be opened to be able to access the server's REST API:

http: port 8080

Configuration

Release package

Terminology Server releases are shared with customers through custom download URLs. The downloaded artifact is a Linux (tar.gz) archive that contains:

an initial folder structure
the configuration files for all services
a docker-compose.yml file that brings together the entire technology stack to run and manage the service
the credentials required to pull our proprietary docker images

As a best practice, it is advised to extract the content of the archive under /opt. So the deployment folder will be /opt/snow-owl. The docker-compose setup will rely on this path, however, if required it can be changed by editing the ./snow-owl/docker/.env file later on (see DEPLOYMENT_FOLDER environment variable).

When decompressing the archive it is important to use the --same-owner and --preserve-permissions options so the docker containers can access the files and folders appropriately.

The next page will describe the content of the release package in more detail.

Preload dataset (optional)

In certain cases, a pre-built dataset is also shipped together with the Terminology Server. This is to ease the initial setup procedure and get going fast.

This method is only applicable to deployments where the Elasticsearch cluster is co-located with the Terminology Server.

To load data into a managed Elasticsearch cluster, there are several options:

use
use
use Snow Owl to rebuild the data to the remote cluster

These datasets are the compressed form of the Elasticsearch data folder which follows the same structure. Except for having a top folder called indexes . This is the same folder as in ./snow-owl/resources/indexes . So to be able to load the dataset one should just extract the contents of the dataset archive to this path.

Make sure to validate the file ownership of the indexes folder after decompression. Elasticsearch requires UID=1000 and GID=0 to be set for its data folder.

Configure Elastic Cloud (optional)

The release package contains everything that is required to use a co-located Elasticsearch instance by default. Only proceed with these steps if a remote Elasticsearch cluster is required.

To configure the Terminology Server to work with a managed Elasticsearch cluster two settings require attention.

System settings

Some settings may require attention before moving to production. While the steps below may not necessitate any action, there are cases where the host running both Snow Owl and Elasticsearch will require fine-tuning.

Configure your host for Elasticsearch requirements

Some system-level settings need to be checked before deploying your own Elasticsearch in production.

Following this link there is an extensive guide on what to verify, but usually, it comes down to these items:

Configure your host for Snow Owl requirements

Set permissions for folders and files appropriately

By default, Snow Owl runs inside the container as user snowowl using uid:gid 1000:1000.

If you are bind-mounting a local directory or file:
- ensure it is readable by the user mentioned above
- ensure that settings, data and log directories are writable as well

A good strategy is to grant group access to gid 1000 or 0 for the local directory.

Bind-mount Snow Owl's temporary working folder

In case the file system of the docker service on the host is different from what the Snow Owl deployment uses, it could be worthwhile to bind-mount Snow Owl's temporary working folder to a path that has excellent I/O performance. E.g.:

the root file system / is backed by a block storage that purposefully has lower I/O performance, this is the file system used by the docker service.
the deployment folder /opt/snow-owl is backed by a fast local SSD

The definition of the snowowl service in the docker compose file should be amended like this:

Spin up the service

Full list of steps to perform before spinning up the service:

Extract the Terminology Server release archive to a folder. E.g. /opt/snow-owl
(Optional) Obtain an SSL certificate
1. Make sure a DNS A record is routed to the host's public IP address
2. Go into the folder ./snow-owl/docker/cert
3. Execute the ./init-certificate.sh script:
(Optional) Configure access for managed Elasticsearch Cluster (elastic.co)
(Optional) Extract dataset to ./snow-owl/resources where folder structure should look like ./snow-owl/resources/indexes/nodes/0 at the end.
Verify file ownership to be UID=1000 and GID=0:
Check any credentials or settings that need to be changed in ./snow-owl/docker/.env
Authenticate with our private docker registry while in the folder ./snow-owl/docker:
Issue a pull (in folder ./snow-owl/docker)
Spin up the service (in the folder ./snow-owl/docker)
Verify that the REST API of the Terminology Server is available at:
1. With SSL: https://snow-owl.example.com/snowowl
2. Without SSL: http://hostname:8080/snowowl
Verify that the server and cluster status is GREEN by querying the following REST API endpoint:
1. With SSL:
2. Without SSL:
Enjoy using the Snow Owl Terminology Server 🎉

Upgrade Snow Owl

When a new Snow Owl Terminology Server release is available we recommend performing the following steps.

New releases are going to be distributed the same way: a docker stack and its configuration within an archive.

It is advised to decompress the new release files to a temporary folder and compare the contents of ./snow-owl/docker .

The changes usually are restricted to version numbers in the .env file. In such cases, it is equally acceptable to overwrite the contents of the ./snow-owl/docker folder as is or cherry-pick the necessary modifications by hand.

Backup and restore

Advanced installation methods

This section includes information on how to set up Snow Owl and get it running using standalone installation methods

Java (JVM) Version

Snow Owl is built using Java and requires at least Java 17 to run. Only Oracle’s Java and the OpenJDK are supported.

We recommend installing the latest version in the Java 17 release series. We recommend using a supported LTS version of Java.

The version of Java that Snow Owl will use can be configured by setting the JAVA_HOME environment variable.

Install Snow Owl

Snow Owl is provided in the following package formats:

Disable swapping

Most operating systems try to use as much memory as possible for file system caches and eagerly swap out unused application memory. This can result in parts of the JVM heap or even its executable pages being swapped out to disk.

Swapping is very bad for performance, and should be avoided at all costs. It can cause garbage collections to last for minutes instead of milliseconds and can cause services to respond slowly or even time out.

There are two approaches to disabling swapping. The preferred option is to completely disable swap, but if this is not an option, you can minimize swappiness.

Disable all swap files

Usually Snow Owl is the only service running on a box, and its memory usage is controlled by the JVM options. There should be no need to have swap enabled.

On Linux systems, you can disable swap temporarily by running:

To disable it permanently, you will need to edit the /etc/fstab file and comment out any lines that contain the word swap.

Configure swappiness

Another option available on Linux systems is to ensure that the sysctl value vm.swappiness is set to 1. This reduces the kernel’s tendency to swap and should not lead to swapping under normal circumstances, while still allowing the whole system to swap in emergency conditions.

File descriptors

This is only relevant if you are running Snow Owl with an embedded Elasticsearch and not connecting it to an existing cluster.

Snow Owl (with embedded Elasticsearch) uses a lot of file descriptors or file handles. Running out of file descriptors can be disastrous and will most probably lead to data loss. Make sure to increase the limit on the number of open files descriptors for the user running Snow Owl to 65,536 or higher.

For the .zip and .tar.gz packages, set ulimit -n 65536 as root before starting Snow Owl, or set nofile to 65536 in /etc/security/limits.conf.

RPM and Debian packages already default the maximum number of file descriptors to 65536 and do not require further configuration.

Virtual memory

Snow Owl uses a mmapfs directory by default to store its data. The default operating system limits on mmap counts is likely to be too low, which may result in out of memory exceptions.

On Linux, you can increase the limits by running the following command as root:

To set this value permanently, update the vm.max_map_count setting in /etc/sysctl.conf. To verify after rebooting, run sysctl vm.max_map_count.

The RPM and Debian packages will configure this setting automatically. No further configuration is required.

Number of threads

Snow Owl uses a number of thread pools for different types of operations. It is important that it is able to create new threads whenever needed. Make sure that the number of threads that the Snow Owl user can create is at least 4096.

This can be done by setting ulimit -u 4096 as root before starting Snow Owl, or by setting nproc to 4096 in /etc/security/limits.conf.

The package distributions when run as services under systemd will configure the number of threads for the Snow Owl process automatically. No additional configuration is required.

Configure Snow Owl

Elasticsearch settings

By default, Snow Owl includes the OSS version of Elasticsearch and runs it in embedded mode to store terminology data and make it available for search. This is convenient for single-node environments (eg. for evaluation, testing and development), but it might not be sufficient when you go into production.

To configure Snow Owl to connect to an Elasticsearch cluster, change the clusterUrl property in the snowowl.yml configuration file:

The value for this setting should be a valid HTTP URL point to the HTTP API of your Elasticsearch cluster, which by default runs on port 9200.

Path settings

If you are using the .zip or .tar.gz archives, the data and logs directories are sub-folders of $SO_HOME. If these important folders are left in their default locations, there is a high risk of them being deleted while upgrading Snow Owl to a new version.

In production use, you will almost certainly want to change the locations of the data and log folders.

The RPM and Debian distributions already use custom paths for data and logs.

Network settings

To allow clients to connect to Snow Owl, make sure you open access to the following ports:

8080/TCP:: Used by Snow Owl Server's REST API for HTTP access
8443/TCP:: Used by Snow Owl Server's REST API for HTTPS access
2036/TCP:: Used by the Net4J binary protocol connecting Snow Owl clients to the server

Setting the heap size

By default, Snow Owl tells the JVM to use a heap with a minimum and maximum size of 2 GB. When moving to production, it is important to configure heap size to ensure that Snow Owl has enough heap available.

To configure the heap size settings, change the -Xms and -Xmx settings in the SO_JAVA_OPTS environment variable.

The value for these setting depends on the amount of RAM available on your server and whether you are running Elasticsearch on the some node as Snow Owl (either embedded or as a service) or running it in its own cluster. Good rules of thumb are:

Set the minimum heap size (Xms) and maximum heap size (Xmx) to be equal to each other.
Too much heap can subject to long garbage collection pauses.
Set Xmx

Start Snow Owl

The method for starting Snow Owl varies depending on how you installed it.

Archive packages (.tar.gz, .zip)

If you installed Snow Owl with a .tar.gz or zip package, you can start Snow Owl from the command line.

Running Snow Owl from the command line

Snow Owl can be started from the command line as follows:

By default, Snow Owl runs in the foreground, prints some of its logs to the standard output (stdout), and can be stopped by pressing Ctrl-C.

Running as a daemon

To run Snow Owl as a daemon, use the following command:

Log messages can be found in the $SO_HOME/serviceability/logs/ directory.

The startup scripts provided in the RPM and Debian packages take care of starting and stopping the Snow Owl process for you.

RPM packages

Snow Owl is not started automatically after installation. How to start and stop Snow Owl depends on whether your system uses SysV init or systemd (used by newer distributions). You can tell which is being used by running this command:

Running Snow Owl with SysV init

Use the chkconfig command to configure Snow Owl to start automatically when the system boots up:

Snow Owl can be started and stopped using the service command:

If Snow Owl fails to start for any reason, it will print the reason for failure to STDOUT. Log files can be found in /var/log/snowowl/.

Running Snow Owl with systemd

To configure Snow Owl to start automatically when the system boots up, run the following commands:

Snow Owl can be started and stopped as follows:

These commands provide no feedback as to whether Snow Owl was started successfully or not. Instead, this information will be written in the log files located in /var/log/snowowl/.

Stop Snow Owl

An orderly shutdown of Snow Owl ensures that Snow Owl has a chance to clean up and close outstanding resources. For example, an instance that is shutdown in an orderly fashion will initiate an orderly shutdown of the embedded Elasticsearch instance, gracefully close and disconnect connections and perform other related cleanup activities. You can help ensure an orderly shutdown by properly stopping Snow Owl.

If you’re running Snow Owl as a service, you can stop Snow Owl via the service management functionality provided by your installation.

If you’re running Snow Owl directly, you can stop Snow Owl by sending Ctrl-C if you’re running Snow Owl in the console, or by invoking the provided shutdown script as follows:

Advanced configuration

Config files location

Snow Owl has three configuration files:

snowowl.yml for configuring Snow Owl
serviceability.xml for configuring Snow Owl logging
elasticsearch.yml for configuring the underlying Elasticsearch instance in case of embedded deployments

These files are located in the config directory, whose default location depends on whether or not the installation is from an archive distribution (tar.gz or zip) or a package distribution (Debian or RPM packages).

For the archive distributions, the config directory location defaults to $SO_PATH_HOME/configuration. The location of the config directory can be changed via the SO_PATH_CONF environment variable as follows:

Alternatively, you can export the SO_PATH_CONF environment variable via the command line or via your shell profile.

For the package distributions, the config directory location defaults to /etc/snowowl. The location of the config directory can also be changed via the SO_PATH_CONF environment variable, but note that setting this in your shell is not sufficient. Instead, this variable is sourced from /etc/default/snowowl (for the Debian package) and /etc/sysconfig/snowowl (for the RPM package). You will need to edit the SO_PATH_CONF=/etc/snowowl entry in one of these files accordingly to change the config directory location.

Config file format

The configuration format is . Here is an example of changing the path of the data directory:

Settings can also be flattened as follows:

Environment variable substitution

Environment variables referenced with the ${...} notation within the configuration file will be replaced with the value of the environment variable, for instance:

Setting JVM options

The preferred method of setting JVM options (including system properties and JVM flags) is via the SO_JAVA_OPTS environment variable. For instance:

When using the RPM or Debian packages, SO_JAVA_OPTS can be specified in the system configuration file.

Logging configuration

Snow Owl uses and for logging.

The logging configuration file (serviceability.xml) can be used to configure Snow Owl logging. The logging configuration file location depends on your installation method, by default it is located in the ${SO_HOME}/configuration folder.

Extensive information on how to customize logging and all the supported appenders can be found on the .

Elasticsearch configuration

By default, Snow Owl is starting and connecting to an embedded Elasticsearch cluster available on http://localhost:9200. This cluster has only a single node and its discovery method is set to single-node, which means it is not able to connect to other Elasticsearch clusters and will be used exclusively by Snow Owl.

This single-node Elasticsearch cluster can easily serve Snow Owl in testing, evaluation and small authoring environments, but it is recommended to customize how Snow Owl connects to an Elasticsearch cluster in larger environments (especially when planning to scale with user demand).

You have two options to configure Elasticsearch used by Snow Owl.

Configure the embedded instance

The first option is to configure the underlying Elasticsearch instance by editing the configuration file elasticsearch.yml, which depending on your installation is available in the configuration directory (you can create the file, if it is not available, Snow Owl will pick it up during the next startup).

Connect to a remote cluster

The second option is to configure Snow Owl to use a remote Elasticsearch cluster without the embedded instance. To use this feature you need to set the repository.index.clusterUrl configuration parameter to the remote address of your Elasticsearch cluster. When Snow Owl is configured to connect to a remote Elasticsearch cluster, it won't boot up the embedded instance, which reduces the memory requirements of Snow Owl.

File realm

You can manage and authenticate users with the built-in file realm. All the data about the users for the file realm is stored in the users file. The file is located in SO_PATH_CONF and is read on startup.

You need to explicitly select the file realm in the snowowl.yml configuration file in order to use it for authentication.

identity:
  providers:
    - file:
        name: users

In the above configuration the file realm is using the users file to read your users from. Each row in the file represents a username and password delimited by : character. The passwords are BCrypt encrypted hashes. The default users file comes with a default snowowl user with the default snowowl password.

Users Command

To simplify file realm configuration, the Snow Owl CLI comes with a command to add a user to the file realm (snowowl users add). See the command help manual (-h option) for further details.

Authorization

The file security realm does NOT support the Authorization formats at the moment. If you are interested in configuring role-based access control for your users, it is recommended to switch to the .

Terminology Standards

This section describes the various supported healthcare standards, how they can be imported into a Snow Owl Terminology Server, and how they can be accessed and distributed further.

List of officially supported standards

SNOMED CT LOINC Socialstyrelsen Standards

Scenarios

This section describes the use case scenarios present in the world of SNOMED CT and how Snow Owl can be used in those scenarios to maximize its full potential. Each scenario comes with a summary and a pros/cons section to help your decision making process when selecting the appropriate scenario for your use case.

Single Edition
Single Extension

Single Edition

The most common use case to consume a SNOMED CT Release Package is to import it directly into a Terminology Server (like Snow Owl) and make it available as read-only content for both human and machine access (via REST and FHIR APIs).

SNOMED CT International Edition

Since Snow Owl by default comes with a pre-initialized SNOMED CT Code System called SNOMEDCT, it is just a single call to import the official RF2 package using the SNOMED CT RF2 Import API The import by default creates a Code System Version for each SNOMED CT Effective Date available in the supplied RF2 package. After a successful import the content is immediately available via REST and FHIR APIs.

SNOMED CT Extension Edition

National Release Centers and other Care Providers provide their own SNOMED CT Edition distribution for third-party consumers in RF2 format. Importing their Edition distribution instead of the International Edition directly into the SNOMEDCT pre-initialized SNOMED CT Code System with the same makes both the International Edition (always included in Edition packages) and the National Extension available for read-only access.

Summary

The single edition scenario without much effort provides access to any SNOMED CT Edition directly on the pre-initialized SNOMEDCT Code System. It is easy to set up and maintain. Because of its flat structure, it is good for distribution and extension consumers. Although it can be used for authoring in certain scenarios, due to the missing distinction between the International Edition and the Extension, it is not the best choice for extension authoring and maintenance.

This scenario can be further extended to support multiple simultaneous Edition releases living on their own dedicated SNOMED CT Code Systems. The Root SNOMEDCT Code System in this case is empty and only serves the purpose of creating other Code Systems "underneath" it. Each SNOMED CT Code System is then imported into its own dedicated branch forming a star-like branch structure at the end (zero-length MAIN branch and content branches). This is useful in distribution scenarios, where multiple Extension Code Systems need to be maintained with their own dedicated set of dependencies and there is no time to set up the proper Extension Scenario (see next section). The only drawback of this setup is the potentially high usage of disk space due to the overlap between the various Editions imported into their own Code Systems (since each of them contains the entire International Release).

Pros:

Good for maintaining the SNOMED CT International Edition
Good for distribution
Simple to set up and maintain

Cons:

Not recommended for extension authoring and maintenance
Not recommended for multi-extension distribution scenarios

Single Extension Authoring

A typical extension scenario is the development of the extension itself. Whether you are starting your extension from scratch or already have a well-developed version that you need to maintain, the first choice you need to make is to identify the dependencies of your SNOMED CT Extension.

Extending the International Edition

If your Extension extends the SNOMED CT International Edition directly, then you need to pick one of the available International Edition versions:

If you are starting from scratch, it is always recommended to select the latest International Release as the starting point of your Extension.
If you have an existing Extension then you probably already know the International Release version your Extension depends on.

When you have identified the version you need to depend on then you need to import that version (or a later release packages that also includes that version in its FULL RF2 package) first into Snow Owl. Make sure that the createVersion feature of the RF2 import process is enabled, so it will automatically create the versions for each imported RF2 effectiveTime value.

After you have successfully imported all dependencies into Snow Owl, the next step is to create a Code System that represents your SNOMED CT Extension (see ). When creating the Code System, besides specifying the namespace and optional modules and languages, you need to enter a Code System shortName, which will serve as the unique identifier of your Extension and select the extensionOf value, which represents the dependency of the Code System.

After you have successfully created the Code System representing your Extension, you can import any existing content from a most recent release or start from scratch by creating the module concept of your extension.

RF2 releases tend to have content issues with the International Edition itself or refer to missing content when you try to import them into Snow Owl via the RF2 Import API. For this reason, the recommended way is to always use the most recent Snapshot RF2 release of a SNOMED CT Extension to form its first representation in Snow Owl. That has a high probability of success without any missing component dependency errors during import. If you are having trouble importing an RF2 Release Package into Snow Owl, feel free to raise a question on our page.

Extending another Extension

If your Extension needs to extend another Extension and not the International Edition itself, then you need to identify the version you'd like to depend on in that Extension (that indirectly will select the International Edition dependency as well). When you have identified all required versions, then starting from the International Edition recursively traverse back and repeat the RF2 Import and Code System creation steps described in the previous section until you have finally imported your extension. In the end your extension might look like this, depending on how many Extensions you are depending on.

Summary

Setting up a Snow Owl deployment like this is not an easy task. It requires a thorough understanding of each SNOMED CT Extension you'd like to import and their dependencies as well. However, after the initial setup, the maintenance of your Extension becomes straightforward, thanks to the clear distinction from the International Edition and from its other dependencies. The release process is easier and you can choose to publish your Extension as an extension only release, or as an Edition or both (see ). Additionally, when a new version is available in one of the dependencies, you will be able to upgrade your Extension with the help of automated validation rules and upgrade processes (see ). From the distribution perspective, this scenario shines when you need to maintain multiple Extensions/Editions in a single deployment.

Pros:

Excellent for authoring and maintenance
Good for distribution

Cons:

Harder to set up the initial deployment

Multi Extension Authoring

Multi Extension Authoring and Distribution

On top of single Edition/Extension distribution and authoring, Snow Owl provides full support for multi-SNOMED CT distribution and authoring even if the Extensions depend on different versions of the SNOMED CT International Edition.

To achieve a deployment like this you need to perform the same initialization steps for each desired SNOMED CT Extension as if it were a single extension scenario (see single extension). Development and maintenance of each managed extension can happen in parallel without affecting one or the other. Each of them can have their own release cycles, maintenance and upgrade schedules, and so on.

Next steps

After you have initialized your Snow Owl instance with the Extensions you'd like to maintain the next steps are:

Development

Authoring is the process by which content is created in an extension in accordance with a set of authoring principles. These principles ensure the quality of content and referential integrity between content in the extension and content in the International Edition (the principles are set by SNOMED International, can be found here).

During the extension development process authors are:

creating, modifying or inactivating content according to editorial principles and policies
running validation processes to verify the quality and integrity of their Extension
classifying their authored content with an OWL Reasoner to produce its distribution normal form

The authors directly (via the available REST and FHIR APIs) or indirectly (via user interfaces, scripts, etc.) work with the Snow Owl Terminology Server to make the necessary changes for the next planned Extension release.

Workflow and Editing

Authors often require a dedicated editing environment where they can make the necessary changes and let others review the changes they have made, so errors and issues can be corrected before integrating the change with the rest of the Extension. Similarly to how SNOMED CT Extensions are separated from the SNOMED CT International Edition and other dependencies, this can be achieved by using branches.

- to create and merge branches
- to compare branches

Authoring APIs

To let authors make the necessary changes they need, Snow Owl offers the following SNOMED CT component endpoints to work with:

- to create and edit SNOMED CT Concepts
Description API - to create and edit SNOMED CT Descriptions
Relationship API - to create and edit SNOMED CT Relationships

Validation

To verify quality and integrity of the changes they have made, authors often generate reports and make further fixes according to the received responses. In Snow Owl, reports and rules can be represented with validation queries and scripts.

Validation API - to run validation rules and fetch their reported issues on a per branch basis

Classification

Last but not least, authors run an OWL Reasoner to classify their changes and generate the necessary normal form of their Extension. The Classification API provides support for running these reasoner instances and generating the necessary normal form.

Releases

When an Extension reaches the end of its current development cycle, it needs to be prepared for release and distribution.

Workflows and Authoring Branches

All planned content changes that are still on their dedicated branch either need to be integrated with the main development version or removed from the scope of the next release.

Prepare the Release

After all development branches have been merged and integrated with the main work-in-progress version, the Extension needs to be prepared for release. This usually involves last minute fixes, running quality checks and validation rules and generating the final necessary normal form of the Extension.

Release

When all necessary steps have been performed successfully, a new Code System Version needs to be created in Snow Owl to represent the latest release. The versioning process will assign the requested effectiveTime to all unpublished components, update the necessary Metadata reference sets (like the Module Dependency Reference Set) and finally create a version branch to reference this release later.

Packaging

After a successful release, an RF2 Release Package needs to be generated for downstream consumers of your Extension. Snow Owl can generate this final RF2 Release Packages for the newly released version via the RF2 Export API.

LOINC

(Pro feature)

As with every other resource in Snow Owl, a LOINC Code System needs to be created using the CodeSystems API first:

POST /codesystems
{
  "id": "LOINC",
  "url": "http://hl7.org/fhir/sid/loinc",
  "title": "LOINC",
  "language": "en",
  "description": "LOINC is a freely available international standard for tests, measurements, and observations",
  "status": "active",
  "copyright": "This material contains content from LOINC (http://loinc.org). LOINC is copyright ©1995-2023, Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.",
  "owner": "ownerUserId",
  "contact": "https://loinc.org/",
  "oid": "2.16.840.1.113883.6.1",
  "toolingId": "loinc",
  "settings": {
      "publisher": "Regenstrief Institute, Inc.",
  }
}

Then, an official release file can be imported via the following request:

POST /loinc/LOINC/import -F "file=@Loinc_2.77.zip"

And last, create a new version to tag the content:

POST /versions
{
  "resource": "codesystems/LOINC",
  "version": "2.77",
  "description": "LOINC 2.77 2024-02-27 release",
  "effectiveTime": "2024-02-27"
}

Socialstyrelsen Standards

(Pro feature)

This page describes the terminology standards offered publicly by the Swedish National Board of Health and Welfare:

ICD-10-SE

(Pro feature)

First, create the ICD-10-SE Code System:

POST /codesystems
{
  "id": "ICD10SE",
  "url": "http://hl7.org/fhir/sid/icd-10-se",
  "title": "ICD-10-SE",
  "language": "se",
  "description": "# Internationell statistisk klassifikation av sjukdomar och relaterade hĂ¤lsoproblem (ICD-10-SE)",
  "status": "active",
  "owner": "ownerUserId",
  "copyright": "",
  "contact": "https://www.socialstyrelsen.se/statistik-och-data/klassifikationer-och-koder/kodtextfiler/",
  "oid": "1.2.752.116.1.1.1",
  "toolingId": "icd10",
  "settings": {
    "publisher": "Socialstyrelsen",
    "isPublic": true
  }
}

Then, import the classification content from a ClaML file (generated by B2i Healthcare, request it here):

POST /icd10/ICD10SE/classes/import -F "file=@ICD-10-SE_2024_generated.xml"

And last, create a new version to mark the content:

POST /versions
{
  "resource": "codesystems/ICD10SE",
  "version": "2024-01-01",
  "description": "2024-01-01 release",
  "effectiveTime": "2024-01-01"
}

ICF

(Pro feature)

First, create the ICF Code System:

POST /codesystems
{
  "id": "icf",
  "url": "http://klassifikationer.socialstyrelsen.se/icf",
  "title": "ICF",
  "language": "se",
  "description": "# Internationell klassifikation av funktionstillstånd, funktionshinder och hälsa",
  "status": "active",
  "contact": "[email protected] - Avdelningen för register och statistik, Enheten för klassifikationer och terminologi",
  "owner": "ownerUserId",
  "oid": "1.2.752.116.1.1.3",
  "toolingId": "lcs",
  "settings": {
      "publisher": "Socialstyrelsen",
      "isPublic": true
  }
}

Then, using column mapping import the concepts from the official TSV file:

POST /lcs/icf/import?idColumn=Kod&ptColumn=Titel&synonymColumns=Beskrivning&synonymColumns=Alternativ%20titel&parentColumn=Överordnad%20kod&locale=se -F "[email protected]"

And last, create a new version to mark the content:

POST /versions
{
  "resource": "codesystems/icf",
  "version": "2024-01-01",
  "description": "2024-01-01 release",
  "effectiveTime": "2024-01-01"
}

KVÅ (KKÅ/KMÅ)

(Pro feature)

KKÅ

First, create the KKÅ Code System:

Then, import the concepts from the official TSV file:

And last, create a new version to mark the content:

REST APIs

Alternatives

To simplify integration and enable interoperability with third-party systems, Snow Owl TS offers two forms of accessing terminology resources via HTTP requests:

An API compliant with the requirements listed in the FHIR R5 specification for terminology services:

Resource management

Content access

Content management

SNOMED CT API

This describes the resources that make up the official Snow Owl® SNOMED CT Terminology API.

Swagger documentation is available on your Snow Owl instance at /snowowl/snomedct.

Available resources and services

Compare

Compare API

Comparison for current terminology changes committed to a source or target branch can be conducted by creating a compare resource.

A review identifier can be added to merge requests as an optional property. If the source or target branch state is different from the values captured when creating the review, the merge/rebase attempt will be rejected. This can happen, for example, when additional commits are added to the source or the target branch while a review is in progress; the review resource state becomes STALE in such cases.

Reviews and concept change sets have a limited lifetime. CURRENT reviews are kept for 15 minutes, while review objects in any other states are valid for 5 minutes by default. The values can be changed in the server's configuration file.

Reference Sets

Two categories make up Snow Owl's Reference Set API:

Reference Sets category to get, search, create and modify reference sets
Reference Set Members category to get, search, create and modify reference set members

Basic operations like create, update, delete are supported for both category.

Content syndication

With content syndication, data can be seamlessly moved between different Snow Owl Terminology Server deployments.

This functionality is useful when content created in a central deployment (upstream) needs to be distributed to one or more read-only downstream instances. The resource distribution is designed to be uni-directional and semi-automated where an actor has to configure any new downstream instances to be able to receive data from the central unit.

Configure upstream

To be able to access the upstream server and its content the following items are required:

the HTTP port of Elasticsearch has to be accessible for the downstream Snow Owl and Elasticsearch instances (configured via the http.port property, the default is 9200)
the REST API of Snow Owl has to be accessible for the downstream Snow Owl servers

Access Elasticsearch

In case Snow Owl uses a self-hosted Elasticsearch instance the HTTP port can be opened by modifying the container settings in the docker-compose.yml file. Make sure to remove the localhost IP prefix from the port declaration:

When opening up a self-hosted Elasticsearch make sure to use strengthened security with secure HTTP and username/password access.

A detailed guide on Elasticsearch security can be found .

In the case of a hosted Elasticsearch instance there is nothing to do, it will already be accessible from outside.

Access Snow Owl

The default reverse proxy configuration (shipped in the released package) exposes the Snow Owl REST API via the URL: http(s)://upstream-snow-owl-url/snowowl

Other than that no additional configuration is needed.

Obtain an Elasticsearch API key

Creating a new API key for Elasticsearch is either possible through its Api Key API or - in the case of a hosted instance - from within Kibana.

The content syndication operation requires the following permissions:

cluster privilege: monitor
index privilege: read

Here is an example request body for the Api Key API:

This request will return with the following response:

Take note of the encoded API Key, which is the one that will be used later on.

To obtain an API key using Kibana, follow with the same settings from above.

Obtain a Snow Owl API Key

To request an API key from the upstream Snow Owl Terminology Server the following REST API endpoint must be used:

To request an API key

POST https://upstream-snow-owl-url/snowowl/token

Request Body

Name

Type

Description

Select distributable resources

All three major terminology resource types can be configured as distributable. Resources have a settings map that can be updated via their specific REST API endpoints:

PUT /codesystems/{codeSystemId}
PUT /valuesets/{valueSetId}
PUT /conceptmaps/{conceptMapId}

A setting called distributable has to be set with a value of either true or false. Here is an example update request to make the 'Example Code System' distributable:

Configure downstream

Elasticsearch

There is one configuration property that must be set before provisioning a new downstream Snow Owl Terminology Server.

Any potential upstream Elasticsearch instance must be listed as an allowed source of information for the downstream Elasticsearch instances via a configuration parameter in the elasticsearch.yml file.

The property is called reindex.remote.whitelist :

The whitelisted URL must contain the upstream HTTP port and must not contain the scheme.

Provision a new downstream server

Provisioning a new downstream server has the following prerequisites:

start with an empty dataset
collect all terminology resource identifiers that need to be syndicated
get all the necessary credentials to communicate with upstream

Collect terminology resources for syndication

To populate a downstream server with terminology resources via an upstream source, one must collect the required resource identifiers or resource version identifiers beforehand.

Resource identifiers must be in their simple form, e.g.:

SNOMED-CT
ICD-10
LOINC

Resource version identifiers must be in the following form: <resource_id>/<version_id>, e.g.:

SNOMED-CT/2020-01-31
ICD-10/v2019
LOINC/v2.72

To determine which resources are available for syndication, the following upstream REST API endpoint can be used. It returns an atom feed that consists of resource versions from where one can collect the required identifiers.

Retrieve syndication resource feed

GET https://upstream-snow-owl-url/snowowl/syndication/feed.xml

Retrieves the feed of all distributable resources

Query Parameters

Name

Type

Description

It is not required to list all resource version identifiers for an already selected resource. E.g.:

If SNOMED-CT is selected as a resource, it is not required to select all its versions among the version resource identifiers.

Syndicate resources

To kick off a syndication process the following parameters are required:

the list of resource identifiers
the list of resource version identifiers
the upstream Snow Owl URL without its REST API root context:

When there are no existing resources on the downstream server yet, at least one resource identifier or one resource version identifier must be selected.

Snow Owl will resolve all resource dependencies and will handle syndication requests rigorously. If e.g. a Value Set depends on a specific SNOMED CT version and that version is not among the selected resources - or does not exist on the downstream server yet - the syndication run will fail to note that there is a missing dependency. It is always required to list all dependencies that the selected resources have for a given syndication run.

The above parameters should be fed to the following downstream Snow Owl REST API endpoint:

Syndicate resource(s)

POST https://downstream-snow-owl-url/snowowl/syndication/syndicate

Syndicate resources from a remote Snow Owl instance. In case no resource identifiers are provided, all existing resources will be syndicated to their latest version.

Request Body

Name

Type

Description

The syndication process starts in the background as an asynchronous job. It can be tracked by calling the following endpoint using the job identifier returned in the Location:

Retrieve syndication job

GET https://downstream-snow-owl-url/snowowl/syndication/{id}

Returns the specified syndication run's configuration and status.

Path Parameters

Name

Type

Description

The returned result object will contain all information related to the given syndication run:

status of the run (RUNNING, FINISHED, FAILED)
list of successfully syndicated resource versions

Examples of resource selection

Code Systems

There is a need to syndicate the SNOMED-CT US extension. It depends on the SNOMED CT International version 2021-01-31. Provide the following resource identifier and resource version identifier configuration:

This will syndicate all versions of SNOMED-CT-US and all international versions until 2021-01-31.

If the configuration is changed to:

This will syndicate all versions of SNOMED-CT-US and SNOMED-CT international, including all international versions even after 2021-01-31.

Value Sets

There is a Value Set with an identifier of VS and members from SNOMED-CT/2020-07-31:

Concept Maps

There is a Concept Map with an identifier of CM mapping concepts between LOINC/v2.72 and ICD-10/v2019:

Keeping a downstream server up-to-date

If a given downstream server already contains the desired resources and the goal is to keep the content up-to-date, it is not required to fill in the resource and resource version identifiers for the syndication request.

One can call the POST /syndication/syndicate endpoint with all the credentials and URLs but without specifying any resource or version identifier. The server will automatically determine - based on the set of existing downstream resources - if there are any new resource versions available for syndication.

To check whether there are any updates available, there is an endpoint that can be called:

Retrieve a list of resource versions which are available for syndication

GET https://downstream-snow-owl-url/snowowl/syndication/list

Returns the full list of resource versions to be syndicated based on the search criteria. If no filters are provided updates are calculated for all existing resources.

Query Parameters

Name

Type

Description

If there are any updates this endpoint will return a list of versions, if there are none it will return an empty result.

Concepts

Introduction

SNOMED CT concepts represent ideas that are relevant in a clinical setting and have a unique concept identifier (a SNOMED CT identifier or SCTID for short) assigned to them. The terminology covers a wide set of domains and includes concepts that represent parts of the human body, clinical findings, medicinal products and devices, among many others. SCTIDs make it easy to refer unambiguously to the described ideas in eg. an Electronic Health Record or prescription, while SNOMED CT's highly connected nature allows complex analytics to be performed on aggregated data.

Each concept is associated with human-readable descriptions that help users select the SCTID appropriate for their use case, as well as relationships that form links between other concepts in the terminology, further clarifying their intended meaning. The API for manipulating the latter two types of components are covered in sections and , respectively.

The three component types mentioned above (also called core components) have a distinct set of attributes which together form the concept's definition. As an example, each concept includes an attribute (the definition status) which states whether the definition is sufficiently defined (and so can be computationally processed), or relies on a (human) reader to come up with the correct meaning based on the associated descriptions.

Terminology services exposed by Snow Owl allows clients to create, retrieve, modify or remove concepts from a SNOMED CT code system (concepts that are considered to be already published to consumers can only be removed with an administrative operation). Concepts can be retrieved by SCTID or description search terms; results can be further constrained via Expression Constraint Language (ECL for short) expressions.

Resource format

A concept resource without any expanded properties looks like the following:

Properties

The resource includes all RF2 properties that are defined in SNOMED International's :

id
effectiveTime
active

It also contains the following supplementary information:

parentIds, ancestorIds

These arrays hold a set of SCTIDs representing the concept's direct and indirect ancestors in the inferred taxonomy. The (direct) parents array contains all destinationIds from active and inferred IS A relationships where the sourceId matches this concept's SCTID, while the ancestor array contains all SCTIDs taken from the parent and ancestor array of direct parents. The arrays are sorted by SCTID. A value of -1 means that the concept is a root concept that does not have any concepts defined as its parent. Typically, this only applies to 138875005|Snomed CT Concept| in SNOMED CT content.

See the following example response for a concept placed deeper in the tree:

Compare the output with a rendering from a user interface, where the concept appears in two different places after exploring alternative routes in the hierarchy. Parents are marked with blue, while ancestors are highlighted with orange:

statedParentIds, statedAncestorIds

Same as the above, but for the stated taxonomy view.

released

A boolean value indicating whether this concept was part of at least one SNOMED CT release. New concepts start with a value of false, which is set to true as part of the code system versioning process. Released concepts can only be deleted by an administrator.

iconId

A descriptive key for the concept's icon. The icon identifier typically corresponds to the lowercase, underscore-separated form of the contained in each concept's Fully Specified Name (or FSN for short). The following keys are currently expected to appear in responses (subject to change):

administration_method, assessment_scale, attribute, basic_dose_form, body_structure, cell, cell_structure, clinical_drug, disorder, disposition, dose_form, environment

In the metadata hierarchy, the use of a hierarchy tag alone would not distinguish concepts finely enough, as lots of them will have eg. "foundation metadata concept" set as their tag. In these cases, concept identifiers may be used as the icon identifier.

subclassDefinitionStatus

Currently unsupported. Indicates whether a parent concept's direct descendants form a in OWL 2 terms; when set to DISJOINT_SUBCLASSES, child concepts are assumed to be pairwise disjoint and together cover all possible cases of the parent concept.

The default value is NON_DISJOINT_SUBCLASSES where no such assumption is made.

Property expansion

Core component information related to the current concept can be attached to the response by using the expand query parameter, allowing clients to retrieve more data in a single roundtrip. Property expansion runs the necessary requests internally, and attaches results to the original response object.

Expand options are expected to appear in the form of propertyName1(option1: value1, option2: value2, expand(...)), propertyName2() where:

propertyNameN stands for the property to expand;
optionN: valueN are key-value pairs providing additional filtering for the expanded property;
optionally, expand

Supported expandable property names are:

`referenceSet()`

Expands reference set metadata and content, available on .

If a corresponding reference set was already created for an identifier concept (a subtype of 900000000000455006|Reference set), information about the reference set will appear in the response:

Note that the response object for property referenceSet can also be retrieved directly using the .

To retrieve reference set members along with the reference set in a single request, use a nested expand property named members:

Reference set members can also be fetched via the .

`preferredDescriptions()`

Expands descriptions with preferred acceptability.

Returns all active descriptions that have at least one active language reference set member with an acceptabilityId of 900000000000548007|Preferred|, in compact form, along with the concept. Preferred descriptions are frequently used on UIs when a display label is required for a concept.

This information is also returned when expand options pt() or fsn() (described later) are present.

`semanticTags()`

Returns hierarchy tags extracted from FSNs.

An array containing the hierarchy tags from all Fully Specified Name-typed descriptions of the concept is added as an expanded property if this option is present:

`inactivationProperties()`

Collects information from concept inactivation indicator and historical association reference set members referencing this concept.

Members of 900000000000489007|Concept inactivation indicator attribute value reference set| and subtypes of 900000000000522004 |Historical association reference set| hold information about a reason a concept is being retired in a release, as well as suggest potential replacement(s) for future use.

The concept stating the reason for inactivation is placed under inactivationProperties.inactivationIndicator.id (a short-hand property exists without an extra nesting, named inactivationProperties.inactivationIndicatorId). It is expected that only a single active inactivation indicator exists for an inactive concept.

Historical associations are returned under the property inactivationProperties.associationTargets as an array of objects. Each object includes the identifier of the historical association reference set and the target component identifier, in the same manner as described above – as an object with a single id property and as a string value.

While most object values where a single id key is present indicate that the property can be expanded to a full resource representation, this is currently not supported for inactivation properties; an expand option of inactivationProperties(expand(inactivationIndicator())) will not retrieve additional data for the indicator concept.

`members()`

Expands reference set members referencing this concept.

Note that this is different from reference set member expansion on a reference set, ie. referenceSet(expand(members())), as this option will return reference set members where the referencedComponentId property matches the concept SCTID, from multiple reference sets (if permitted by other expand options). Inactivation and historical association members can also be returned here, in their entirety (as opposed to the summarized form described in inactivationProperties() above).

Reference set members can also be fetched in a "standalone" fashion via the .

Compare the output with the one returned when inactivation indicators were expanded. The last two reference set members correspond to the historical association and the inactivation reason, respectively:

The following expand options are supported within members(...):

active: true | false

Controls whether only active or inactive reference set members should be returned.

refSetType: "{type}" | [ "{type}"(,"{type}")* ]

The reference set type(s) as a string, to be included in the expanded output; when multiple types are accepted, values must be enclosed in square brackets and separated by a comma.

expand(...)

Allows nested expansion of reference set member properties.

Allowed reference set type constants are (these are described in the section of SNOMED International's "Reference Sets Practical Guide" and the section of "Release File Specification" in more detail):

SIMPLE - simple type
SIMPLE_MAP - simple map type
LANGUAGE

See the following example for combining reference set member status filtering and reference set type restriction:

`module()`

Expands the concept's module identified by property moduleId, and places it under the property module. As the returned resource is a concept itself, property expansion can apply to modules as well by using a nested expand() option.

Property module does not appear in compact form (with a single id key) in the standard representation.

`definitionStatus()`

Expands the definition status concept identified by the property definitionStatusId, and places it under the property definitionStatus. When this property is not expanded, a smaller placeholder object with a single id property is returned in the response. Nested expand() options work the same way as in the case of module().

`pt()` and `fsn()`

Expands the (PT for short) and the (FSN for short) of the concept, respectively.

These descriptions are language context-dependent; the use of certain descriptions can be preferred in one dialect and acceptable or discouraged in others. The final output is controlled by the request header, which clients can use to supply a list of locales in order of preference.

In addition to the standard locales like en-US, Snow Owl uses an extension to allow referring to language reference sets by identifier, in the form of {language code}-x-{language reference set ID}. "Traditional" language tags are resolved to language reference set IDs as part of executing the request by consulting the code system settings:

An example response pair demonstrating cases where the PT is different in certain dialects:

`descriptions()`

Expands all descriptions associated with the concept, and adds them to a collection resource (that includes an element limit and a total hit count) under the property descriptions. These can also be retrieved separately by the use of the .

The collection resource's limit and total values are set to the same value (the number of descriptions returned for the concept) because a description fetch limit can not be set via a property expand option.

The following expand options are supported within descriptions(...):

active: true | false

Controls whether only active or inactive descriptions should be included in the response. (If both are required, do not set any value for this expand property.)

typeId: "{expression}"

An ECL expression that restricts the typeId property of each returned description. The simplest expression is a single SCTID, eg. when this option has a value of "900000000000013009", only will be expanded.

sort: "{field}(:{asc | desc})?"(, "{field}(:{asc | desc})")*

Items in the collection resource are sorted based on the sort configuration given in this option. A single, comma-separated string value is expected; field names and sort order must be separated by a colon (:) character. When no sort order is given, ascending order (asc) is assumed.

expand(...)

Allows nested expansion of description properties.

`relationships()`

Retrieves all "outbound" relationships, where the sourceId property matches the SCTID of the concept(s), adding them to a property named relationships as a collection resource object. The same set of relationships can also be retrieved in standalone form via Snow Owl's .

limit and total values on relationships are set to the same value (the number of relationships returned for the concept) because a relationship fetch limit can not be set via an expand option.

The following expand options are supported within relationships(...):

active: true | false

Controls whether only active or inactive relationships should be included in the response. (If both are required, do not set any value for this expand property.)

characteristicTypeId: "{expression}"

An ECL expression that restricts the characteristicTypeId property of each returned relationship. As an example, when this value is set to "<<900000000000006009", both stated and inferred relationships will be returned, as their characteristic type concepts are descendants of 900000000000006009|Defining relationship|.

typeId: "{expression}"

An ECL expression that restricts the typeId property of each returned relationship.

destinationId: "{expression}"

An ECL expression that restricts the destinationId property of each returned relationship.

sort: "{field}(:{asc | desc})?"(, "{field}(:{asc | desc})")*

expand(...)

Allows nested expansion of relationship properties.

`inboundRelationships()`

Retrieves all "inbound" relationships, where the destinationId property matches the SCTID of the concept(s), adding them to property inboundRelationships.

limit and total values on inboundRelationships are set to the same value (the number of inbound relationships returned for the concept), but differently from options above, a fetch limit is applied when it is specified.

The same set of options are supported within inboundRelationships as in relationships (see ), with three important differences:

destinationId: "{expression}"

This option is not supported on inboundRelationships; all destination IDs match the concept's SCTID.

sourceId: "{expression}"

An ECL expression that restricts the sourceId property of each returned relationship.

limit: {limit}

Limits the maximum number of inbound relationships to be returned. Not recommended for use when the expand option applies to a collection of concepts, not just a single one, as the limit is not applied individually for each concept.

`descendants()` / `statedDescendants()`

Depending on which direct setting is used, retrieves all concepts whose [stated]parentIds and/or [stated]AncestorIds array contains this concept's SCTID. Results are added to property descendants or statedDescendants, based on the option name used.

Only active concepts are returned, as these are expected to have active "IS A" relationships or OWL axioms that describe the relative position of the concept within the terminology graph.

The following options are available:

direct: true | false (required)

Controls whether only direct descendants should be collected or a transitive closure of concept subtypes.

When set to true, property [stated]parentIds will be searched only, otherwise both [stated]parentIds and [stated]AncestorIds are used. The presence or absence of the "stated" prefix in the search field depends on the option name.

limit: 0

Applicable only when a single concept's properties are expanded. Collects the number of descendants in an efficient manner, and sets the total property of the returned collection resource without including any concepts in it. Not used when a collection of concepts are expanded in a single request, or any other value is given.

expand(...)

Allows nested expansion of concept properties on each collected descendant.

`ancestors()` / `statedAncestors()`

Depending on which direct setting is used, retrieves all concepts that appear in this concept's [stated]parentIds and/or [stated]AncestorIds array. Results are added to property ancestors or statedAncestors, based on the option name used.

The following options are available:

direct: true | false (required)

Controls whether only direct ancestors should be collected or a transitive closure of concept supertypes.

When set to true, property [stated]parentIds will be used only for concept retrieval, otherwise the union of [stated]parentIds and [stated]AncestorIds are collected (the special placeholder value "-1" is ignored). The presence or absence of the "stated" prefix in the search field depends on the option name.

limit: 0

Collects the number of ancestors in an efficient manner, and sets the total property of the returned collection resource without including any concepts in it. Not used when any other value is given (however, this property expansion supports cases where multiple concepts' ancestors need to be returned).

expand(...)

Allows nested expansion of concept properties on each collected ancestor.

Operations

Read concept (GET)

A GET request that includes a concept identifier as its last path parameter will return information about the concept in question:

Query parameters

expand={options}

Concept properties that should be returned along with the original request, as part of the concept resource. See available options in section above.

field={field1}[,{fieldN}]*

Restricts the set of fields returned from the index. Results in a smaller response object when only specific information is needed.

Supported names for field selection are the following:

active
activeMemberOf
ancestors

Specifying any other field name results in a 400 Bad Request response:

Fields with a value of null do not appear in the response, even if they are selected for inclusion.

Request headers

Accept-Language: {language-range}[;q={weight}](, {language-range}[;q={weight}])*

Controls the logic behind Preferred Term and Fully Specified Name selection for the concept. See the documentation for expand options for details.

Specifying an unknown language or dialect results in a 400 Bad Request response:

Find concepts (GET)

A GET request that ends with concepts as its last path parameter will search for concepts matching all of the constraints supplied as query parameters. By default (when no query parameter is added) it returns all concepts.

The response consists of a collection of concept resources, a searchAfter key (described in section "Query parameters" below), the limit used when computing response items and the total hit count:

Query parameters

definitionStatus={eclExpression} | {id1}[,{idN}]*

An ECL expression or enumerated list that describes the allowed set of SCTIDs that must appear in matching concepts' definitionStatusId property. Since there are only two values used, 900000000000074008|Primitive| and 900000000000073002|Defined| for primitive and fully defined concepts, respectively, a single SCTID is usually entered here.

ecl={eclExpression}

Restricts the returned set of concepts to those that match the specified ECL expression. The query parameter can be used on its own for evaluation of expressions, or in combination with other query parameters. Expressions conforming to the short form of ECL 1.5 syntax are accepted. The expression is evaluated over the , based on the currently persisted inferred relationships.

As ECL syntax uses special symbols, query parameters should be encoded to URL-safe characters. The examples in this section are using the cleartext form for better readability.

statedEcl={eclExpression}

Same as ecl, but the input expression is evaluated over the by using stated relationships (if present) and OWL axioms for evaluation.

semanticTag={tag1}[,{tagN}]*

Filters concepts by a comma-separated list of allowed hierarchy tags. Matching concepts can have any of the supplied tags present (at least one) on their Fully Specified Names.

term={searchTerm}

Matching concepts must have an active description whose term matches the string specified here. The search is executed in "smart match" mode; the following examples show which search expresssions match which description terms:

descriptionType={eclExpression} | {id1}[,{idN}]*

Restricts the result set by description type; matches must have at least one active description whose typeId property is included in the evaluated ECL result set or SCTID list. It is typically used in combination with term (see above) to control which type of descriptions should be matched by term.

parent={id1}[,{idN}]*
statedParent={id1}[,{idN}]*
ancestor={id1}[,{idN}]*

Filters concepts by hierarchy. All four query parameters accept a comma-separated list of SCTIDs; the result set will contain direct descendants of the specified values in the case of parent and statedParent, and a transitive closure of descendants for ancestor and statedAncestor (including direct children). Parameters starting with stated... will use the stated IS A hierarchy for computations.

doi=true | false

Controls whether relevance-based sorting should take Degree of Interest (DOI for short) into account. When enabled, concepts that are used frequently in a clinical environment are favored over concepts with a lower likelihood of use.

namespace={namespaceIdentifier}
namespaceConceptId={id1}[,{idN}]*

The SCTID of matching concepts must have the specified 7-digit , eg. 1000154. When matching by namespace concept ID, a comma-separated list of SCTIDs are expected, and the associated 7-digit identifier will be extracted from the active FSNs of each concept entered here.

isActiveMemberOf={eclExpression} | {id1}[,{idN}]*

This filter accepts either a single ECL expression, or a comma-separated list of reference set SCTIDs. For each matching concept at least one active reference set member must exist where the referenceComponentId points to the concept and the referenceSetId property is listed in the filter, or is a member of the evaluated ECL expression's result set.

effectiveTime={yyyyMMdd} | Unpublished

Filters concepts by effective time. The query parameter accepts a single effective time in yyyyMMdd (short) format, or the literal Unpublished when searching for concepts that have been modified since they were last published as part of a code system version.

Note that only the concept's effective time is taken into account, not any of its related core components (descriptions, relationships) or reference set members. If the concept's status, definition status or module did not change since the last release, its effective time will not change either.

When searching for Unpublished concepts, the effectiveTime property will not appear on returned concept resources, as the value is null for all unpublished components.

active=true | false

Filters concepts by status. When set to true, only active concepts are added to the resulting collection, while a value of false collects inactive concepts only. (If both active and inactive concepts should be returned, do not add this parameter to the query.)

module={eclExpression} | {id1}[,{idN}]*

Filters concepts by moduleId. The query parameter accepts either a single ECL expression, or a comma-separated list of module SCTIDs; concepts must have a moduleId property that is included in the ID list or the evaluated ECL result.

id={id1}[,{idN}]*

Filters concepts by SCTID. The parameter accepts a comma-separated list of IDs; matching concepts must have an id property that matches any of the specified identifiers.

sort: "{field}(:{asc | desc})?"(, "{field}(:{asc | desc})")*

Sorts returned concept resources based on the sort configuration given in this parameter. Field names and sort order must be separated by a colon (:) character. When no sort order is given, ascending order (asc) is assumed.

Field names supported for sorting are the same that are used for field selection; please see for the complete list.

The default behavior is to sort results by id, in ascending order. SCTIDs are sorted lexicographically, not as numbers; this means that eg. 10683591000119104 will appear before 10724008, as their first two digits are the same, but the third digit is smaller in the former identifier.

limit={limit}

Controls the maximum number of items that should be returned in the collection. When not specified, the default limit is 50 items.

searchAfter={searchAfter}

Supports keyset pagination, ie. retrieving the next page of items based on the response for the current page. To use, set limit to the number of items expected on a single page, then run the first search request without setting a searchAfter key. The returned response will include the value to be inserted into the next request:

The process can be repeated until the items array turns up empty, indicating that there are no more pages to return.

searchAfter keys should be considered opaque; they can not be constructed to jump to an arbitrary point in the enumeration. Keyset pagination also doesn't handle cases gracefully where eg. concepts with "smaller" SCTIDs are inserted while pages are retrieved from the server. If a consistent result set is expected, a path parameter should be used in consecutive search requests.

expand={options}

Concept properties that should be returned along with the original request, as part of the concept resource. See available options in section above.

field={field1}[,{fieldN}]*

Restricts the set of fields returned from the index. Results in a smaller response object when only specific information is needed. See for the list of supported field names.

Request headers

Accept-Language: {language-range}[;q={weight}](, {language-range}[;q={weight}])*

Controls the logic behind Preferred Term and Fully Specified Name selection for returned concepts. See the documentation for expand options for details.

Find concepts (POST)

POST requests submitted to concepts/search perform the same search operation as described for the GET request above, but each query parameter is replaced by a property in the JSON request body:

Request headers

Accept-Language: {language-range}[;q={weight}](, {language-range}[;q={weight}])*

Controls the logic behind Preferred Term and Fully Specified Name selection for returned concepts. See the documentation for expand options for details.

Create concept (POST)

POST requests submitted to concepts create a new concept with the specified parameters, then commit the result to the terminology repository.

The resource path typically consists of a single code system identifier for these requests, indicating that changes should go directly to the working branch of the code system, or a direct child of the working branch for isolating a set of changes that can be reviewed and merged in a single request.

The request body needs to conform to the following requirements:

include at least one Fully Specified Name (FSN)
include at least one preferred synonym (Preferred Term, PT)

The SCTID of created components can be specified in two ways:

Explicitly by setting the id property on the component object; the request fails when an existing component in the repository already has the same SCTID assigned to it;
Allowing the server to generate an identifier by leaving id unset and populating namespaceId with the expected namespace identifier, eg. "1000154". Requests using namespaceId

When a namespaceId is set on the concept level, descriptions and relationships will use this value by default, so in this case neither id nor namespaceId needs to be set on them. The same holds true for moduleId – the concept's module identifier is applied to all related descriptions, relationships and reference set members in the request, unless it is set to a different value on the component object.

Please see the example below for required properties. (Note that it is non-executable in its current form, as the OWL axiom reference set member can not be created without knowing the concept's SCTID in advance.)

A successful commit will result in a 201 Created response; the response header Location can be used to extract the generated concept identifier. Validation errors in the request body cause a 400 Bad Request response.

Request headers

X-Author: {author_id}

Changes the author recorded in the commit message from the authenticated user (default) to the specified user.

Update concept (PUT)

PUT requests to locations that identify a concept resource (same as when concept content) will update the concept. Following a successful commit, the state of the concept on the branch should match the state received in the request body.

The following properties can be updated on any component. If they are not included in the request, the corresponding component property remains unchanged.

moduleId: string
active: boolean
effectiveTime

When a concept, an object named inactivationProperties can be added that can point to possible replacement concepts and/or specify the reason for inactivation:

Specifying an empty string for inactivationIndicatorId will remove an existing indicator, while an empty array will delete historical association reference set members for the concept. This is handled automatically when the concept is re-activated, so inactivationProperties can be omitted from such requests entirely:

Properties that can be updated on the concept itself are:

definitionStatusId: string
subclassDefinitionStatus: "DISJOINT_SUBCLASSES" | "NON_DISJOINT_SUBCLASSES"

In addition to the above, core components and reference set members related to the concept in question can be updated in a single request by including any of the following properties:

descriptions
relationships
members

Each of the above can hold a collection resource of the respective component resource type. These resources are described in detail in sections , and , respectively.

If a collection resource property is not included in the update request, the corresponding component type is unchanged. An empty array attempts to delete all existing related components. Otherwise, the components included in the collection are compared by SCTID/UUID to existing components, and it is decided whether:

a new component should be created (if the identifier did not appear previously in the terminology store)
an existing component should be updated (if the identifier existed previously in the terminology store)
an existing component should be deleted (if the identifier does not exist in the request, but existed previously in the terminology store)

Successful updates return 204 No Content from the server. Updates that attempt to modify the state of a missing or deleted concept result in a 404 Not Found response.

Query parameters

force=true | false

Specifies whether updating the effective time of the concept should be allowed. The default value is false; in such cases, supplying an effective time property for the update is disallowed. The component's effective time after an update is computed automatically at all times, when the force property is set to true, this can be overridden externally.

Request headers

X-Author: {author_id}

Changes the author recorded in the commit message from the authenticated user (default) to the specified user.

Delete concept (DELETE)

DELETE requests sent to a URI where the last path parameter is an existing concept ID will remove the concept and all of its associated components (descriptions, relationships, reference set members referring to the concept) from the terminology repository.

Deletes are acknowledged with a 204 No Content response on success. Deletion can be verified by trying to retrieve concept information from the same resource path – a 404 Not Found should be returned in this case.

Note that resource branches maintain content in isolation, and so deleting a concept on eg. a task branch will not remove the concept from the code system's working branch, until work on the task branch is approved and merged into mainline.

Query parameters

force=true | false

Specifies whether deletion of the concept should be allowed, if it has components that were already part of an RF2 release (or code system version). This is indicated by the released property on each component.

The default value is false; with the option disabled, attempting to delete a released component results in a 409 Conflict response:

Only administrators should set this parameter to true. It is advised to delete redundant or erroneous components before they are put in circulation as part of a SNOMED CT RF2 release. In other cases, inactivation should be preferred over removal.

Request headers

X-Author: {author_id}

Changes the author recorded in the commit message from the authenticated user (default) to the specified user.

9.x

Introduction

Quick Start

hashtagTL;DR

Create your first Resource

hashtagCreate a Code System

Import SNOMED CT from RF2

Find concepts by ID or term

hashtagSearch by identifier

hashtagSearch by term

Find concepts using ECL

Next steps

hashtagREST API

hashtagConclusion

Setup and Administration

Plan your deployment

Technology stack

Software requirements

hashtagOperating System

hashtagSoftware packages

hashtagFirewall

Configuration

Release package

Preload dataset (optional)

Configure Elastic Cloud (optional)

hashtag

System settings

hashtagConfigure your host for Elasticsearch requirements

hashtagConfigure your host for Snow Owl requirements

hashtagSet permissions for folders and files appropriately

hashtagBind-mount Snow Owl's temporary working folder

Spin up the service

Upgrade Snow Owl

Backup and restore

Advanced installation methods

hashtagJava (JVM) Version

Install Snow Owl

Disable swapping

hashtagDisable all swap files

hashtagConfigure swappiness

File descriptors

Virtual memory

Number of threads

Configure Snow Owl

hashtagElasticsearch settings

hashtagPath settings

hashtagNetwork settings

hashtagSetting the heap size

Start Snow Owl

hashtagArchive packages (.tar.gz, .zip)

hashtagRunning Snow Owl from the command line

hashtagRunning as a daemon

hashtagRPM packages

hashtagRunning Snow Owl with SysV init

hashtagRunning Snow Owl with systemd

Stop Snow Owl

Advanced configuration

hashtagConfig files location

hashtagConfig file format

hashtagEnvironment variable substitution

Setting JVM options

Logging configuration

Elasticsearch configuration

hashtagConfigure the embedded instance

hashtagConnect to a remote cluster

File realm

hashtagUsers Command

hashtagAuthorization

Terminology Standards

hashtagList of officially supported standards

Scenarios

Single Edition

hashtagSNOMED CT International Edition

hashtagSNOMED CT Extension Edition

hashtagSummary

Single Extension Authoring

hashtagExtending the International Edition

hashtagExtending another Extension

hashtagSummary

Multi Extension Authoring

TL;DR

Create a Code System

Search by identifier

Search by term

REST API

Conclusion

Operating System

Software packages

Firewall

Configure your host for Elasticsearch requirements

Configure your host for Snow Owl requirements

Set permissions for folders and files appropriately

Bind-mount Snow Owl's temporary working folder

Java (JVM) Version

Disable all swap files

Configure swappiness

Elasticsearch settings

Path settings

Network settings

Setting the heap size

Archive packages (.tar.gz, .zip)

Running Snow Owl from the command line

Running as a daemon

RPM packages

Running Snow Owl with SysV init

Running Snow Owl with systemd

Config files location

Config file format

Environment variable substitution

Configure the embedded instance

Connect to a remote cluster

Users Command

Authorization

List of officially supported standards

SNOMED CT International Edition

SNOMED CT Extension Edition

Summary

Extending the International Edition

Extending another Extension

Summary

Multi Extension Authoring and Distribution

Next steps

Workflow and Editing

Authoring APIs

Validation

Classification

Workflows and Authoring Branches

Prepare the Release

Release

Packaging

KKÅ

Alternatives

Available resources and services

Compare API

REST API

Conclusion

TL;DR

Supported architectures

Start your deployment

Change memory settings

Check the healthiness of the service

Features

Revision-controlled authoring and distribution

SNOMED CT and others

Various sets of APIs

Highly extensible and configurable

Full-text search and data storage

Acknowledgments

List of officially supported standards

Java (JVM) Version

Configure the embedded instance

Connect to a remote cluster

Terminology Server