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: https://hl7.org/fhir/R5/terminology-service.html

• A native API that is customized to match Snow Owl's internal representation of its supported resources, and so can provide more options

The following pages provide additional information on each method of access:

Official Examples

A comprehensive set of examples is available in our Postman collection: https://documenter.getpostman.com/view/16295366/2s93z3h6cP

Interactive documentation

Port 8080 and the context path /snowowl is assigned in the default installation for serving both APIs. Navigate to http(s)://<host>:8080/snowowl/ to visit the built-in "interactive playground" which lists all available requests by category in the dropdown on the top left:

Once valid user credentials are entered on the "Authentication" page reachable from the sidebar, it becomes possible to send requests to the server and inspect the returned response body as well as any relevant headers:

Select a request from the sidebar so that its documentation page appears in the main area. Each request is accompanied by a short description and the list of parameters it accepts. Fields marked with a * symbol are required.

Press the Try button after populating the input fields to execute the request:

Introduction

The paid version of Snow Owl TS supports interactions and operations that target concept map resources.

Interactions

read (instance)

GET requests that include the identifier of the concept map return the resource's current state:

GET /snowowl/fhir/ConceptMap/69YWt6qc1ydgwARjh8XNw2

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType": "ConceptMap",
  "id": "69YWt6qc1ydgwARjh8XNw2",
  "meta": {
    "lastUpdated": "2023-11-30T16:36:31.653Z"
  },
  "language": "en",
  "text": {
    "status": "empty",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "https://b2ihealthcare.com/conceptmaps/example-concept-map",
  "name": "69YWt6qc1ydgwARjh8XNw2",
  "title": "Example Concept Map",
  "status": "draft",
  "description": "# Example Concept Map",
  "group": [
    {
      "source": "http://snomed.info/sct/900000000000207008|2023-10-01",
      "target": "https://b2ihealthcare.com/codesystems/example-lcs-1|v1",
      "element": [
        {
          "code": "103015000",
          "display": "Thoracic nerve root pain",
          "target": [
            {
              "code": "C00",
              "display": "Root concept",
              "relationship": "equivalent"
            }
          ]
        }
      ]
    }
  ]
}

Just as with CodeSystem or ValueSet read interactions, query parameters _format, _summary, _elements and _pretty are applicable. #common-request-parameters expands on these settings.

update (instance)

PUT requests that include a resource identifier will update an existing resource (or create a new one if it didn't exist earlier):

PUT /snowowl/fhir/ConceptMap/69YWt6qc1ydgwARjh8XNw2

[Request headers]
X-Author: user@host.domain
Content-Type: application/fhir+json

[Request body]
{
  "resourceType": "ConceptMap",
  "id": "69YWt6qc1ydgwARjh8XNw2",
  "meta": {
    "lastUpdated": "2023-11-30T16:36:31.653Z"
  },
  "language": "en",
  "text": {
    "status": "empty",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "https://b2ihealthcare.com/conceptmaps/example-concept-map",
  "name": "69YWt6qc1ydgwARjh8XNw2",
  "title": "Example Concept Map",
  "status": "draft",
  "description": "# Example Concept Map",
  "group": [
    {
      "source": "http://snomed.info/sct/900000000000207008|2023-10-01",
      "target": "https://b2ihealthcare.com/codesystems/example-lcs-1|v1",
      "element": [
        {
          "code": "103015000",
          "display": "Thoracic nerve root pain",
          "target": [
            {
              "code": "C00",
              "display": "Root concept",
              "relationship": "equivalent"
            }
          ]
        },
        // Added mapping
        {
          "code": "102506008",
          "display": "Well child (finding)",
          "target": [
            {
              "code": "C00-1",
              "display": "Child concept",
              "relationship": "equivalent"
            }
          ]
        }
      ]
    }
  ]
}

The response code is 201 Created if the resource did not exist previously, and the URL is included in the Location response header. Existing concept maps (like in the example above) are updated and a 200 OK response is returned instead.

If an error occurs during the update, a 400 Bad Request response with an OperationOutcome resource as the response body is emitted instead.

The following non-standard request headers can be used to control certain aspects of the commit process:

• X-Effective-Date -> the effective date to use if a version identifier is present in the resource without a corresponding date element

• X-Author -> sets the user identifier that the commit should be attributed to (defaults to the authenticated user)

• X-Owner -> sets the owner of the resource, for access control purposes in external systems (defaults to the author or the authenticated user if the former is not set)

• X-Owner-Profile -> sets the human-readable name of the owner of the resource, for presentation purposes in external systems

• X-Bundle-Id -> specifies the parent bundle's resource identifier (defaults to the root bundle if not set)

delete (instance)

A DELETE request removes an existing concept map:

DELETE /snowowl/fhir/ConceptMap/69YWt6qc1ydgwARjh8XNw2

[Request headers]
X-Author: user@host.domain

[Response]
204 No Content

Successful removal of a resource results in a 204 No Content response.

Concept maps that have already been versioned can not be removed without adding the force=true query parameter to signal a forced deletion (this option is only available to administrators however).

create (type)

In create interactions a POST request is sent to the path corresponding to the resource type. Any identifier included in the request body is ignored and a new, random one is generated from scratch.

POST /snowowl/fhir/ConceptMap

[Request headers]
X-Effective-Date: 2023-11-29
X-Author: user@host.domain
X-Owner: owner@host.domain
X-Owner-Profile-Name: Resource Owner
X-Bundle-Id: parent-bundle-id
Content-Type: application/fhir+json

[Request body]
{
  "resourceType": "ConceptMap",
  // "id": "..." is not used by the server
  "text": {
    "status": "empty",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "https://b2ihealthcare.com/conceptmaps/example-concept-map-2",
  "title": "Example Concept Map",
  "status": "draft",
  "group": [
    {
      "source": "http://snomed.info/sct/900000000000207008|2023-10-01",
      "target": "https://b2ihealthcare.com/codesystems/example-lcs-1|v1",
      "element": [
        {
          "code": "103015000",
          "display": "Thoracic nerve root pain (finding)",
          "target": [
            {
              "code": "C00",
              "display": "Root concept",
              "relationship": "equivalent"
            }
          ]
        }
      ]
    }
  ]
}



[Response]
201 Created

[Response headers]
Location: http://<host>/snowowl/fhir/ConceptMap/cndkDE31kfeXw8

The response code is 201 Created if the interaction is successful. The request URL that can be used in eg. follow-up read interactions is included in the response header named Location.

search (type)

GET requests with a request path that points to the resource type returns all concept maps that satisfy the specified search criteria, in the form of query parameters. The following example uses the count summary mode to determine the number of active concept maps in the system, without returning any of the matches:

GET /snowowl/fhir/ConceptMap?status=active&_summary=count

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType": "Bundle",
  "id": "conceptmaps",
  "meta": {
    "lastUpdated": "2023-11-30T16:52:08.443803Z"
  },
  "type": "searchset",
  "total": 22
}

The following search parameters are supported:

• _id -> matches concept maps by logical identifier

• name -> matches concept maps by name (in Snow Owl this is set to the logical identifier)

• title -> matches concept maps by title (Snow Owl uses exact, phrase and prefix matching during its lexical search activities)

• url -> matches concept maps by their assigned url value

• version -> matches concept maps by their version value

• status -> matches concept maps by resource status (eg. draft, active, etc.)

Operations

$translate

Snow Owl TS uses the path parameter (and optionally, conceptMapVersion) to identify the concept map used for the operation. Supplying a concept map resource "inline" as input parameter conceptMap is not supported.

Parameters sourceScope and targetScope are also ignored.

The presence of a source* parameter (code, coding or codeable concept) implies that the translation needs to find "forward" (target) matches, while target* codes, codings or codeable concepts will run the translation in reverse.

An example translation request can be seen below:

GET /snowowl/fhir/ConceptMap/cndkDE31kfeXw8/$translate?system=http://snomed.info/sct/900000000000207008&code=103015000

[Query parametes (repeated for clarity)]
system: http://snomed.info/sct/900000000000207008
code: 103015000

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "message",
      "valueString": "1 member(s) from concept map: cndkDE31kfeXw8"
    },
    {
      "name": "match",
      "part": [
        {
          "name": "relationship",
          "valueCode": "equivalent"
        },
        {
          "name": "concept",
          "valueCoding": {
            "system": "codesystems/example-lcs-1",
            "code": "C00",
            "display": "Root concept"
          }
        },
        {
          "name": "originMap",
          "valueUri": "cndkDE31kfeXw8"
        }
      ]
    }
  ]
}

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

Available resources and services

Introduction

HL7's Fast Healthcare Interoperability Resources (FHIR) standard describes data types, resources, interactions, coded values and their associated code systems that are used to represent and exchange structured clinical data.

Thanks to its pluggable and extensible architecture, Snow Owl TS is able to expose clinically relevant resources like code systems, value sets and concept maps in a format that can be consumed by third-party FHIR clients. Additionally, Snow Owl's revision model allows concurrent management of resource versions.

Interactive documentation

Navigate to http://<host>:8080/snowowl/ and select "FHIR API" from the category dropdown to see the full list of FHIR requests supported by Snow Owl TS:

Request/response formats

JSON and XML formats are both supported; resources in Turtle RDF format are not accepted (nor produced) by the server. The MIME type for these formats can appear in the Accept and Content-Type headers. These are the following:

• XML

  • application/fhir+xml

  • application/xml

  • text/xml

• JSON

  • application/fhir+json

  • application/json

  • text/json

Unless explicitly stated in the MIME type, the server accepts and responds in the R5 format. To select an explicit FHIR version format the fhirVersion argument can be used along with the fhir+json/xml media types. For example:

All declared and provided FHIR endpoints support the following FHIR Specification versions:

Common request parameters

Override response format

Clients can override the desired output format by using the _format query parameter, if they have limited access to request headers. In this case shorthand values like xml and json are also permitted (Content-Type must still be set correctly if the request includes a body):

Snow Owl returns a 406 Not Acceptable response if the client requested a response format it does not support. Conversely, if the request body is in a format it does not recognize, a 415 Unsupported Media Type response is emitted.

Pretty-printing

For development purposes, responses returned from the server can be formatted so they are more pleasing to the human eye. The example above already includes the query parameter that controls this behavior; it is named _pretty. Setting its value to true results in pretty-printed output.

Resource summary

The query parameter _summary controls whether a subset of the elements should be returned for a resource. Supported values are:

• true -> return a pre-defined subset of elements from the resource (these are marked as "summary" in the FHIR specification)

• false -> return all elements of the resource

• text -> return text, id, meta and top-level elements marked as "mandatory" in the FHIR specification (to ensure that the response remains a valid FHIR resource representation)

• data -> remove the text element that contains a human-readable rendering of the resource, in the form of eg. an XHTML snippet

• count -> return hit count without the accompanying list of matching resources (applicable in resource search interactions only)

When summary mode is enabled, returned resources are marked with a SUBSETTED code to indicate that certain elements were left out:

Element selection

If none of the _summary modes listed above are appropriate for a use case, clients can select individual elements for inclusion via the _elements query parameter. Its value should be a comma-separated list of element names. Elements marked as "mandatory" are always returned.

As above, the returned resource's meta.tag element will also include a SUBSETTED Coding to indicate that some information has been left out.

Sorting and paging

Clients can indicate the preferred number of results to return on a single page via the _count query parameter. Paging via offsets is not supported, but the response usually includes a link of type "next" to retrieve the next page:

As can be seen from the example, the paging mechanism uses an additional state tracking parameter called _after.

Resource types

Snow Owl only supports a small subset of FHIR's 150+ resource types – the ones that are relevant from a terminology service perspective. These are described on separate pages in detail:

Resource identifiers

The id element of each resource is assigned by Snow Owl in create interactions; the assigned value never changes once it has been set and is unique across resource types. Update interactions that use an identifier which did not exist previously will create a new resource – in this case the identifier is checked for potential collisions first.

Snow Owl represents versioned content as standalone resources when accessed via the FHIR API (the version part is separated from the resource identifiers by a / character which is not allowed to be used in "regular" FHIR identifiers):

If there are no versions present for a given resource, or the requested identifier does not include a version part, the latest development version is returned which may include "in-progress" changes. Therefore it is recommended to always query a specific version of any terminology content to get consistent results, especially when the same terminology server instance is being used for both authoring and distribution.

Response status

The following HTTP status codes are used by Snow Owl's FHIR API to indicate the success or failure of an interaction:

If an error occurs, a response containing an OperationOutcome resource may be returned to include additional details about the problem at hand:

This section describes common information about all available native APIs.

Media Types

Custom media types are used in the API to let consumers choose the format of the data they wish to receive. This is done by adding one of the following types to the Accept header when you make a request. Media types are specific to resources, allowing them to change independently and support formats that other resources don’t.

The most basic media types the API supports are:

1. application/json (default)

2. text/plain;charset=UTF-8

3. text/csv;charset=UTF-8

4. application/octet-stream (for file downloads)

5. multipart/form-data (for file uploads)

We encourage you to explicitly set the accepted content type before sending your request.

Schema

All data is sent and received as JSON. Blank fields are omitted instead of being included as null.

Timestamps use the ISO 8601 format:

Effective time values used in SNOMED CT (and other terminology content as well) are sent and received in short format:

Hypermedia

An example Location header looks like this:

Pagination

Requests that return multiple items will be paginated to 50 items by default. You can request further pages with the searchAfter query parameter.

Resource expansion

Where applicable, the expand query parameter will include nested objects in the response, to avoid having to issue multiple requests to the server.

Expanded properties should be followed by parentheses and separated by commas; any options for the expanded property should be given within the parentheses, including properties to expand. Typical values for parameters are given in the "Implementation Notes" section of each endpoint.

Response:

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

Invalid JSON

Valid JSON but invalid representation

Conflicts

Server Errors

In certain circumstances, Snow Owl might fail to process and respond to a request and responds with a 500 Internal Server Error.

Path parameters

Snow Owl is a revision-based terminology server, where terminology data (concepts, descriptions, etc.) is stored in multiple revisions across multiple branches. When requesting content from the terminology server, clients can specify a path value or expression to select the content they'd like to access and receive.

For example, Snow Owl supports importing SNOMED CT content from different sources, allowing eg. multiple national Extensions to co-exist with the base International Edition provided by SNOMED International.

Versioned editions can be consulted when non-current representations of concepts need to be accessed. Concept authoring and review can also be done in isolation. Both Java and REST API endpoints require a path parameter to select the content (or substrate) the user wishes to work with.

The following formats are accepted:

Absolute branch path

Absolute branch path parameters start with MAIN and point to a branch in the backing terminology repository. In the following example, all concepts are considered to be part of the substrate that are on branch MAIN/2021-01-31/SNOMEDCT-UK-CL or any ancestor (ie. MAIN or MAIN/2021-01-31), unless they have been modified:

Relative branch path

Relative branch paths start with a short name identifying a SNOMED CT code system, and are relative to the code system's working branch. For example, if the working branch of code system SNOMEDCT-UK-CL is configured to MAIN/2021-01-31/SNOMEDCT-UK-CL, concepts visible on authoring task #100 can be retrieved using the following request:

An alternative request that uses an absolute path would be the following:

An important difference is that the relative path parameter tracks the working branch specified in the code system's settings, so requests using relative paths do not need to be adjusted when a code system is upgraded to a more recent International Edition.

Path range

The substrate represented by a path range consists of concepts that were created or modified between a starting and ending point, each identified by an absolute branch path (relative paths are not supported). The format of a path range is fromPath...toPath.

To retrieve concepts authored or edited following version 2020-08-05 of code system SNOMEDCT-UK-CL, the following path expression should be used:

The result set includes the ones appearing or changing between versions 2019-07-31 and 2021-01-31 of the International Edition; if this is not desired, additional constraints can be added to exclude them.

Path with timestamp

To refer to a branch state at a specific point in time, use the path@timestamp format. The timestamp is an integer value expressing the number of milliseconds since the UNIX epoch, 1970-01-01 00:00:00 UTC, and corresponds to "wall clock" time, not component effective time. As an example, if the SNOMED CT International version 2021-07-31 is imported on 2021-09-01 13:50:00 UTC, the following request to retrieve concepts will not include any new or changed concepts appearing in this release:

Both absolute and relative paths are supported in the path part of the expression.

Branch base point

Concept requests using a branch base point reflect the state of the branch at its beginning before any changes on it were made. The format of a base path is path^ (only absolute paths are supported):

Returned concepts include all additions and modifications made on SNOMEDCT-UK-CL's working branch, up to the point where task #101 starts; neither changes committed to the working branch after task #101, nor changes on task #101 itself are reflected in the result set.

Tooling support

Snow Owl TS differentiates between certain "families" (toolings) of code system resources. Each tooling uses an internal representation for its terminology components that can be searched and edited more effectively. These components are converted to a FHIR-compatible form when a read or search interaction happens, and back when new a CodeSystem resource is created via the FHIR API (or an existing resource receives an update).

SNOMED CT

SNOMED CT and its extensions are effectively read-only from the FHIR API's point of view – they can not be created via a create interaction, nor can content be loaded or updated from an RF2 archive. Only Snow Owl's native API has provisions for doing so.

SNOMED CT code system URLs follow the conventions described in the .

As SNOMED CT code systems contain a considerable amount of concepts, resource responses for this tooling do not include a concept array and content is always set to not-present to highlight this fact:

All SNOMED CT resources behave like editions, which means lookup operations succeed for any concept that can be found within eg. the International Edition's content, or in any other extension the resource depends on:

Filters

The following filters are supported in value set compose statements, should they reference a SNOMED CT code system:

• code: expression operator: = value: <ECL expression>

  • matches concepts using the Expression Constraint Language

• code: expressions operator: = value: <true|false>

  • specifies whether Post-Coordinated Expressions should be included in the filtered result set or not (even though the filter is recognized, Snow Owl currently does not store PCEs)

• code: concept operator: is-a value: <conceptId>

  • matches the descendants of the specified parent concept

• code: concept operator: in value: <refsetId>

  • matches concepts that are members of the specified reference set

Properties

All SNOMED CT relationship types are supported and can be returned along with concept data if requested. An example can be seen below:

• code: 288556008 (the attribute concept's ID) type: code URI: http://snomed.info/id/288556008 description: Before

In addition to these (and the common properties that are applicable to all code systems), Snow Owl can also return the following set of SNOMED CT-specific concept properties:

• code: inactive type: boolean URI: http://snomed.info/field/Concept.inactive

  • The concept's active RF2 property (inverted)

• code: moduleId type: code URI: http://snomed.info/field/Concept.moduleId

  • The concept's moduleId RF2 property

• code: effectiveTime type: string URI: http://snomed.info/field/Concept.effectiveTime

  • The concept's effectiveTime RF2 property (in yyyyMMdd format)

• code: sufficientlyDefined type: boolean URI: http://snomed.info/field/Concept.sufficientlyDefined

  • A boolean value derived from the concept's definitionStatusId (set to true if the original value is 900000000000073002|Defined|, false otherwise)

ICD-10 and its national variants can be imported from XML release files using the ClaML format in the paid edition of Snow Owl, however this functionality is not exposed via FHIR requests; neither can such a code system be created using a create interaction.

Similarly to SNOMED CT resources, the concept array remains unpopulated with content set to not-present in the response. ICD-10 concepts can still participate in lookup, validation or subsumption testing operations.

In the paid edition the official release archive can be used to populate the code system's contents. It is available over the FHIR API in a read-only fashion as the previous two toolings.

In Snow Owl's paid edition FHIR code system resources submitted as part of a create or update interaction (if no resource existed with the same ID earlier) become members of the LCS tooling. Custom properties may be defined when submitting the creation request and added to concepts of the code system.

The code system URL can be set upon creation and is checked for uniqueness.

The concept array is fully populated in LCS responses and content is set to complete.

Properties

User-defined properties listed in the top-level property elements of the resource get included in the LCS schema. The cardinality is set to [0..*], which means concepts can have any number of properties associated with the same type code.

Interactions

read (instance)

Standard GET requests that include the identifier as the final path segment(s) return the code system's current (or versioned) state:

update (instance)

PUT requests that include a resource identifier update an existing (local) code system or create a new instance:

The response code is 201 Created if the resource did not exist previously, and the URL is included in the Location response header. Existing code systems are updated and a 200 OK response is returned instead.

If an error occurs during the update, a 400 Bad Request response with an OperationOutcome resource as the response body is emitted instead.

The following non-standard request headers can be used to control certain aspects of the commit process:

• X-Effective-Date -> the effective date to use if a version identifier is present in the resource without a corresponding date element

• X-Author -> sets the user identifier that the commit should be attributed to (defaults to the authenticated user)

• X-Owner -> sets the owner of the resource, for access control purposes in external systems (defaults to the author or the authenticated user if the former is not set)

• X-Owner-Profile -> sets the human-readable name of the owner of the resource, for presentation purposes in external systems

• X-Bundle-Id -> specifies the parent bundle's resource identifier (defaults to the root bundle if not set)

delete (instance)

A DELETE request removes an existing code system:

Successful removal of a code system resource results in a 204 No Content response. Code systems that have been published can not be removed without adding the force=true query parameter to signal a forced deletion – this option in turn is only available to administrators.

create (type)

POST requests are very similar to the instance-level update interactions with the following important difference: the identifier included in the request body is ignored and a new, random one is generated from scratch. The request path should also omit the path segments corresponding to the resource identifier:

The response code is 201 Created if the interaction is successful. As mentioned above, the resource URL that can be used in eg. follow-up read interactions is included in the Location response header.

search (type)

GET requests targeting the endpoint corresponding to the resource type return all code systems that satisfy the specified search criteria, in the form of query parameters. The following example uses the count summary mode to determine the total number of code systems registered in the system, without returning any of the matches:

The following search parameters are supported:

• _id -> matches code systems by logical identifier

• name -> matches code systems by name (in Snow Owl this is set to the logical identifier)

• title -> matches code systems by title (Snow Owl uses exact, phrase and prefix matching during its lexical search activities)

• url -> matches code systems by their assigned url value

• version -> matches code systems by their version value

• status -> matches code systems by resource status (eg. draft, active, etc.)

Operations

$lookup

Both GET as well as POST HTTP methods are supported. Concepts are queried based on code, version, system or Coding. Designations are included as part of the response as well as supported concept properties when requested. Date parameters are not supported.

The following example request retrieves details about the SNOMED CT concept 128927009|Procedure by method|, including properties "inactive" and "Method" (a SNOMED CT attribute), using the latest version of the code system:

$validate-code

Both GET as well as POST HTTP methods are supported.

The example request below validates that 128927009|Procedure by method| is present in SNOMED CT, selecting the resource to use for validation using a versioned identifier (an instance-level invocation):

$subsumes

Both GET as well as POST HTTP methods are supported.

Subsumption testing is supported for all terminologies, including SNOMED CT. The example uses version 2022-02-28 of code system SNOMED CT (via the URL in the system query parameter) to determine whether 409822003|Domain Bacteria| is an ancestor of 112283007|Escherichia coli| (type-level invocation):

The response is positive (and encouraging). Changing the role of the two codes gives us a subsumed-by result instead.

Introduction

Snow Owl TS supports interactions and operations related to value sets, as described in the FHIR R5 specification. For certain toolings implicit value sets are also expandable; these are described below in detail.

Tooling support

SNOMED CT (implicit)

Value set URIs following SNOMED International's URI format are evaluated based on the associated SNOMED CT code system's content. The following URIs can be set as the url parameter of the request:

• http://snomed.info/sct/900000000000207008?fhir_vs - all concepts of the International Edition (may include a version suffix as well).

• http://snomed.info/sct/900000000000207008?fhir_vs=isa/409822003 - all concepts of the International Edition that are descendants of 409822003|Domain bacteria|

• http://snomed.info/sct/900000000000207008?fhir_vs=refset - all reference set identifier concepts in the International Edition

• http://snomed.info/sct/900000000000207008?fhir_vs=refset/733073007 - all concepts of the International Edition that are members of the reference set 733073007|OWL axiom reference set|

Persisted value sets

Regular value sets are only supported in the paid edition of Snow Owl.

Interactions

read (instance)

GET requests that include the value set identifier as the final path segment(s) return the resource state:

update (instance)

PUT requests that include a resource identifier will update an existing value set or create a new instance:

The response code is 201 Created if the resource did not exist previously, and the URL is included in the Location response header. Existing value sets (like in the example above) are updated and a 200 OK response is returned instead.

If an error occurs during the update, a 400 Bad Request response with an OperationOutcome resource as the response body is emitted instead.

The following non-standard request headers can be used to control certain aspects of the commit process:

• X-Effective-Date -> the effective date to use if a version identifier is present in the resource without a corresponding date element

• X-Author -> sets the user identifier that the commit should be attributed to (defaults to the authenticated user)

• X-Owner -> sets the owner of the resource, for access control purposes in external systems (defaults to the author or the authenticated user if the former is not set)

• X-Owner-Profile -> sets the human-readable name of the owner of the resource, for presentation purposes in external systems

• X-Bundle-Id -> specifies the parent bundle's resource identifier (defaults to the root bundle if not set)

delete (instance)

A DELETE request removes an existing value set:

Successful removal of a resource results in a 204 No Content response.

Value sets that have been published can not be removed without adding the force=true query parameter to signal a forced deletion (this option is only available to administrators however). The example value set was never published and so can be deleted without this option.

create (type)

In create interactions a POST request is sent to the path corresponding to the resource type. Any identifier included in the request body is ignored and a new, random one is generated from scratch.

The response code is 201 Created if the interaction is successful. The request URL that can be used in eg. follow-up read interactions is included in the response header named Location.

search (type)

GET requests with a request path that points to the resource type returns all value sets that satisfy the specified search criteria, in the form of query parameters. The following example uses the count summary mode to determine the number of draft value sets in the system, without returning any of the matches:

The following search parameters are supported:

• _id -> matches value sets by logical identifier

• name -> matches value sets by name (in Snow Owl this is set to the logical identifier)

• title -> matches value sets by title (Snow Owl uses exact, phrase and prefix matching during its lexical search activities)

• url -> matches value sets by their assigned url value

• version -> matches value sets by their version value

• status -> matches value sets by resource status (eg. draft, active, etc.)

Operations

$expand

Snow Owl supports the following input parameters for value set expansion:

• url -> the URI of the value set to expand (can be an implicit or an explicit one)

• valueSetVersion -> the version of the value set for use for the expansion

• activeOnly -> to return only active codes in the response

• filter -> to filter the results lexically

• includeDesignations -> whether to include all designations or not in the returned response

• displayLanguage -> to select the language for the returned display values

• count -> to select the number of codes to be returned in the expansion (10 by default)

• after -> state tracking parameter for concept set paging

The value set with expanded concepts is returned in entirety for this request. It includes a link that can be followed to retrieve the next page of expanded concepts:

$validate-code

The operation is supported both on the instance level (in this case the value set is located by resource ID) as well as the type level (a canonical URL must be supplied in the url input parameter to identify the value set to use).

Codes can only be validated against persisted value sets, not implicit ones.

Encountering any of the following conditions will fail the code validation check:

• The specified value set does not exist

• The value set does not contain the specified code in its expansion

• The code does not exist in the code system specified in the request (the corresponding parameter, system is mandatory in Snow Owl)

• The specified code system version differs from the version referenced by the value set

The following example checks whether 429885007|Bar| satisfies the aforementioned conditions in the value set containing all basic dose forms we created earlier:

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.

Compare two branches

POST /compare 
{
  "baseBranch": "MAIN",
  "compareBranch": "MAIN/a",
  "limit": 100
}

Response

Status: 200 OK
{
  "baseBranch": "MAIN",
  "compareBranch": "MAIN/a",
  "compareHeadTimestamp": 1567282434400,
  "newComponents": [],
  "changedComponents": ["138875005"],
  "deletedComponents": [],
  "totalNew": 0,
  "totalChanged": 1,
  "totalDeleted": 0
}

Read component state from comparison

Terminology components (and in fact any content) can be read from any point in time by using the special path expression: {branch}@{timestamp}. To get the state of a SNOMED CT Concept from the previous comparison on the compareBranch at the returned compareHeadTimestamp, you can use the following request:

Request

GET /snomedct/MAIN@1567282434400/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

To get the state of the same SNOMED CT Concept but on the base branch, you can use the following request:

Request

GET /snomedct/MAIN/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

Additionally, if required to compute what's changed on the component since the creation of the task, it is possible to get back the base version of the changed component by using another special path expression: {branch}^.

Request

GET /snomedct/MAIN/a^/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

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

1. Reference Sets category to get, search, create and modify reference sets

2. Reference Set Members category to get, search, create and modify reference set members

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

Actions API

On top of the basic operations, reference sets and members support actions. Actions have an action property to specify which action to execute, the rest of the JSON properties will be used as body for the Action.

Supported reference set actions are:

1. sync - synchronize all members of a query type reference set by executing their query and comparing the results with the current members of their referenced target reference set

Supported reference set member actions are:

1. create - create a reference set member (uses the same body as POST /members)

2. update - update a reference set member (uses the same body as PUT /members)

3. delete - delete a reference set member

4. sync - synchronize a single member by executing the query and comparing the results with the current members of the referenced target reference set

For example the following will sync a query type reference set member's referenced component with the result of the reevaluated member's ESCG query

POST /members/:id/actions
{
  "commitComment": "Sync member's target reference set",
  "action": "sync"
}

Bulk API

Members list of a single reference set can be modified by using the following bulk-like update endpoint:

PUT /:path/refsets/:id/members

Input

{
  "commitComment": "Updating members of my simple type reference set",
  "requests": [
  	{
  	  "action": "create|update|delete|sync",
  	  "action-specific-props": ...
  	}
  ]
}

The request body should contain the commitComment property and a request array. The request array must contain actions (see Actions API) that are enabled for the given set of reference set members. Member create actions can omit the referenceSetId parameter, those will use the one defined as path parameter in the URL. For example by using this endpoint you can create, update and delete members of a reference set at once in one single commit.

Snow Owl provides branching support for terminology repositories. In each repository there is an always existing and UP_TO_DATE branch called MAIN. The MAIN branch represents the latest working version of your terminology (similar to a master branch on GitHub).

You can create your own branches and create/edit/delete components and other resources on them. Branches are identified with their full path, which should always start with MAIN. For example the branch MAIN/a/b/c/d represents a branch under the parent MAIN/a/b/c with name d.

Later you can decide to either delete the branch or merge the branch back to its parent. To properly merge a branch back into its parent, sometimes it is required to rebase (synchronize) it first with its parent to get the latest changes. This can be decided via the state attribute of the branch, which represents the current state compared to its parent state.

Branch states

There are five different branch states available:

1. UP_TO_DATE - the branch is up-to-date with its parent there are no changes neither on the branch or on its parent

2. FORWARD - the branch has at least one commit while the parent is still unchanged. Merging a branch requires this state, otherwise it will return a HTTP 409 Conflict.

3. BEHIND - the parent of the branch has at least one commit while the branch is still unchanged. The branch can be safely rebased with its parent.

4. DIVERGED - both parent and branch have at least one commit. The branch must be rebased first before it can be safely merged back to its parent.

5. STALE - the branch is no longer in relation with its former parent, and should be deleted.

Basics

Get a branch

GET /branches/:path

Response

Status: 200 OK
{
  "name": "MAIN",
  "baseTimestamp": 1431957421204,
  "headTimestamp": 1431957421204,
  "deleted": false,
  "path": "MAIN",
  "state": "UP_TO_DATE"
}

Get all branches

GET /branches

Response

Status: 200 OK
{
  "items": [
    {
      "name": "MAIN",
      "baseTimestamp": 1431957421204,
      "headTimestamp": 1431957421204,
      "deleted": false,
      "path": "MAIN",
      "state": "UP_TO_DATE"
    }
  ]
}

Create a branch

POST /branches

Input

{
  "parent" : "MAIN",
  "name" : "branchName",
  "metadata": {}
}

Response

Status: 201 Created
Location: http://localhost:8080/snowowl/snomedct/branches/MAIN/branchName

Delete a branch

DELETE /branches/:path

Response

Status: 204 No content

Merging

Perform a merge

POST /merges

Input

{
  "source" : "MAIN/branchName",
  "target" : "MAIN"
}

Response

Status: 202 Accepted
Location: http://localhost:8080/snowowl/snomedct/merges/2f4d3b5b-3020-4e8e-b046-b8266967d7dc

Perform a rebase

POST /merges

Input

{
  "source" : "MAIN",
  "target" : "MAIN/branchName"
}

Response

Status: 202 Accepted
Location: http://localhost:8080/snowowl/snomedct/merges/c82c443d-f3f4-4409-9cdb-a744da336936

Monitor progress of a merge or rebase

GET /merges/c82c443d-f3f4-4409-9cdb-a744da336936

Response

{
  "id": "c82c443d-f3f4-4409-9cdb-a744da336936",
  "source": "MAIN",
  "target": "MAIN/branchName",
  "status": "COMPLETED",
  "scheduledDate": "2016-02-29T13:52:45Z",
  "startDate": "2016-02-29T13:52:45Z",
  "endDate": "2016-02-29T13:53:06Z"
}

Remove merge or rebase queue item

DELETE /merges/c82c443d-f3f4-4409-9cdb-a744da336936

Response

Status: 204 No content

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 Descriptions and Relationships, 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:

{
  "id": "138875005",
  "released": true,
  "active": true,
  "effectiveTime": "20020131",
  "moduleId": "900000000000207008",
  "iconId": "snomed_rt_ctv3",
  "definitionStatus": {
    "id": "900000000000074008"
  },
  "subclassDefinitionStatus": "NON_DISJOINT_SUBCLASSES",
  "ancestorIds": [],
  "parentIds": [
    "-1"
  ],
  "statedAncestorIds": [],
  "statedParentIds": [
    "-1"
  ],
  "definitionStatusId": "900000000000074008"
}

Properties

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

• id

• effectiveTime

• active

• moduleId

• definitionStatusId

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:

GET /snomedct/MAIN/concepts/425758004 // Diagnostic blood test
{
  [...]
  "ancestorIds": [
    "-1",        // Special value for taxonomy root
    "15220000",  // Laboratory test
    "71388002",  // Procedure
    "108252007", // Laboratory procedure (not pictured below)
    "128927009", // Procedure by method
    "138875005", // SNOMED CT Concept
    "362961001", // Procedure by intent
    "386053000"  // Evaluation procedure
  ],
  "parentIds": [
    "103693007", // Diagnostic procedure
    "396550006"  // Blood test
  ],
  [...]
}

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 hierarchy tag 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, environment_location, ethnic_group, event, finding, geographic_location, inactive_concept, intended_site, life_style, link_assertion, linkage_concept, medicinal_product, medicinal_product_form, metadata, morphologic_abnormality, namespace_concept, navigational_concept, observable_entity, occupation, organism, owl_metadata_concept, person, physical_force, physical_object, procedure, product, product_name, qualifier_value, racial_group, record_artifact, regime_therapy, release_characteristic, religion_philosophy, role, situation, snomed_rt_ctv3, social_concept, special_concept, specimen, staging_scale, state_of_matter, substance, supplier, transformation, tumor_staging, unit_of_presentation

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

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, expands can be nested, and the options will apply to the components returned under the parent property;

• when no expand options are given, an empty set of () parentheses need to be added after the property name.

Supported expandable property names are:

referenceSet()

Expands reference set metadata and content, available on identifier concepts.

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:

GET /snomedct/MAIN/concepts/900000000000497000?expand=referenceSet() // CTV3 simple map
{
  "id": "900000000000497000",
  "active": true,
  [...]
  "referenceSet": {
    "id": "900000000000497000",
    "released": true,
    "active": true,
    "effectiveTime": "20020131",
    "moduleId": "900000000000012004",
    "iconId": "900000000000496009",
    "type": "SIMPLE_MAP",                    // Reference set type
    "referencedComponentType": "concept",    // Referenced component type
    "mapTargetComponentType": "__UNKNOWN__"  // Map target component type
                                             // (applicable to map type reference sets only)
  },
  [...]
}

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

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

GET /snomedct/MAIN/concepts/900000000000497000?expand=referenceSet(expand(members()))
{
  "id": "900000000000497000",
  [...]
  "referenceSet": {
    [...]
    "type": "SIMPLE_MAP",
    "referencedComponentType": "concept",
    "mapTargetComponentType": "__UNKNOWN__",
    "members": {
      "items": [
        {
          "id": "00000193-e889-4d3f-b07f-e0f45eb77940",
          "released": true,
          "active": true,
          "effectiveTime": "20190131",
          "moduleId": "900000000000207008",
          "iconId": "776792002",
          "referencedComponent": {
            "id": "776792002"
          },
          "refsetId": "900000000000497000", // Reference set ID matches the identifier concept's ID
                                            // for all members of the reference set
          "referencedComponentId": "776792002",
          "mapTarget": "XV8E7"
        },
        [...]
      ],
      "searchAfter": "AoE_BTAwMDcyYWIzLWM5NDgtNTVhYy04MTBkLTlhOGNhMmU5YjQ5Yg==",
      "limit": 50,
      "total": 481508
    }
  },
}

Reference set members can also be fetched via the SNOMED CT Reference Set Member API.

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.

GET /snomedct/MAIN/2011-07-31/concepts/86299006?expand=preferredDescriptions()
{
  "id": "86299006", // Concept SCTID
  [...]
  "preferredDescriptions": {
    "items": [
      {
        "id": "828532012",                        // Description SCTID
        "term": "Tetralogy of Fallot (disorder)", // Description term
        "concept": {
          "id": "86299006"
        },
        "type": {
          "id": "900000000000003001"
        },
        "typeId": "900000000000003001",           // Type: Fully Specified Name
        "conceptId": "86299006",                  // "conceptId" matches the returned concept's SCTID
        "acceptability": {
          "900000000000509007": "PREFERRED",      // Acceptability in reference set "US English"
          "900000000000508004": "PREFERRED"       // Acceptability in reference set "GB English"
        }
      },
      {
        "id": "143123019",
        "term": "Tetralogy of Fallot",
        "concept": {
          "id": "86299006"
        },
        "type": {
          "id": "900000000000013009"
        },
        "typeId": "900000000000013009",           // Type: Synonym
        "conceptId": "86299006",
        "acceptability": {
          "900000000000509007": "PREFERRED",
          "900000000000508004": "PREFERRED"
        }
      }
    ],
    "limit": 2,
    "total": 2
  },
  [...]
}