ConceptMap API

The endpoints /ConceptMap and /ConceptMap/{conceptMapId} and corresponding operations expose the following types of terminology resources:

• SNOMED CT Simple Map Reference Sets with Concepts as referenced components

• SNOMED CT Complex Map Reference Sets

• SNOMED CT Extended Map Reference Sets

• Snow Owl's generic Concept Maps

$translate

All concept map accessible via the /ConceptMap endpoints are considered when retrieving mappings (translations). The translate request's source that designates the source value set cannot be interpreted hence not used. With the exception of SNOMED CT where the standard URI is expected, our proprietary short name or component ids are used to designate the source/target code system.

SNOMED CT:

• Simple Map Type Reference Set mappings are considered equivalent in terms of their correlation

• The availability and format of target code systems are not guaranteed, there is an ongoing conversation at SNOMED CT International to rectify this.

ValueSet API

The endpoints /ValueSet and /ValueSet/{valueSetId} and corresponding operations expose all Value Set resources stored (or implict Value Sets if the corresponding Value Set plug-in supports it) in the server. CUD operations are not supported.

$expand

All value sets accessible via the /ValueSet endpoints can be expanded.

For SNOMED CT URIs, implicit value sets are supported:

• ?fhir_vs - all Concept IDs in the edition/version. If the base URI is http://snomed.info/sct, this means all possible SNOMED CT concepts

• ?fhir_vs=isa/[sctid] - all concept IDs that are subsumed by the specified Concept.

• ?fhir_vs=refset - all concept ids that correspond to real references sets defined in the specified SNOMED CT edition

• ?fhir_vs=refset/[sctid] - all concept IDs in the specified reference set

The following in-parameters are supported:

• activeOnly - to return only active codes in the response

• filter - to filter the results lexically

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

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

• count - to select the number of codes to be returned in the expansion

• after - to select codes to be returned after this last page value (cursor)

$validate-code

Codes can be validated against a given Value Set specified by the value set's logical id or canonical URL. In terms of Snow Owl terminology components, codes are validated against:

• SNOMED CT Simple Type Reference Sets with Concepts as referenced components.

• SNOMED CT Query Type Reference Sets with ECL expressions (each member is a Value Set)

• Snow Owl's generic Value Sets

Validation performs the following checks:

• The existence of the given Value Set (error if not found)

• The existence of the reference in the existing Value Set to the given code (error if not found)

• The existence of the given code in the system (error if not found)

• Potential version mismatch (_error if the reference points to a version that is different to the code's version)

• The status of the given code and reference (warning if code is inactive while reference is active)

Code Systems maintained within Snow Owl are exposed (read-only) via the endpoints /CodeSystem and /CodeSystem/{codeSystemId}. Supported concept properties are handled and returned if requested. The currently exposed code systems are:

Snow Owl OSS:

• SNOMED CT

Snow Owl:

• ATC

• ICD-10 (and extensions)

• LOINC

• OPCS

• Local Code Systems

• Any other terminology

SNOMED CT

All standard and default SNOMED CT properties are supported, including the relationship type and concrete value properties. In addition to the FHIR SNOMED CT properties, Snow Owl can return the effective time property, with the URI http://snomed.info/field/Concept.effectiveTime.

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. No date parameter is supported.

Example for looking up properties (inactive and method) of the latest version of a SNOMED CT procedure by method code:

 /CodeSystem/$lookup?system=http://snomed.info/sct&code=128927009&_format=json&property=inactive&property=http://snomed.info/id/260686004

For SNOMED CT, all common and SNOMED CT properties are supported, including all active relationship types.

$validate-code

Both GET as well as POST HTTP methods are supported for all exposed terminologies. Example for validating a SNOMED CT code:

/CodeSystem/SNOMEDCT/2021-07-31/$validate-code?code=128927009

$subsumes

Both GET as well as POST HTTP methods are supported. Subsumption testing is supported for all terminologies, including SNOMED CT.

Example for SNOMED CT (version 2021-07-31):

/CodeSystem/$subsumes?codeA=409822003&codeB=264395009&system=http://snomed.info/sct/900000000000207008/version/20210731

FHIR API

Fast Healthcare Interoperability Resources (FHIR) specifies resources, operations, coded data types and terminologies that are used for representing and communicating coded, structured data in the FHIR core specification within its Terminology Module.

Snow Owl's pluggable and extensible architecture allows modular development of the FHIR API both in terms of the supported functionality as well as the exposed terminologies. Additionally, Snow Owl's revision-based model allows the concurrent management of multiple versions.

Resources

The Snow Owl terminology server's FHIR API release includes support for the following resources:

• CodeSystem API

• ValueSet API

• ConceptMap API

• Bundle API

• CapabilityStatement API

Versions

Versions in Snow Owl are represented as individual FHIR Resources when accessed via the FHIR API endpoints. If there are no versions present for a given resource, only the latest development version is returned as available FHIR Resource. When accessing a terminology resource via the FHIR API, but without specifying an exact version tag, then the system will always assume and return the latest development version, including not yet published changes. 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.

Search

Resource representations can be filtered by the following supported official FHIR payload filters:

• _summary - to return a predefined set of properties and their values

• _elements - to return only the mandatory and the specified list of properties and nothing else

The supported search parameters:

• _id - to filter FHIR resources by their logical identifier

• name - to filter FHIR resources by their name (which in Snow Owl equals to the logical identifier)

• title - to filter FHIR resources by their title property lexically (Snow Owl by default uses exact, phrase and prefix matching during its lexical search activities)

• url - to filter FHIR resources by their assigned url value

• system - to filter FHIR resources by their assigned system value (which in Snow Owl always matches the url value)

• version - to filter FHIR resource by their version property value

• _lastUpdated - exposed but not supported yet

Sorting and paging

Sorting supported via standard FHIR sort parameters, while paging is supported with a new after parameter (using count as page size). Offset + count based traditional paging is not supported.

URIs

Globally unique logical URIs that represent a terminology resource. For code systems these are:

SNOMED CT

For SNOMED CT, Snow Owl's FHIR implementation follows the SNOMED CT URI Standard.

ICD-10

For ICD-10, Snow Owl's FHIR implementation follows the HL7 FHIR Specification.

Local Code System

Snow Owl's Local Code Systems (LCS) identified by the URI that is based on the Organization Link property stored within Snow Owl's Terminology Registry and the Short Name of the LCS e.g.: https://b2i.sg/MyLocalCodeSystem.

IDs

The logical id field of each resource is assigned by Snow Owl and is unique within it. Once it has been assigned, the id never changes. For this logical identifier, Snow Owl follows the pattern:

resourceId[/version]

For example to identify a particular SNOMED CT Edition with its version 2021-03-01:

SNOMEDCT-US/2021-03-01

For example to identify a particular LOINC code system with the version tag v2.64:

 LOINC/v2.64

REST API

Currently only JSON format is supported with UTF-8 encoding and content type of Content-Type = application/fhir+json;charset=utf-8. In case of any errors during the processing the API responds with an OperationOutCome within the response body using one of the HTTP status codes:

Snow Owl's extension API

Snow Owl exposes a comprehensive REST API to support areas such as:

• Syndication - content provisioning between servers or between the Snow Owl Authoring platform and servers

• Administration (repository and revision control management)

• Auditing

• SNOMED CT specific browsing and authoring API