Terminology service providers should refer to the following sections of this guide for statements of requirements that their services should meet when accessing SNOMED CT:
Outlines user requirements for high-performance services that provide appropriate access to SNOMED CT.
Outlines requirements from the perspective of healthcare applications that consume terminology services.
Provides examples of practical use cases involving access to SNOMED CT that an application may need to complete. For each of these use cases, it identifies one or more of the required terminology services that can be used to complete the required activity.
Describes specific terminology services or functions that are required to enable effective use of SNOMED CT.
Clinical systems can be effectively implemented using a service oriented architecture, in which the terminology services are designed as an independent software component, accessible via an API (Application Programming Interface) gateway. This enables the other system components to access the key services without being affected by changes to the way these services are implemented.
When designing terminology services for SNOMED CT, it is important to utilize the sophisticated design features of the terminology, as this will support its effective use. When designing terminology services to support a range of different terminologies, it is important to consider the commonality between these terminologies. The table below summarizes some of the advantages and disadvantages of designing terminology services that only work with SNOMED CT, compared with designing services that can also enable access to terminologies or code systems. It also identifies advantages and disadvantages of supporting one or more interfaces through which applications can access SNOMED CT and/or other terminologies.
The following tables outline key design choices for terminology services, focusing on the types of terminologies supported and the interfaces provided. Each option includes potential advantages and disadvantages from the perspective of service design, helping organizations assess trade-offs between specialization, interoperability, and maintainability. These options can inform procurement decisions, integration strategies, and long-term terminology management planning.
Option
Notes
Option
Notes
Multiple interfaces
Example: Snowstorm supports both its native REST API and FHIR API.
✅ Advantage: Combines benefits of SNOMED-specific and general-purpose interfaces.
❌ Disadvantage: Increased maintenance burden; differences in behavior, performance, or output may exist between interfaces.
SNOMED CT only
A terminology service provider may develop and deliver services that are specific to SNOMED CT.
✅ Advantage: Services can be tailored to the structure and features of SNOMED CT.
❌ Disadvantage: May be less attractive to organizations seeking broader terminology support.
SNOMED CT and other code systems
A provider may support access to SNOMED CT along with other terminologies, code systems, or classifications.
✅ Advantage: Single solution for customers needing access to multiple terminologies.
❌ Disadvantage: Risk of underutilizing SNOMED CT-specific features.
Proprietary interface
A provider may define a custom interface to access SNOMED CT and/or other terminologies.
✅ Advantage: Interface can be optimized for specific service features.
❌ Disadvantages:
• Application providers may resist supporting multiple proprietary interfaces.
• Vendor lock-in risk makes switching providers difficult.
SNOMED CT-specific interface
Example: SNOMED International's Snowstorm API.
✅ Advantage: Allows services optimized for SNOMED CT features.
❌ Disadvantage: Requires app providers to use separate interfaces for other code systems.
General-purpose interface
Example: FHIR Terminology Service API.
✅ Advantages:
• Uniform interface for accessing multiple code systems.
• Easier to switch between service implementations.
❌ Disadvantage: May not support full optimization for SNOMED CT features.
Support for Different Terminologies and Interfaces
SNOMED CT is a clinically validated, semantically rich, controlled terminology. SNOMED CT is comprised of concepts with human-readable descriptions and a hierarchical structure supported by machine-readable logic-based definitions. SNOMED CT is used within electronic health records to support data capture, retrieval, and subsequent analysis and reuse for a range of purposes. The SNOMED CT design also includes features that support multilingual terms, subsets, maps to other codes systems, formal constraint specifications and comprehensive history tracking.
When implemented in software applications, SNOMED CT can represent clinically relevant information consistently, reliably and comprehensively as an integral part of electronic health records. This requires effective access to terminology content in ways that leverage the features of the terminology. A terminology service is a software function that interfaces with and provides access to information from one or more representations of a terminology.
Some services described in this guide are also applicable to other code systems, classifications and terminologies. However, delivery of the full set of benefits of SNOMED CT also requires terminology services that access and make effective use of features that are specific to SNOMED CT.
Purpose
The purpose of this document is to identify and describe the terminology services required to support effective access to the content and features of SNOMED CT. The guide also outlines approaches to delivery for some of the most important services. In some cases, more extensive details of service requirements and delivery options are provided by reference to other SNOMED CT documents or appendixes to this document. Where appropriate, this document may also include practical illustrations of a service by reference to specifications of existing tools or interfaces.
The content of this guide is primarily focused on the terminology service requirements of applications that enable the use of SNOMED CT for clinical purposes. This include electronic health record applications that enable entry, viewing, and reporting of clinical data. It also includes applications that support clinical data analytics and decision support. Some services and use cases mentioned in the guide are also relevant to terminology content authoring. However, it is important to note that the scope of this guide does not cover the full set of requirements for terminology development, authoring, and distribution services.
This guide is designed to be of value and interest to the following audience groups:
Consumers of SNOMED CT terminology services :
Procurers and implementers of healthcare applications
People involved in procuring and/or deploying applications that enable entry, viewing, reporting, and analysis of healthcare data coded using SNOMED CT
The needs of each of these audience groups vary, and as a result, the sections likely to be of most interests to each of these audience groups are noted in the Document Structure section below
This document is organized into five main chapters:
introduces the definition of SNOMED CT terminology services, it describes the general terminology service categories, and it presents three key roles with an interest in SNOMED CT terminology services and provides notes on issues relevant to each role.
outlines the practical use cases for terminology services.
describes the different types of terminology services required to enable effective use of SNOMED CT.
Terminology Data Storage and Access
SNOMED CT terminology data is distributed in release packages containing tab-delimited release files that conform to the . All release files follow a consistent design pattern with the following key features:
A versioning mechanism, which tracks additions, changes, and inactivations made in each release. This versioning mechanism enables terminology services to access the full history of every SNOMED CT component and reference set member.
A limited range of data types, all of which are rendered as text in release files.
Testers and evaluators of specific healthcare applications
End-users responsible for testing or evaluating applications that enable entry, viewing, reporting, and analysis of healthcare data coded using SNOMED CT
Providers of healthcare applications that use SNOMED CT:
People involved in designing, developing, or maintaining applications that enable entry, viewing, reporting, and analysis of healthcare data coded using SNOMED CT
Providers of SNOMED CT terminology services :
People involved in designing, developing, maintaining, or delivery of terminology services that include support of access to SNOMED CT
Service Implementation Considerations provides practical information regarding the use of the SNOMED CT release files to meet specific terminology service requirements.
Use of the Unicode UTF-8 character set for the string data type, to support the inclusion of the full range of Unicode characters.
Data from the files in SNOMED CT release packages needs to be loaded into a datastore that can be accessed by terminology services. The design of this datastore is a key design decision for developers of terminology services since it will determine the capabilities and performance characteristics of those services.
General requirements for the datastore design include:
It must enable the representation of all the information contained in all release files types in the SNOMED CT release package(s) imported
It must support the terminology services that are marked as Required in the subsections of Terminology Service Types
It must deliver scalable optimization of terminology services required by the use cases in Terminology Service Use Cases that the server is designed to support1.
Different technical options are available for implementing terminology services, for example, using a relational database, other database options (such as Graph databases), or using predefined services accessible via an API (for example SNOMED International's Snowstorm).
SNOMED CT terminology services can be subdivided into categories based on the following two defining characteristics:
Access requirements : Does the service need to update the terminology?
User interface requirements : Does the service include its own user interface controls?
Access Requirements
The following table describes the distinction between terminology services that provide read-only access to the terminology and those that also allow the terminology to be updated. Practical requirements for using SNOMED CT to enter, display, and report clinical data can be met by read-only terminology services. Services that are able to update the terminology are only required by those involved in the development, maintenance, or customization of the terminology.
Characteristic
Description
Additional Notes
The image below illustrates the association between the different types of terminology services and record services.
The table below differentiates between services based on whether the service includes user interface components, in addition to its application programming interface. Terminology services that do not include user interface components are capable of delivering a full range of essential terminology services but they require the client application to provide the user interface components to interact with those services. Terminology services that include user interface components have the potential to simplify client application development and configuration. Some examples of potentially beneficial terminology services with user interfaces are noted in the table below.
Section notes the need for combinations of the terminology services identified in to address each use case. Most of these use cases also need interfaces to allow users to interact and access the results of those services. However, the detailed specification of the user interface functionality of these combined services is beyond the scope of the current version of this guide.
Characteristic
Description
Additional Notes
The following tables provide examples of services in each of the four categories defined by applying the terminology access and user interface criteria.
User Interface
Examples
User Interface
Examples
Read-Only
Read-only terminology services enable access to SNOMED CT content and features.
These services meet requirements for practical use of SNOMED CT including collecting, displaying, communicating, and analyzing SNOMED CT coded data.
Add-Update
Add-update terminology services can add, modify, or inactivate SNOMED CT components and/or reference set members.
These services include functions that support terminology authoring, maintenance, and distribution.
A full suite of development services meets the requirements of organizations responsible for creating and maintaining a SNOMED CT edition, or a SNOMED CT extension containing additional clinical concepts.
Limited sets of development services can meet the requirements of organizations responsible for a SNOMED CT extension that consists only of reference sets representing subsets, maps, or data that is used to customize the terminology to meet specific purposes.
No UI
Terminology services that only provide access to SNOMED CT through an API.
Client applications using these services are responsible for providing any user interfaces required to enable practical use of these services.
Client-developed user interfaces can be closely integrated with the look and feel of the client application UI. They limit dependency on a specific terminology service provider, as services without a UI have less variability and are more likely to include shared, common features.
UI
Terminology services that, in addition to an API, also provide a user interface through which users can interact with the terminology.
Services in this category range from individual terminology-bound UI controls to fully functioning tools that enable viewing or editing the terminology.
User interface controls included as part of the terminology service may facilitate more rapid development and can be useful when client applications have limited requirements for SNOMED CT searching and display.
Examples:
• Terminology search control (Use Case 3.2 – Support EHR Data Entry):
– Text search with constraints set by data entry
– Display results to support selection of appropriate concepts
– Option to add postcoordinated refinements
• Report and analysis query development tool (Use Case 3.4 – EHR Reporting and Analytics):
– Enables creation of valid expression constraints or SNOMED CT queries
No UI
• Get details of a concept using its concept ID.
• Search for concepts based on term search criteria or expression constraints.
• Retrieve reference set data (e.g., subset membership, language acceptability, maps, history).
• Test if a set of concepts or expressions is subsumed by a specified concept or expression constraint.
UI
• SNOMED CT browser that allows exploration and supports API-based integration with applications.
• Terminology-bound UI controls (e.g., dropdown lists populated via reference sets or constraints).
• Tools to analyze records containing SNOMED CT-coded data.
No UI
• Create new SNOMED CT concepts.
• Add or modify axioms for defining concepts.
• Classify SNOMED CT content to infer relationships.
• Add descriptions to concepts.
• Inactivate concepts or descriptions.
• Create new reference sets of specific types.
• Add members to reference sets.
UI
• SNOMED CT authoring tools for creating concepts with full descriptions and axioms.
• Tools for maintaining subsets as reference sets.
• Translation tools to manage language-specific descriptions and acceptability settings.
• Mapping tools to develop and maintain crosswalks to other terminologies or code systems.
Terminology Access Requirements
User Interface Requirements
User Interface Inclusion
Terminology Service Category Examples
Read-Only Access
Add-Update Access
Many of the general use cases identified in can be met in different ways by different combinations of the terminology services detailed in with user interface components or forms. Therefore, detailed specifications of the specific functionality of combined terminology services would inevitably be either incomplete or overly restrictive.
Furthermore, user interfaces presented by a combined terminology service will typically need to be integrated with client applications. Client applications may adopt different user interface styles and these styles may evolve overtime. Therefore, flexibility in the design of the user interface through which a service is accessed may be preferable to a rigid detailed specification of each type of service.
Depending on feedback from readers, consideration will be given to providing more guidance on combined terminology services in future versions of this guide.
SNOMED CT is made available to license holders in release packages containing sets of files that represent SNOMED CT components and. The content of these files provides the source data to which a terminology service provides access. This chapter provides guidance on how the structure and content of different release packages should be accessed and used to enable desired services. This chapter is important for those designing, developing, and maintaining terminology services, as they require a thorough understanding of the structure and content of different release packages and the release files they contain.
This page is a placeholder for an identified advanced service requirement for which a definitive set of detailed requirements are not yet available.
The detailed requirements are under discussion and this page will be updated based on the outcome of those discussions.
Overview
An expression is a structured combination of one or more concept identifiers that represents an idea. Expressions can be used to represent concept definitions. They can also be used to represent meanings that are not currently represented by a concept in the current SNOMED CT release.
When expressions are used, it is necessary to determine whether the meaning of a particular expression is a subtype of a specified concept or more generally is subsumed by a particular expression constraint. The terminology services required are similar to those described for testing concepts in sections Get and Test Concept Subtypes and Supertypes and Validate and Apply Expression Constraints. However, in this case the first step is to determine the meaning of the expression relative to existing defined concepts.
Requirements and Options
The required services are listed in the table below.
Services Required
Service Name and Status
Input
Output
Use Cases
(if entry of post-coordinated expressions is supported)
(if stored data includes post-coordinated expressions)
Service Name
API Call 2
Result
Service Name
API Call 3
Result
Service Name
SQL Query 4
Result
Notes
Language and/or dialect should be specified if the service returns terms associated with referenced concepts.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of ().
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system . It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the . For instructions on how to build the example database refer to .
Test subsumption of an expression minimal
REQUIRED
...
...
...
...
...
Interdependencies
Required By
Depends On
Service Examples
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
The end users of SNOMED CT terminology services include healthcare professionals and other people who enter, view, report, and analyze healthcare data coded using SNOMED CT. Terminology services may sound like a technical matter of little interest to users but the quality and performance of these services can make a big difference to the usability of a healthcare application. Poorly implemented terminology services can make it hard to locate appropriate concepts, distracting, and frustrating health professionals as they struggle to enter notes. The end result is likely to be incomplete records or inaccurate recording due to the inability to find the correct concept. In contrast, well-designed terminology services used effectively by healthcare applications facilitate rapid and accurate entry of clinical data. This not only assists the delivery of patient care but also provides a valuable source of information for communication, reporting, and valuable analysis.
Terminology services that enable rapid searches for concepts in relevant areas of the SNOMED CT hierarchy are a key factor in facilitating accurate data entry and minimizing the risk of errors. When creating task-oriented forms or templates for data entry it is even more important to use search techniques that pinpoint the correct concepts, because any errors in a template will inevitably be duplicated by records created using that template.
Terminology services also need to support data retrieval for retrieval, analysis, and decision support. This requires terminology services that can examine the definition of a concept and determine if it meets the criteria specified in a query or expression constraint. A terminology service that supports rapid evaluation of these types of queries can be a key factor in facilitating the delivery of essential reports and valuable analytics.
Most end-users are unlikely to have a direct role in the development or selection of terminology services. However, those who are involved in designing, procuring, and implementing these services should recognize the importance of ensuring a positive end-user experience for people whose day-to-day work requires frequent access to SNOMED CT.
Organizations procuring applications that require access to SNOMED CT should carefully evaluate the way that the application provides access to terminology content and features. This evaluation should consider practical usability and also the flexibility of the underlying design. It should also consider the context of the existing technical architecture, as this will drive the type of service being procured.
To facilitate the assessment of the way an application interacts with SNOMED CT, the following steps are recommended:
Identify user activities that involve interaction with the terminology
It may be helpful to refer to the list of use cases in to assist the identification of specific activities that are relevant to the application being procured
Identify groups of users that regularly undertake each of the identified activities
Another important point to consider when procuring a solution that requires access to SNOMED CT. is the way (or ways) in which the solution provides access to the terminology. A solution may include built-in terminology services, it may provide an interface to terminology services from a specific provider, or it may offer options to use terminology services from different providers who support a common interface. The table below outlines the advantages and disadvantages of each of these options from the perspective of a procuring organization.
Option
Advantages for Procuring Organization
Disadvantages for Procuring Organization
Request representatives of the affected groups of users to assist with the evaluation of those activities
Those involved in this evaluation may find it useful to refer to the use cases in Terminology Service Use Cases and the specific service requirements which may suggest a particular factor underlying any issues they experience
Application uses terminology services provided by a specified third party
Application provider is responsible for maintaining compatibility of their application with the chosen terminology services interface
Potential for reuse of terminology services by other applications
Dependent on the quality of the specified terminology services and its future maintenance
Option for other applications to use the services is limited to those able to use the interface provided by the chosen terminology services
Risk of non-alignment between SNOMED CT editions/versions in terminology services used by different applications
Application supports use of terminology services that offer an interface that conforms to a publishedspecification
Application provider is responsible for maintaining compatibility of their application with the chosen terminology services interface
Choice of terminology services may allow reuse of terminology services already used in the organization
Choice of terminology services may allow migration to enhanced terminology services offered by a different provider
Possible differences in performance, functionality, and results between different implementations of a chosen terminology services interface
Separate support arrangement for terminology services may make responsibility for errors or performance issues less clear
Option for other applications to use the services may be limited by the chosen interface specification
Application configurable to support use of a specified range of terminology services
Application provider is responsible for maintaining compatibility of their application with the chosen terminology services interfaces
Choice of terminology services may allow the reuse of terminology services already used in the organization
Choice of terminology services may allow migration to enhanced terminology services offered by a different provider
Separate support arrangement for terminology services may make responsibility for errors or performance issues less clear
Option for other applications to use the services may be limited by the chosen interface specification
Application includes built-in functions for the terminology services it requires
Integrated solution without external dependencies
Potential for optimization of specific terminology services needed by the application
Single source for support
Dependent on the quality of the application provider's solution and its future maintenance
No option to select an enhanced set of terminology services from a specialist provider
Risk of non-alignment between SNOMED CT editions/versions in terminology services used by different applications
Application uses terminology services provided by the same organization but independent from the application
Purpose-built solution matched to the application
Single source for support
Potential for reuse of terminology services by other applications
Procurement
Evaluating the Usability of Terminology Services
Evaluating Application Options for Access to Terminology Services
Table: Options for Application Access to Terminology Services - Procuring Organization Perspective
Dependent on the quality of the application provider's terminology services and its future maintenance
No option to select an enhanced set of terminology services from a specialist provider
Option for other applications to use the services is limited to those able to use the interface provided by the application vendor
Terminology Services Overview
This chapter defines SNOMED CT terminology services, and it describes the general terminology service categories. Furthermore, it presents three key roles with an interest in SNOMED CT terminology services including end-users and those involved in the procurement of healthcare applications.
SNOMED CT terminology services are defined as a set of software functions that interface with and provide effective access to the content and features of one or more SNOMED CT editions.
Each terminology service is a software function that interfaces with and provides access to information from one or more representations of a terminology.
The software application that provides
Risk of non-alignment between SNOMED CT editions/versions in terminology services used by different applications
Future options for reuse of terminology services by other applications that support the same published interface specification
Future options to switch to another provider of terminology services that conform to the same published interface specification
Future options for the reuse of terminology services by other applications that support the same published interface specification
Future options to switch to another provider of terminology services that conform to the same published interface specification
SNOMED CT terminology services
is known as a SNOMED CT terminology server.
While terminology services may be applicable to several different terminologies, applications that provide SNOMED CT terminology services, should support access to the specific design features of SNOMED CT. These include the subtype hierarchy, description logic concept definitions, reference sets and expression constraints.
Find a concept based on a set of search criteria. The criteria may include text to be matched against terms associated with the concept and constraints requiring a concept to be a subtype of an identified concept or a member of an identified reference set.
Show the preferred term associated with an identified concept.
Support EHR Data Entry - Services needed for electronic health record data entry with SNOMED CT
- Services for displaying SNOMED CT concepts in EHR systems
- Services required for reporting and analytics using SNOMED CT
- Services for creating and editing SNOMED CT reference sets
- Services for applying mapping reference sets between code systems
- Services for managing terminology changes and versioning
- Services to support terminology authoring and review processes
Notes on the attributes used in the tables of this page:
*Status: Applications designed to address this use case must support the practical requirements marked as Required. Support for the practical requirements marked as Optional is recommended as these provide enhanced functionality that may be required by some users.
*Required Services: In most cases, a reference to a subsection of Terminology Service Types, implies a requirement for all services marked as Required in that subsection. However, where a reference is followed by a bulleted list, that list specifies the specific terminology services required. Some of the specific services listed as required for an Optional practical requirement may be marked as Recommended in the referenced subsection.
*Dependencies: This columns contains references to services on which a Required Terminology Service depends. This column does not restate dependencies on services listed as required service or additional dependencies for essential requirements listed in earlier rows.
A full list of the dependencies of each terminology service is provided in the relevant subsection of .
This section identifies three roles with an interest in SNOMED CT terminology services. The perspective of each of these roles is summarized with notes on general issues that those in particular roles should consider and references to relevant sections in the guide. The roles considered are as follows:
The Terminology Services Guide describes the terminology services required to support effective access to the content and features of SNOMED CT. This guide primarily focuses on the terminology service requirements of applications that enable the use of SNOMED CT for clinical purposes.
This document is a publication of International Health Terminology Standards Development Organisation, trading as SNOMED International. SNOMED International owns and maintains SNOMED CT®.
Any modification of this document (including without limitation the removal or modification of this notice) is prohibited without the express written permission of SNOMED International. This document may be subject to updates. Always use the latest version of this document published by SNOMED International. This can be viewed online and downloaded by following the links on the front page or cover of this document.
SNOMED®, SNOMED CT® and IHTSDO® are registered trademarks of International Health Terminology Standards Development Organisation. SNOMED CT® licensing information is available at . For more information about SNOMED International and SNOMED International Membership, please refer to or contact us at .
Two key factors determine the ability of an instance of a terminology server to provide access to a particular SNOMED CT versioned edition. Firstly, the data that forms part of that versioned edition must be loaded into a data store that the terminology service is able to access. Secondly, unless the terminology server only has access to one versioned edition, the terminology server must allow the edition and version to be specified by the client application (see Select Edition and Version).
The table below shows some of the different ways in which a terminology server may be designed and configured to enable access to a specific SNOMED CT edition or versioned edition Most of the options in the table require the client application to select the edition and version to which they require access.
Enabling Edition and Versioned Edition Access
Versioned Edition Accessibility
Description
Versioned Edition Selection
Notes
The current version(s) used by its client applications
The version(s) its client applications were using prior to their most recent updates.
Any versions of a single edition| A specific instance of a terminology server has access a datastore that contains the data required to access any version of a single edition.| Referring to a server instance implicitly identifies the edition.Any version of that edition can be selected by specifying the effective time for a snapshot.| Recommended for client applications that are processing, reporting, or analyzing data collected using a range of different versions of a single edition.
Specific versions of several editions| A specific instance of a terminology server accesses a datastore that only contains data for several specific versions of a several editions. The edition and version can be selected from those available.| Recommended for client applications that require access to multiple editions.
Any versions of several editions| A specific instance of a terminology server has access a datastore that contains data from the most recent full release for several editions. The edition can be selected from those available.Any version of the selected edition can be selected by specifying the effective time for a snapshot.| Recommended for client applications that are processing, reporting or analyzing data collected with using a range of different versions of more than one edition.
The table below summarizes the recommended ways to identify a SNOMED CT edition or versioned edition using a URI.
Method
Terminology Resource
General form and example
Notes
Apply Mapping Reference Sets
This section considers the terminology services required to apply a mapping reference set to map data between SNOMED CT and another code system.
A mapping reference set is a reference set designed to support the process of mapping data from one code system, classification, or terminology to another code system, classification, or terminology.
In practice, these terminology services only get the relevant mapping data for the source concept (or source code in the other code system). The relevant mapping data may be one or more rows from the mapping reference set. If there are no rows, this implies that there are no maps from the source code. Otherwise, the rows of returned mapping data must be parsed using the rules applicable to the particular map to determine the result. These rules are found in the mapping guide associated with the particular map or mapping reference set type. For example, the mapping rules for the SNOMED International ICD-10 map are documented in the .
The following table shows a summary of the services required to support effective use of a mapping reference set.
Example:
The {versionDate} is the effectiveTime of the set of module dependency reference set rows for this version of this edition. This is formally represented using the format YYYYMMDD (see Time data type).
Uniform Resource Identifiers
Edition
Example:
The SNOMED CT URI Standard defines globally unique identifiers for a wider range of terminology components. These URIs include the {moduleId} and {versionDate} noted above (see URI Standard section 2.1 URIs for Editions and Versions).
Note: The URI http://snomed.info/sct/731000124108/version/20200301 refers to the 2020-01-31 version of the US Edition, which is formally defined to include the 731000124108 | US National Library of Medicine maintained module | and the two International Edition modules on which it depends (900000000000207008 | SNOMED CT core module | and 900000000000012004 | SNOMED CT model component module |).
Versioned Edition
Examples:
—
Other Options
Edition
Key, path or alias for an edition
Example:
A less formal approach that provides a more meaningful representation of the edition and version can be used.
The example shown here is currently used by the Snowstorm terminology server to refer to the US Edition of SNOMED CT.
Note: This Snowstorm path refers to an extended version of the formally defined US edition. In addition to the formally defined content noted above, it also includes the 5991000124107 | SNOMED CT to ICD-10-CM rule-based mapping module | and several other additional modules distributed by SNOMED International in separate release packages. The inclusion of these additional extension modules creates an extended versioned edition (see 5.2.2 Enabling Access to Extended Editions).
Versioned Edition
Combination key, path, or alias with the version date
Example:
—
Fixed versioned edition
A specific instance of a terminology server accesses a datastore that only contains data for a single versioned edition.
Referring to a server instance implicitly identifies the edition and version.
Specific versions of a single edition
A specific instance of a terminology server accesses a datastore that only contains data for several specific versions of a single edition.
Referring to a server instance implicitly identifies the edition. The version can be selected from those available.
Recommended minimum for client applications only requiring access to a single edition.The accessible versions should include:
Module identifier and version date
Edition
{moduleId}
Example:
900000000000207008
The {moduleId} is an SCTID that identifies the edition. It does this by referring to the moduleId of the most dependent module in the edition. The other modules in the edition are specified by the module dependencies of that module.
Identifying SNOMED CT Editions and Versioned Editions
There are several types of mapping reference set each of these supports different types of mapping.
Simple Map from SNOMED CT Reference Sets and Simple Map to SNOMED CT Reference Sets support one-to-one maps from or to SNOMED CT.
Complex and Extended Map from SNOMED CT Reference Sets support maps where additional information is required to determine the correct mapping from SNOMED CT to a statistical classification such as ICD-10.
Maps which have a requirement to indicate the degree of correlation between a SNOMED CT concept and other codes. (See Map Reference Sets which use "correlation" within their type / name.)
Code to Expression Reference Sets support maps from other code systems in cases where some or all the source codes may need to be represented by a postcoordinated expression.
SNOMED International provides an online Mapping Tool that can be used to access maps that it distributes. This tool enables guests to view the maps (see https://mapping.ihtsdotools.org/).
When applying a mapping reference set it is important to note that most mapping reference sets are designed to be unidirectional and will not produce reliable results when used to map codes in the opposite direction.
This section identifies terminology services required to support the authoring and review of SNOMED CT content. This includes the creation and editing of concepts, descriptions, relationships, and reference sets. The terminology services described in this section are primarily used by terminology authors and reviewers working in terminology development environments. However, some of these services may also be used by applications that need to validate terminology content or provide terminology editing capabilities.
Services Required to Support Terminology Authoring and Review
The table below shows a summary of the terminology services required to support terminology authoring and review processes.
Practical Requirement
Required Services
Dependencies
Reference Set Editing
A reference set is a standard format for maintaining and distributing a set of references to SNOMED CT components.
The reference set mechanism provides a standard extensible mechanism that can be used to customize SNOMED CT to meet a wide range of practical use cases. Detailed information about reference sets is provided in the and in the
The table below shows a summary of the terminology services required to support reference set creation and editing.
Practical Requirement
Required Services
Dependencies
Appendix A: Summary of Types and Use Cases
This section summarizes the main types of terminology service requirements.
For each requirement type, typical use cases are identified, along with how terminology services are applied to those use cases.
Required Terminology Services
Use Cases
Application to Use Cases
EHR Reporting and Analytics
The design of SNOMED CT facilitates the use of a range of powerful reporting and analytic techniques. For more information about the applications of these techniques, please see the guide to . The same techniques can also be employed to support clinical decision support as described in the guide to Decision Support with SNOMED CT.
The table below shows a summary of the terminology services required to support reporting and analytics.
Practical Requirement
Required Services
Dependendies
Display EHR Data
Data stored in an electronic health record (EHR) that includes SNOMED CT concepts or expressions may also include a human readable term associated with each concept identifier. In this case, EHR data can be displayed without using any terminology services. However, as shown in the table below there are several situations in which it may be necessary to lookup and display a term rather than relying upon a term stored in the rec.
The table below shows a summary of the services required to support display of EHR data including looked up terms.
Reason
Notes
Terminology Service Types
This section describes services required to enable effective use of SNOMED CT. The guide does not mandate a particular way to meet these requirements. In some cases, a single terminology service API call may address several of the requirements identified in this section of the guide. In other cases, multiple API calls may be required to address a single requirement.
Enable the selection of SNOMED CT edition and version to be used.
REQUIRED
Note: The terminology services described in this section provide the foundation for terminology authoring and review. However, actual terminology editing applications typically require additional functionality beyond these services, such as:
User interface components for editing terminology content
Workflow management for authoring and review processes
Version control and change tracking
Integration with terminology classification engines
Export and import capabilities for terminology content
These additional capabilities are outside the scope of this guide and are typically provided by specialized terminology authoring tools.
- Explore and review SNOMED CT
- EHR data entry
- EHR data entry design
- EHR reporting and analytics
- Reference set editing
- Terminology authoring and review
Retrieve specified concepts to explore their descriptions, definitions, and hierarchy position; record data in an EHR; constrain UI templates; add concepts to reports or subsets; select attributes and values for authoring.
Get Terms for a Concept
- Explore and review SNOMED CT
- EHR data entry design
- EHR data entry
- Display EHR data
- Reporting and analytics
- Authoring and review
Display terms in search results, hierarchies, UI templates, EHR data displays, human-readable reports, and concept definitions.
Get Definition of a Concept
- Explore and review SNOMED CT
- Authoring and review
Display inferred definitions from relationships and stated definitions from OWL axioms. Show both in authoring environments.
Get and Test Concept Subtypes and Supertypes
- Explore and review SNOMED CT
- EHR data entry design
- EHR data entry
- Reporting and analytics
Display hierarchy views, apply subtype constraints in templates, constrain searches for entry, and apply subsumption tests in queries.
Get and Test Reference Set Membership
- EHR data entry design
- EHR data entry
- Reporting and analytics
- Reference set editing
Constrain searches by reference set membership, list reference set members for entry, and apply membership tests in queries and subset editing.
Validate and Apply Expression Constraints
- EHR data entry design
- EHR data entry
- Reporting and analytics
- Reference set editing
Apply expression constraints in templates, searches, reports, and analytics. Define subsets using intentional definitions.
Find Concepts
- Explore and review SNOMED CT
- EHR data entry
- EHR data entry design
- Reporting and analytics
- Authoring and review
Search for concepts to display, enter, include in templates, use in reports/queries, or define new concepts.
Identify Changes to the Terminology
- Terminology change management
- Manage impact of changes on EHR apps
- Manage impact on extensions
Identify added/changed/inactivated components, review inactive concepts in templates, records, and queries, and assess extension dependencies.
Get Data from a Reference Set
- Explore and review SNOMED CT
Retrieve acceptability of descriptions in language reference sets.
Get History Data
- Terminology change management
- Manage impact on EHR apps
- Manage impact on extensions
Identify inactivation reasons, retrieve replacements via historical associations, produce human-readable change reports, and support impact analysis.
Get Mapping Data
- Mapping data to/from another code system
Retrieve maps for concepts in a specified map reference set.
Get Concept Model Rules
- EHR data entry
- EHR data entry design
- Reporting and analytics
- Authoring and review
Constrain and validate refinements during data entry, NLP, template design, reporting queries, and concept definitions.
Validate Concept Definitions and Expressions
- EHR data entry
- EHR data entry design
Record and validate expressions when no single concept matches. Create templates that record expressions.
Test Expression Subsumption
- EHR data entry
- Reporting and analytics
Apply subsumption tests in queries and include subsumed or equivalent expressions in reports.
This guide primarily focuses on read-only terminology services without a user interface.
Applicable to all healthcare applications that require access to SNOMED CT.
Add-update services are only needed by those maintaining editions/extensions, which is a smaller audience.
Update services are interdependent and require complex version control and validation, making them unsuitable for generalized documentation here.
Detailed functionality of authoring tools is provided separately with those tools.
Services without a UI can be reused flexibly across different applications.
Applications can present SNOMED CT data in their own design styles while reusing the same terminology services.
UI-based terminology services are essentially composites of general services + UI components, with many possible combinations that cannot all be documented.
Instead, this guide notes general examples of binding terminology services to UI controls.
Enable the selection of SNOMED CT edition and version to be used.
REQUIRED
N/A
Get concepts or descriptions that are members of a reference set
In the case of a description, this includes the human-readable term for this refset member
REQUIRED
Get a description
N/A
Get terms for concepts to use in human-readable descriptions of:
The current reference set
Concepts that are members of a reference set
REQUIRED
N/A
Apply concept subsumption tests to identify candidate concepts for addition to or removal from a reference set.
REQUIRED
N/A
Apply reference set membership criteria to identify:
Current members of the reference set being edited
Candidate concepts for addition to or removal from a reference set
REQUIRED
N/A
Create and apply an expression constraint query:
as an intensional definition of reference set membership; or
to identify candidate concepts for addition to or removal from a reference set.
Get all concepts that conform to an expression constraint
N/A
Find concepts:
to find the id of a named reference set to be edited
to be added to or removed from a reference set; or
to be included in intensional definition of a reference set
REQUIRED
N/A
Get reference set member data (i.e. data of reference sets that extend on the simple type reference set, e.g. data from map type reference sets, association type reference sets etc.)
OPTIONAL
Enable the selection of SNOMED CT edition and version to be used.
REQUIRED
To display the preferred term or fully specified name of a concept in the following situations:
If a record entry contains a concept identifier without an associated term
It is good practice to store the selected term as well as the concept identifier but this is not mandatory.
If a communication contains a concept identifier without an associated term
It is good practice to communicate the selected term as well as the concept identifier but this is not mandatory. In some cases, the design of a message or interchange format may not support the inclusion of terms for all concept identifiers. This may be a particular issue when postcoordinated expressions are communicated as some interchange formats may not support the inclusion of terms for each concept identifier in an expression.
If the synonym in a record entry or communication is ambiguous
The term stored or communicated may be appropriate to the concept but may not be sufficiently clear.
For example, the term "fundus" is a valid synonym for four different concepts. Looking up the fully specified name for the concept identifier allows the display of term that removes this ambiguity.
To display the preferred term for a concept in a familiar language:
If the term stored or communicated is in an unfamiliar language
The term stored or communicated may be in a language that the user does not understand. If the concept is also included in the edition used by the viewer, it should be possible to display the term in the viewers own language.
To confirm that a term linked to a concept identifier is a valid:
If there is a requirement for quality assurance validation
Even when a term is stored or communicated with a concept identifier, it may be useful to confirm that the term included is associated with that concept identifier.
Practical Requirement
Required Services
Dependencies
Enable the selection of SNOMED CT edition and version to be used
REQUIRED
N/A
Display terms for the concepts in EHR record entries and communications
REQUIRED
Mapping is the process of converting data from one code system, classification, or terminology to another code system, classification, or terminology.
Notes
The mapping process includes the preparation and maintenance of resources used for converting data.
SNOMED CT mapping resources are distributed as mapping reference sets.
The SNOMED CT reference set design provides a common foundation on which mapping resources that meet different requirements can be built. The guidance in this section relates to the general approaches to accessing data in a mapping reference set. The table below provides reference to specific mapping reference set types and supporting documentation related to the use of those reference sets.
Map type
Description
Reference Set File Format
Terminology services should be able to provide access to sets of maps based either on the SNOMED CT concept or a code from the other code system.
The concept involved in the map is represented by the referencedComponentId. As noted in , access to reference set data using a combination of refsetId and referencedComponentId is a general requirement.
The other code is generally in a column referred to as mapTarget1. Support for access to maps using a combination of refsetId and mapTarget is therefore also required.
The required services are listed in the table below. Additional requirements should be considered for cases where the map refers to an expression rather than a single concept.
The services described in this section are limited to accessing the relevant map data. In simple cases, this may be sufficient to enable mapping. However, in other cases the services will provide client applications with options to display to the user and/or processable rules to be tested against other data to determine the appropriate map.
Service Name and Status
Input
Output
Use Cases
Service Name
API Call
Result
Service Name
API Call
Result
Service Name
SQL Query
Result
Find Concepts
Overview
Finding a specific concept is a fundamental requirement and a prerequisite for most other terminology service. To make practical use of SNOMED CT, users must be able search for concepts using using phrases, words or parts of words. The SNOMED CT Search and Data Entry Guide provides detailed descriptions of these essential search types. It also notes a range of important additional features that facilitate appropriate use of the terminology by constraining searches and appropriately ordering search results. This section does not repeat that detailed discussion of different search techniques. Instead, it focuses on technical and practical requirements for delivering and accessing services that meet those requirements.
Several services described earlier in the guide provide technical ways to constrain searches for concepts to meet particular requirements.
includes consideration of services that find concepts based on subtype relationships to or from other concepts.
includes services that find concepts that are members of a particular reference set.
describes the way that the above approaches to finding concepts can be combined.
This section indicates ways in which term searches can and should be combined with those constraints to enable effective searches for concepts relevant to a particular context of use.
High-performance term search services are essential for most practical applications of SNOMED CT. Search services also need to employ effective strategies for rationalizing, sorting and presenting search results in ways that facilitate selection of concepts most frequently used in a given context of use. Term searches are typically language or dialect specific. Therefore requests for searches should include appropriate language codes or language reference set identifiers2.
Section in the Search and Data Entry Guide identifies a range of different search techniques that may be valuable. If a terminology server supports more than on search technique the service request will need to indicate the technique to be used.
In the simplest case a term search service should be able to take a term or phrase typed by a user and return matching results. For this purpose, the recommended default search technique is to search for words or parts of words in any order (see Search and Data Entry Guide ). Searches using this technique should be to return concepts associated with terms that include words that match or begin with all the words or part words in the search string. The order of words need not be the same in the search string and the matched term and the search string need not include all the words in the term.
Specific data storage and development environments also support specific solutions for searching text. These include boolean searches (which require some words to be present and other words to be absent, natural language searches which may include words with similar meanings. In addition to these there are more general pattern matching approaches including the use of wildcard character and searches using regular expressions. While these techniques can be useful, end users should be able to search SNOMED CT effectively without being required to understand a specific technical syntax.
Section in the Search and Data Entry Guide identifies a range of options for filtering and ordering the results of a search. Filtering options include avoiding displaying multiple matching terms that refer to the same concept as well as ensuring that by default descriptions associated with inactive concept are not displayed (though there should be an option to include inactive concepts as these may be relevant to historical data). Ordering options include displaying the closest matches, shortest matching terms or most commonly used concepts at the top of the list of results.
Many practical use cases are best addressed by applying term searches to a constrained set of concepts. Searches that are appropriately constrained result in shorter lists of matching results and thus make it easier for a user to find the required concept. Constrained searches also reduce the risk of inadvertently selecting a concept in a hierarchy that is not appropriate to the data entry context. Thus this technique simplifies data entry and leads to improvements in data quality.
Example
Searching the entire content of SNOMED CT when looking for a diagnosis or reason for admission is likely to include many concepts that are are not valid diagnoses or reasons for admission. This can make if difficult for the user to find the concept that they need and, in some case, may lead to recording of concepts that have terms that do not represent the intended meaning. Examples of errors arising from failing to constrain searches include recording the names of substances and morphological abnormality rather than the name of symptom or disorder. The results of such errors can result in errors in reporting, analysis and decision support even in cases where the selected term may appear to capture the required meaning.
The recommended approach to constrained searches is to use expression constraints to specify the constraints. Ideally, the service should implement all the features of (ECL). However, even if the service does not support some of the more advanced features, it should enable use of ECL to represent and combine subtype tests and reference set membership tests.
Services that do not support ECL should as a minimum support constraints based on reference set membership and the position of the concept in the subtype hierarchy. The recommended approach to testing the location of a concept in the hierarchy is the use of subtype tests. However, if these tests are not supported, a more limited approach that filters search results by hierarchy tags may be used.
Service Name and Status
Input
Output
Other Services
Use Cases
Service Name
API Call
Result
Service Name
API Call
Result
Service Name
SQL Query 9
Result
Notes
It should never be necessary for an end-user to enter a concept identifier. However, there are practical situations in which concept identifiers may be available to be used to find a specific concept or set of concepts. These situations include coded data in existing records or messages; templates, pick lists and other user interface controls that are bound to specific concept identifiers. If concept identifiers are available they provide a direct way to find data about specific concepts.
One or more languages and/or dialects should be specified for searches. If more than one language or dialect is specified, the search should return matching terms that are acceptable in any specified language or dialect.
The nature of the search string may vary according the search techniques supported and any options selected (see ).
The search technique needs to be specified if the service supports different techniques (see ).
If the service supports alternative ways of filtering or ordering results, these options chosen need to be specified (see ).
As noted in , the use of expression constraints is recommended. However, other representations of constraints may be used if the service does not support expression constraint language.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of ().
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system. It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the . For instructions on how to build the example database refer to .
Appendix C - Videos
This playlist brings together all videos on searching and data capture using SNOMED CT from the SNOMED International Implementation Course. The videos introduce key concepts, practical implementation considerations, and real-world examples to help you understand how SNOMED CT can be applied to support terminology services.
If you would like the full e-learning experience, you can enroll in the , which is self-paced and allows you to mix and match topics of interest. The course is free for participants from SNOMED International Member countries.
How to navigate the playlist in GitBook
When a YouTube playlist is embedded in GitBook, only one video is shown on the page at a time, but all playlist videos are still available.
Use the forward () and back () arrows on the video player to move between videos in the playlist
Get Data from a Reference Set
Reference set files provide a standard format for maintaining and distributing a set of references to SNOMED CT components.
A reference set can be used to represent a subset of components (concepts, descriptions or relationships).
A reference set may also associate referenced components with additional information such as:
Healthcare Application Providers
Application providers should refer to the following sections of this guide for statements of terminology service requirements that need to be met for effective access to SNOMED CT.
Which notes user requirements for high performance services that provide appropriate access to SNOMED CT.
Appendix B: Editions, Versions and Extensions
This appendix explains the different types of SNOMED CT editions, versions, and extensions.
It also outlines the requirements for terminology services and applications that use them.
Terminology service providers must deliver services that can load data from SNOMED CT release packages that conform to the Release File Specifications.
They must enable client applications to access the content of a selected SNOMED CT versioned edition.
Maps including additional data to represent attribute-value combinations, correlation and source of original code
Supports maps where some codes in the other code system represent a combination of and attribute with a value (e.g. finding site appendix). Also supports maps where the correlation between source and target needs to be specified and where there are intellectual property reasons for recording that either the SNOMED CT or other code were the original representations of the mapped meaning.
Map to SNOMED CT with Correlation and Origin Reference Set
Maps to SNOMED CT expressions
Supports maps from another code systems where the use of a SNOMED CT expression may capture the meaning of that code more accurately than can be achieved with a single concept.
Code to Expression Reference Set
Get maps based on combinations of refsetId,referencedComponentIdand mapTarget
Identifier of concept
Other code
Edition and version
All map data associated with maps in the specified reference set in which the referencedComponentId matches the specified concept identifier and the mapTarget matches the other code.
Property
Description
mapGroup
An integer grouping a set of maps. One map should be chosen from each group.
mapPriority
The order in which map within a group should be checked.
mapRule
A machine-readable rule, that determines if a map applies.
mapAdvice
Advice to assist manual selection map from a group.
mapTarget
The target code from the other coding scheme (if this map is chosen based on the rule or advice).
correlationId
|Representing the correlation between the concept and the target code.
mapCategoryId
Represents the map category that applies to this map.
Get maps based on combinations of refsetId and mapTarget
Example 6. Map from ICD-O code "8090/3" to SNOMED CT concepts
Encoded URL
Example 7. Maps from NHS Clinical Terms to a SNOMED CT concept
Encoded URL
Returns a JSON representation of the data in active rows in the specified mapping reference set with a mapTarget that matches the specified otherCode. This returns the same data as noted above.
Example 6. Reverses the map shown in example 1. In this case it returns records showing several concepts that map to the this ICD-O code. As these are simple map with no rules, this result indicates that all these concepts map to the same less specific ICD-O code.
Example 7 . Maps from NHS CTV3 codes (previously used in the UK) to SNOMED CT concepts. In this case the map returns a single map from any specified CTV3 code to the closes matching SNOMED CT concept.
Warning
The ICD-10 map is a unidirectional map from SNOMED CT concept to ICD-10 codes. The mapGroup, mapPriority, mapRule, mapAdvice and mapCategoryId properties of complex and extended apply to the set of maps from a SNOMED CT concept to a mapTarget. These rules cannot be interpreted if maps are accessed for specified targetCode. Therefore, this service should not be used to access maps of this type.
Get mapsbased on combinations of refsetId, referencedComponentId and mapTarget
Example 8. Finds any maps from to ICD-10 code S06.90
Encoded URL
Returns a JSON representation of the data in active rows in the specified mapping reference set with a referencedComponentId that matches the specified conceptId and a mapTarget that matches the specified code from the other code system.
Example 8 . Could be used either or both of the following:
Test if there is a map between the SNOMED CT concept "Closed skull fracture with intracranial injury" and the ICD-10 code S06.9 "Unspecified intracranial injury".
Provide access to the associated mapping rule, advice and correlation data for any maps between these two codes.
mapAdvice
Advice to assist manual selection map from a group.
mapTarget
The target code from the other coding scheme (if this map is chosen based on the rule or advice).
correlationId
|Representing the correlation between the concept and the target code.
mapCategoryId
Represents the map category that applies to this map.
Get maps based on combinations of refsetId, referencedComponentId and mapTarget
Example 8. Finds any maps from to ICD-10 code S06.90
Example 9. Finds any maps from to ICD-10 codes in the S06 chapter
Returns rows of data from the specified mapping reference set with a referencedComponentId that matches the specified conceptId and a mapTarget that matches the specified code in the other code system.
Example 9. provides an additional option, which may be useful code systems such as ICD-10 in which part of the code represents represent chapters or subdivision. It allows a search for a map from a concept to any code in a specified chapter.
Simple map
Supports one to one maps to or from another code system
Simple Map Reference Set
ICD classification maps
Supports maps from SNOMED CT to ICD-10 classifications. Enables mapping to different codes based on rules and priorities. Also allows maps from a single code to combinations of codes.
Get maps based on combinations of refsetId and referencedComponentId
Identifier of concept to be mapped to target scheme
Edition and version Reference set identifier
Optional: Language/dialect2
All map data associated with maps in the specified reference set in which the referencedComponentId matches the specified concept identifier.
Gets maps from SNOMED CT to another code system, if the map data supports mapping in that direction.
Get maps based on combinations of refsetId and mapTarget
Other code to be mapped to SNOMED CT.
Edition and version
Reference set identifier
Optional: Language/dialect2
All map data associated with maps in the specified reference set in which the mapTarget matches the specified other code.
Gets maps from SNOMED CT to another code system, if the map data supports mapping in that direction.
Get maps based on combinations of refsetId and referencedComponentId
GET [snowstorm]/[branchPath]/members?referenceSet=[refsetid]&referencedComponentId=[conceptId]&active=true
GET [snowstorm]/MAIN/2020-01-31/members?referenceSet=447562003&referencedComponentId=32398004&active=true
Encoded URL
Example 5. ICD-10 Map for
Returns a JSON representation of the data in active rows in the specified mapping reference set with a referencedComponentId that matches the specified conceptId.
The examples illustrate the following pointsExample 1. A concept that maps to a single ICD-O code in a simple map refset.
Example 2. A concept that maps to a single ICD-10 classification code in a complex/extended map refset.
Example 3. A concept that maps to a combination of two classification codes (there are two map groups and each contains a single map row with priority 1)
Example 4. A concept that has a single map group containing two rows. The row with priority 1 has a rule that requires the patient age to be less than or equal to 15 years. If that rule is not matched the row with map priority 2 applies as it contains the rule "OTHERWISE".
Example 5. A concept that, like example 2, contains two map groups. However, in the case it each of those maps also include specific human readable advice "... MAPPED FOLLOWING WHO GUIDANCE | POSSIBLE REQUIREMENT FOR AN EXTERNAL CAUSE CODE"
The data returned for each refset member of an extended map (e.g. as used in examples 2-5) includes the following mapping data as subproperties of the additionalFields property:
Property
Description
mapGroup
An integer grouping a set of maps. One map should be chosen from each group.
mapPriority
The order in which map within a group should be checked.
mapRule
A machine-readable rule, that determines if a map applies.
Get maps based on combinations of refsetId and referencedComponentId
GET [fhir]/ConceptMap/$translate?code=[componentId] &system=http://snomed.info/sct&source=[sourceCodeSystem]?fhir_vs&target=[sourceCodeSystem]&url=[version]?fhir_cm=[refesetId]
GET [fhir]/ConceptMap/$translate?code=1338007&system=http://snomed.info/sct &source=http://snomed.info/sct?fhir_vs &target=http://snomed.info/sct?fhir_vs &url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_cm=446608001
Encoded URL
GET [fhir]/ConceptMap/$translate?code=1338007&system=http%3A%2F%2Fsnomed.info%2Fsct+&source=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs+&target=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs+&url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_cm%3D446608001%0A
GET [fhir]/ConceptMap/$translate?code=74400008&system=http://snomed.info/sct&source=http://snomed.info/sct?fhir_vs &target=http://hl7.org/fhir/sid/icd-10&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_cm=447562003
Encoded URL
GET [fhir]/ConceptMap/$translate?code=74400008&system=http://snomed.info/sct&source=http://snomed.info/sct?fhir_vs &target=http://hl7.org/fhir/sid/icd-10&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_cm=447562003
GET [fhir]/ConceptMap/$translate?code=196607008&system=http://snomed.info/sct&source=http://snomed.info/sct?fhir_vs &target=http://hl7.org/fhir/sid/icd-10&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_cm=447562003
Encoded URL
GET [fhir]/ConceptMap/$translate?code=196607008&system=http%3A%2F%2Fsnomed.info%2Fsct&source=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs+&target=http%3A%2F%2Fhl7.org%2Ffhir%2Fsid%2Ficd-10&url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_cm%3D447562003
GET [fhir]/ConceptMap/$translate?code=32398004&system=http://snomed.info/sct&source=http://snomed.info/sct?fhir_vs &target=http://hl7.org/fhir/sid/icd-10&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_cm=447562003
Encoded URL
Returns a JSON representation of data about each of the target components.
The data returned for each concept includes:
boolean: True if the concept could be translated successfully. The value can only be true if at least one returned match
match: Each match represents data for the map or associated target. Note that there may be multiple matches, where each element represents a mapTarget. For each mapTarget, following data is provided
system: the codesystem of the mapTarget
code: The identifier of the mapTarget
Request response
Be aware that the FHIR TS API only provides information about the mapTarget. However, no additional map data represented in the map reference set is provided. This service is therefore sufficient to represent simple maps, but data required to interpret complex maps is not made available.
Example1. A concept that maps to a single ICD-O code in a simple map refset.
Example 2. A concept that maps to a single ICD-10 classification code in a complex/extended map refset.
Example 3. A concept that maps to a combination of two classification codes (there are two map groups and each contains a single map row with priority 1)
Example 4. A concept that has a single map group containing two rows. For this map, a rule will determine which target should be chosen. Please note that the response does not show the rules as they are stated in the map reference set.
Get maps based on combinations of refsetId and mapTarget
N/A
The FHIR TS API does not support retrieval of map data based on a specific mapTarget
Get maps based on combinations of refsetId and referencedComponentId
SELECT * FROM snap_refset_extendedmap WHERE active=1 AND refsetId=[refsetId] AND referencedComponentId=[conceptId];
SELECT * FROM snap_refset_extendedmap WHERE active=1 AND refsetId=447562003 AND referencedComponentId=111613008;
Alternative approach using a stored procedure. This does not require the specific map reference set type to be identified.
-- Alternative that also shows the terms associated-- with identifiers in the map records
CALL snap_members([refsetId],[conceptId]);
Returns rows of data from the specified mapping reference set with a referencedComponentId that matches the specified conceptId.
Get maps based on combinations of refsetId and mapTarget
SELECT * FROM snap_refset_extendedmap WHERE active=1 AND refsetId=[refsetId] AND mapTarget=[otherCode];
Example 6. Map from ICD-O code "8090/3" to SNOMED CT concepts
SELECT * FROM snap_refset_extendedmap WHERE active=1 AND refsetId=446608001 AND mapTarget="8090/3";
Example 7. Maps from NHS Clinical Terms to a SNOMED CT concept
SELECT * FROM snap_refset_extendedmap WHERE active=1 AND refsetId=900000000000497000 AND mapTarget="Xa9C4";
Returns rows of data from the specified mapping reference set with a mapTarget that matches the specified code in the other code system.
Map Reference Sets and Documentation
Requirements and Options
Required Services
Interdependencies
Required By
Depends On
Service Examples
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see IETF RFC1738).
Search filtering or sorting options (if supported)
A collection of matching terms each of which is linked to the appropriate concept.
Find concepts by constrained term search
Edition and version
Language code(s)
Search string
Search technique option (if required)
Search filtering or sorting options (if supported)
An expression constraint
A collection of matching terms that are applicable to concepts that conform to the specified constraints. Each term must be linked to the appropriate concept.
Find concepts by term search
GET [snowstorm]/snomed-ct/[branchPath]/concepts?activeFilter=true&term=[search-string]
Example 1
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=knee
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&term=knee
Example 2.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=alcohol
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&term=alcohol
Example 3.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=ren ston
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&term=ren+ston
Returns a JSON representation of data related to the concepts that have terms that match the search string.
Also returns the total number of concepts that match the search string.
As some searches are matched by large numbers of concepts, this service is paged. Requests parameters include:
limit to restrict the number of concepts returned (default 50).
offset to specify the start in the results (in multiples of the limit).
The results of the searches shown when applied to the 2020-01-31 International Edition were as follows:
Example 1 returns the first 50 concept that match the search term "knee". It also return a total value of 1387 indicating that there are 1337 more matches that could be shown. If the word "x-ray" is added to the search term, this reduces the number of matches to 8. This is an example of how an additional term can provide refinement for a particular context of use. However, this does not necessarily include all radiographic procedures on the knee - for example "Computed tomography of knee" will not match.
Example 2 returns the first 50 of 509 matches for the search term "alcohol". Of the first 50 concepts shown most related relate to the substance alcohol (26) and only 11 relate to disorders and findings.
Example 3
In all the above examples adding another word or two greatly reduces the results returned and reduces the distribution of the results across multiple hierarchies. However, when entering data for a given purpose it makes sense to limit the search results to concepts that can sensibly be applied to those contexts.
Find concepts by constrained term search
GET [snowstorm]/snomed-ct/[branchPath]/concepts?activeFilter=true&term=[search-string]&ecl=[expressionConstraint]
Example 4.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&ecl=<363680008|Radiographic imaging procedure|&term=knee
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&amp;ecl=%3C363680008%7CRadiographic+imaging+procedure%7C&term=knee
Example 5.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=alcohol&ecl=<64572001|Disease|
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&amp;term=alcohol&ecl=%3C64572001%7CDisease%7C
Example 6.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=alcohol&ecl=<64572001|Disease| and ^450970008| General Practice / Family Practice reference set|
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&amp;term=alcohol&ecl=%3C64572001%7CDisease%7C+and+%5E450970008%7C+General+Practice+%2F+Family+Practice+reference+set%7C%0A
Example 7.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=ren ston&ecl=<64572001|Disease|
Encoded URL
Constrained searches return JSON data for each of the matches in the same way as described above for the unconstrained searches.
Example 4 provides an example of how a search for x-ray procedures can be constrained so it is only necessary to enter the site and other related details. In this case the search term "knee" returns 40 matches. These include concepts such as "computed tomography of knee" which do not match "knee x-ray". The same constraint would simplifies all searches for radiology procedures and the constraint could also relaxed to include all imaging procedures.
Examples 5 and 6 provide an examples of how a search for a reason for admission might be constrained. In example 5 the constraint to disease restricts searches for alcohol or other drugs to concepts in the disorder hierarchy. This reduces the count of matches to 148. In example 6 a further constraint is added requiring the concept to be in the "General Practice / Family Practice reference set". The result of this is that only 21 matching concepts are returned. It is important to note that this is only an example, for practical in different clinical environments more specific reference sets should be considered.
Example 7 restricts the "ren ston" search to subtypes of disease and result in only 2 matches, which is a worryingly low number because there are certainly more SNOMED CT concepts that represent different disorders involving renal stones. The problem here is that many of the concepts do not have terms that match the search string. Instead, most related concepts use synonymous terms like "renal calculus" or "kidney stone".
A useful option to allow the user to deal with this situation is for the client application to provide users with the option to expand the results to include the subtype children or descendants of the matching concepts. In the case illustrated by example 7, this option would return 18 additional concepts (subtype descendants of 95570007|Kidney stone| that did not match the search term.
Find concepts by term search
In FHIR, the ValueSet/$expand operation may be used to search within a specified collection of codes.
A text filter may be applied to FHIR requests to restrict the codes that are returned. The interpretation of this is delegated to the server in order to allow to determine the most optimal search approach for the context.
Typical usage of this parameter includes functionality like:
using left matching e.g. "acut ast"
allowing for wild cards such as %, &, ?
searching on definition as well as display(s)
allowing for search conditions (and / or / exclusions)
For further details, see
Example 1
Encoded URL
Example 2
Encoded URL
Returns a JSON representation of data related to the concepts that have terms that match the search string.
The data returned for each concept includes:
The codesystem to which the returned concept belongs
The identifier (code) of the returned concept
A display term associated with the concept, e.g. the preferred term
All concept release file data
The preferred term and fully specified name.
Also returns the total number of concepts that match the search string.
As some searches are matched by large numbers of concepts, restrictions may be applied to limit the number of returned concepts. Parameters include:
count to restrict the number of concepts returned.
offset to specify the start in the results (in multiples of the limit).
Example 1 returns the first 10 concepts that match the search term "knee". As indicated by the first part of the url, the version requested is the January 2020 version of the International Edition. The total number of concepts returned is 1387.
Example 2 uses the a search term with two partial words "ren ston". This finds only 7 matches but even in this case, the search results contain concepts from five different SNOMED CT hierarchies (substance, specimen, disorder, procedure and situation). However, please note that when using this FHIR service, the semantic tag (or FSN) is not provided in the response.
Find concepts by constrained term search
GET [fhir]/ValueSet/$expand?url=[version]?fhir_vs=ecl/[expressionConstraint]&filter=[search-string]
Example 3
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<363680008&count=10&filter=knee
Encoded URL
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C363680008&amp;count=10&filter=knee
Example 4
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<64572001|Disease|&filter=alcohol
Encoded URL
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C64572001%7CDisease%7C&filter=alcohol
Example 5
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<64572001|Disease|and ^450970008| General Practice / Family Practice reference set|&filter=alcohol
Encoded URL
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C64572001%7CDisease%7Cand+%5E450970008%7C+General+Practice+%2F+Family+Practice+reference+set%7C&filter=alcohol
Returns a JSON representation of data related to the concepts that have terms that match the search string.
The data returned for each concept includes:
The codesystem to which the returned concept belongs
The identifier (code) of the returned concept
A display term associated with the concept, e.g. the preferred term
All concept release file data
The preferred term and fully specified name.
Also returns the total number of concepts that match the search string.
As some searches are matched by large numbers of concepts, restrictions may be applied to limit the number of returned concepts. Parameters include:
count to restrict the number of concepts returned.
offset to specify the start in the results (in multiples of the limit).
Example 3 provides an example of how a search for x-ray procedures can be constrained so it is only necessary to enter the site and other related details. In this case the search term "knee" returns 40 matches. These include concepts such as "computed tomography of knee" which do not match "knee x-ray". The same constraint would simplifies all searches for radiology procedures and the constraint could also relaxed to include all imaging procedures.
Examples 4 and 5 provide an examples of how a search for a reason for admission might be constrained. In example 4, the constraint to disease restricts searches for alcohol or other drugs to concepts in the disorder hierarchy. This reduces the count of matches to 148. In example 5 a further constraint is added requiring the concept to be in the "General Practice / Family Practice reference set". The result of this is that only 21 matching concepts are returned. It is important to note that this is only an example, for practical in different clinical environments more specific reference sets should be considered.
Find concepts by term search
SELECT s.conceptId 'id',s.term 'term',f.term 'FSN'
FROM snap_term_search_active s JOIN snap_fsn f on s.conceptId=f.conceptId
WHERE MATCH (s.term) AGAINST ('[search-string]' IN BOOLEAN MODE) ORDER BY LENGTH(s.term)
For example
SELECT s.conceptId 'id',s.term 'term',f.term 'FSN' FROM snap_term_search_active s
JOIN snap_fsn f on s.conceptId=f.conceptId
WHERE MATCH (s.term) AGAINST ('knee' IN BOOLEAN MODE) ORDER BY LENGTH(s.term)
SELECT s.conceptId 'id',s.term 'term',f.term 'FSN' FROM snap_term_search_active s
JOIN snap_fsn f on s.conceptId=f.conceptId
WHERE MATCH (s.term) AGAINST ('+renal +stone' IN BOOLEAN MODE) ORDER BY LENGTH(s.term)
Returns the conceptId, term found and fully specified name. Ordering the results so that the closest matches (shortest matching terms) appear first in the list.
The searchPlus procedure allows a search string to be combined with a simple subtype constraint. This returns the conceptId and term for each match found. This current searchPlus procedure in the example MySQL database does not support more complex constraint expressions.
Requirements and Options
Term Searches
Search Techniques and Search Strings
Search Result Filtering and Ordering
Constrained Term Searches
All those involved in developing or procuring SNOMED CT terminology services are strongly advised to refer to the detailed guidance on this topic in the SNOMED CT Search and Data Entry Guide .
Essential and Recommended Functionality for Finding Concepts
Interdependencies
Required By
Depends On
Service Examples
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see IETF RFC1738).
Mapping between SNOMED CT concepts and other systems codes, classifications, or knowledge resources.
The services required to identify the members of a reference set are described in Section Get and Test Reference Set Membership. This section describes general requirements for services that are able to access additional data stored in reference sets.
The following services, described in earlier sections, require access to a single data value from each reference set row:
Get Terms for a Concept requires access to the acceptabilityId in a language reference set to determine the preferred and acceptable terms for a concept in a specified language or dialect.
The following services described in the next few sections, require access to one or more data values from each reference set row:
Get History Data uses historical reference set data to determine the reason for inactivation and to identify related active concepts.
Get Mapping Data uses mapping reference set data to access maps to or from SNOMED CT concepts or expressions.
Get Concept Model Rules uses MRCM reference set data to access concept model domain, attribute and range related rules.
Other reference set types that are not specifically documented in this section of the guide also contain additional data to which a client application may require access. Furthermore when new reference sets are introduced, there will be requirements to access additional data items in those reference sets. The service described in this section provides a general solution by providing access to all additional data associated with a reference set member in any type of reference set.
Service Name and Status
Input
Output
Get data from a reference set for a specific referenced component
REQUIRED
Edition and version
refsetId for the reference set from which data is to be extracted.
Optional alternatives: a set of refsetIds or an expression constraint for a group of related reference sets.
Data from specified rows in the identified reference set(s).
Note that the available data depends on the reference set type
Other Services
Get Terms for a Concept
Get Definition of a Concept
Get History Data
Get Mapping Data
Get Concept Model Rules
Select Edition and Version
Get and Test Reference Set Membership
Service Name
API Call 2
Result
Get data from a reference set for a specific referenced component
Example 1
Encoded URL
Example 2
Encoded URL
Example 3
Encoded URL
Returns a JSON representation of data from members of the specified reference set that match the specified criteria.
The data returned for each matching reference set row includes:
Data from the common columns present in all reference sets.
The referencedComponentId
Service Name
API Call
Result
Get data from a reference set for a specific referenced component
The FHIR TS API supports the retrieval of targets for specific SNOMED CT reference sets. Please refer to this document for detailed guidance: . Thus, the ConceptMap/$translate operation enables the retrieval of targets for a specific referenced component.
for example
Returns a JSON representation of data about each of the target components.
The data returned for each concept includes:
boolean: True if the concept could be translated successfully. The value can only be true if at least one returned match
match: Each match represents data for the map or associated target. Note that there may be multiple matches, where each element represents a mapTarget. For each mapTarget, following data is provided
Service Name
SQL Query
Result
Get data from a reference set for a specific referenced component
Example 1
Example 2
Example 1
Returns rows of data from the relevant reference set determined by the specified criteria.
The data returned for each matching reference set row includes:
Data in the common columns present in all reference sets.
Additional data columns associated with the particular reference set type.
Also returns the total number of reference set row that match the constraint.
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
Which provides examples of practical use cases involving access to SNOMED CT that an application may need to complete. For each of these use cases it identifies one or more of the required terminology services that can be used to complete the required activity.
As noted in the following section, these requirements can be met either directly by the application or by use of SNOMED CT terminology services accessed through an API.
Applications that require access to SNOMED CT are direct users of SNOMED CT terminology services. Organizations that design, develop, supply and support those applications can enable access to SNOMED CT in several different ways. The main options are identified in the table below with notes on the advantages and disadvantages of each option from the perspective of the application provider.
The first two options shown in the table require the application provider to also develop and maintain terminology services. Application providers considering those options should also take a look at the notes on the Terminology Services Provider Role.
Terminology Services Option
Advantages for Application Provider
Disadvantages for Application Provider
Application includes built-in functions for the terminology services it requires
Integrated approach may simplify installation.
No external dependency on third parties for supply or support of terminology service.
Application provider must create, maintain, and support terminology services.
Must keep pace with changes to SNOMED CT that affect user requirements.
Must enable access to appropriate SNOMED CT edition versions for each customer.
Application uses a defined interface to terminology services provided by the same organization
Purpose-built terminology server matched to application requirements.
No external dependency on third parties.
Potential to license terminology services for use with other applications.
Application Options for Access to Terminology Services
Table: Options for Application Access to Terminology Services - Application Provider Perspective
They should also enable access to extended versioned editions that include additional modules compatible with the selected edition.
They must provide access to data identifying which versioned edition (or extended versioned edition) is currently being accessed.
Terminology service users must ensure that the services they procure can be configured to access the SNOMED CT versioned editions (or extended editions) required by their organization, specialty, or national authority.
Healthcare application providers must ensure that applications:
Support access to configurable terminology services that can provide the required editions.
Track the history of the edition or extension in use, since this may affect data interpretation and analysis.
A SNOMED CT edition is a complete set of SNOMED CT components and reference set members that either belong to an identified module, or to one of the modules on which that module depends.
The module that defines the scope of an edition is called the focus module.
All editions (except the International Edition) combine one or more extension modules with the International Edition.
A complete edition may be prepared and released by SNOMED International, a National Release Center, or an Affiliate.
Dependencies between modules are recorded in the Module Dependency Reference Set.
Editions can be identified using a Uniform Resource Identifier (URI) as defined in the URI Standard.
Edition Type
Definition
Notes
International Edition
The set of SNOMED CT components and reference set members that belong to the International focus module or its dependencies.
Includes foundational content required by all other modules. The focus module is currently the SNOMED CT core module, with SNOMED CT model component module as a dependency. Can be supplemented by national or affiliate extensions.
Member / National Edition
A set of components and reference set members that belong to a focus module defined by a National Release Center (NRC) or its dependencies.
NRCs may produce multiple editions. Typically combines a national focus module with the International Edition and other required extensions. Distributed as part of a National Release.
When working with SNOMED CT, it is critical to ensure that release packages are correctly validated and imported. Proper validation safeguards data integrity and ensures that terminology services, applications, and users can rely on accurate and consistent content. This section outlines the general integrity checks required for all release packages, additional checks for extensions, and the requirements for importing release files.
General Release Package Integrity Checks
To validate the integrity of SNOMED CT release packages:
Consistency of distribution files
All imported files must be from the same release.
The set of files must be complete and include all mandatory components.
Delta releases
Previously imported data must be from the version immediately prior to the delta release being imported.
Snapshot or full releases
Pre-existing data must be removed before import, or
The process must overwrite duplicates so that:
Component identifiers
Must have a valid partition identifier for the type of component.
Must include a valid check-digit.
Field constraints
All fields must comply with data type, size, and value constraints defined in the Release File Specifications.
Concept integrity
All concepts must have at least two active descriptions:
One Synonym (900000000000013009).
Other consistency checks
May be applied as needed to ensure overall data integrity.
When importing an extension, additional checks must be performed to ensure proper installation and compatibility:
Recognition and approval
The extension must be recognized and formally approved by an appropriate authority.
Compatibility
Terminology service providers must ensure that terminology services provide access to all the data in selected versioned views of a selected SNOMED CT edition.
Applies to all editions and versioned views the service can access.
Data must support the purposes defined in the SNOMED CT Release File Specifications, though storage format does not need to match the release file structures exactly.
The simplest approach is to import all files from the full release and/or snapshot release of the required edition.
Exception
Notes
The data structure of each release file is defined in the SNOMED CT Release File Specifications:
Get a Concept, Description or Relationship
The terminology content of SNOMED CT is represented by three types of uniquely identified components:
A concept is a clinical idea to which a unique concept identifier has been assigned.
A description is an association between a human-readable phrase (term) and a particular SNOMED CT concept.
May be less attractive to organizations already using a terminology server.
Must create, maintain, and support terminology services.
Must keep up with terminology changes affecting user requirements.
Must ensure customer access to correct SNOMED CT editions.
May be less attractive to customers already using a different terminology server.
Application uses terminology services provided by a specified third party
No need to build or maintain terminology services.
Less burden to track SNOMED CT developments (managed by server).
Less responsibility for managing edition/version access.
Must support application integration with chosen third-party terminology services.
External dependency on the third-party provider.
Risk of support conflicts between application and terminology server.
Development limitations if the terminology server doesn’t evolve with SNOMED CT.
May be less attractive to organizations using a different terminology server.
Application supports use of terminology services that offer an interface that conforms to a publishedspecification
No need to build or maintain terminology services.
Less responsibility for SNOMED CT updates or edition/version management.
May appeal to organizations using that interface.
Enables migration to alternate providers if current service is discontinued or inadequate.
Must support interface integration with third-party services.
Performance or result variability across implementations using the same interface.
External dependency for support.
Support conflicts possible (origin of issue unclear).
Risk of stagnation if the server doesn't evolve to meet application needs.
Application configurable to support use of a specified range of terminology services
No need to build or maintain terminology services.
Less burden to follow SNOMED CT changes (server responsibility).
May appeal to organizations already using supported terminology services.
Enables migration to other services if current one is discontinued or underperforms.
Must support multiple interfaces to third-party services.
Result inconsistency across supported terminology services.
External dependency on terminology service providers.
Support conflicts possible.
Development may be limited by server responsiveness to SNOMED CT changes.
Affiliate Edition
A set of components and reference set members that belong to a focus module created by an Affiliate Licensee with an allocated namespace, or its dependencies.
May extend the International Edition or a National Edition.
Extended Edition
A SNOMED CT edition to which additional modules have been added.
Used to add modules containing maps, subsets, or other derivatives. Dependencies must be satisfied. Additional modules may include reference sets, metadata concepts, and subtype relationships, but not new clinical concepts, descriptions, or relationships.
Versioned Edition
A SNOMED CT edition that is published on a specific date.
International releases occur twice a year (January and July). National extensions often follow, with some delays. Some extensions (e.g., medication-related) may release more frequently.
Extended Versioned Edition
A versioned edition with additional modules added.
Must satisfy all module dependencies. Additional modules may include reference sets, metadata concepts, and subtype relationships, but not new concepts, descriptions, relationships, or OWL members.
A snapshot import does not contain obsolete rows.
A full release import matches the full release exactly.
One Fully Specified Name (900000000000003001).
All active concepts (except the root concept 138875005 | SNOMED CT Concept|) must have at least one active Is a relationship (116680003).
The extension must be based on, or supported by, the currently installed version of the International Edition.
Required versions of other dependent extensions must already be installed (or be part of the same import process).
Module dependencies
All dependencies of the extension module must be listed in the Module Dependency Reference Set.
Each dependency row must:
Match the extension’s moduleId.
Have a sourceEffectiveTime that matches the current version of the extension.
Reference the correct dependent modules and target effective times.
Component validation
All components must have a valid moduleId for the extension.
All component identifiers must:
Be unique per effectiveTime.
Have a valid partition identifier.
Use a namespace identifier appropriate to the extension provider.
Include a valid check-digit.
All fields must meet data type, size, and value constraints.
Where this is not possible, alternative sources may be used (see below).
Importing delta data between two versions from a full release
Import only rows where:
• effectiveTime > start date
• effectiveTime ≤ end date.
If multiple rows exist for the same id, import only the most recent.
Importing edition data from a multi-edition release package
Import only rows where the moduleId matches the edition’s moduleId or the moduleId of a dependent module.
Importing edition data from multiple release packages
Import only rows where the moduleId matches the edition or dependent modules. If dependencies are missing, import from additional packages. Avoid duplicates (rows with the same id and effectiveTime).
Importing snapshot data from a full release (same version)
Import only rows with the most recent effectiveTime for each unique id. Discard all other rows.
Importing snapshot data from a full release (later version)
Discard rows newer than the required version date. From the remaining rows, import only the most recent effectiveTime for each unique id.
Importing delta data from a full or snapshot release (same version)
Import only rows with an effectiveTime greater than the previous release date.
Optional parameters to select items within a particular type of reference set for example:
mapTarget (in a mapping reference set)
targetComponentId (in an association or ordered association reference set)
If the referencedComponentId refers to a concept, details of the concept including its fully specified name and preferred term are also included.
An additionalFields object containing specific data fields associated with the particular reference set type.
Also returns the total number of reference set row that match the constraint.
As some requests for reference set members return a large numbers of row, this service is paged. Requests parameters include:
limit to restrict the number of concepts returned (default 50).
offset to specify the start in the results (in multiples of the limit).
Example 1 shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.
Example 2 provides an example in which rows from all the historical association reference sets are returned.
Example 3 demonstrates that it is also possible to specify a targetComponentId value when searching for members of reference sets that contains this data item. Similar options are also supported for searches using some other data items specific to certain types of reference set (e.g. mapTarget, owlExpression.conceptId).
system: the codesystem of the mapTarget
code: The identifier of the mapTarget
Example 1 shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.
Example 1 shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.
Example 2 provides an example in which rows from two an historical association reference sets and the concept inactivation attribute value reference set are returned for a specified referencedComponentId
GET [snowstorm]/MAIN%2F2020-01-31/members?referenceSet=447562003&amp;referencedComponentId=32398004&active=true
GET [snowstorm]/MAIN/2020-01-31/members?referenceSet=447562003&referencedComponentId=111613008&active=true
GET [fhir]/ConceptMap/$translate?code=32398004&amp;amp;amp;system=http%3A%2F%2Fsnomed.info%2Fsct&amp;amp;source=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs+&amp;target=http%3A%2F%2Fhl7.org%2Ffhir%2Fsid%2Ficd-10&url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_cm%3D447562003
GET [snowstorm]/[branchPath]/members?referenceSet=[refsetid]&mapTarget=[otherCode]&active=true
GET [snowstorm]/MAIN/2020-01-31/members?referenceSet=446608001&mapTarget=8090/3&active=true
GET [snowstorm]/MAIN%2F2020-01-31/members?referenceSet=446608001&amp;mapTarget=8090%2F3&active=true
GET [snowstorm]/MAIN/2020-01-31/members?referenceSet=900000000000497000&mapTarget=Xa9C4&active=true
GET [snowstorm]/MAIN%2F2020-01-31/members?referenceSet=900000000000497000&amp;mapTarget=Xa9C4&active=true
GET [snowstorm]/[branchPath]/members?referenceSet=[refsetid]&referencedComponentId=[conceptId]&mapTarget=[otherCode]&active=true
GET [snowstorm]/MAIN/2020-01-31/members?referenceSet=447562003&referencedComponentId=111613008&mapTarget=S06.90&active=true
GET [snowstorm]/MAIN%2F2020-01-31/members?referenceSet=447562003&amp;amp;referencedComponentId=111613008&amp;mapTarget=S06.90&active=true
SELECT * FROM snap_refset_extendedmap WHERE active=1 AND refsetId=[refsetId] AND referencedComponentId=[conceptId] AND mapTarget=[otherCode]
SELECT * FROM snap_refset_extendedmap WHERE active=1 AND refsetId=447562003 AND referencedComponentId=111613008 AND mapTarget="S06.90"
SELECT * FROM snap_refset_extendedmap WHERE active=1 AND refsetId=447562003 AND referencedComponentId=111613008 AND mapTarget like "S06.%"
GET [snowstorm]/[branchPath]/members?active=true&referenceSet=[refsetId-or-ecl][&refsetComponentId=[componentId][&other-refsetType-specific-parameters]
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=900000000000523009|POSSIBLY EQUIVALENT TO association reference set|&referencedComponentId=203004
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;referenceSet=900000000000523009%7CPOSSIBLY+EQUIVALENT+TO+association+reference+set%7C&referencedComponentId=203004
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=<900000000000522004|Historical association reference set|
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=<900000000000522004|Historical association reference set|&targetComponent=140004
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C&targetComponent=140004
GET [fhir]/ConceptMap/$translate?code=[componentId] &system=http://snomed.info/sct &source=http://snomed.info/sct?fhir_vs &target=http://snomed.info/sct?fhir_vs &url=[version]?fhir_cm=[refesetId]
GET [fhir]/ConceptMap/$translate?code=203004 &system=http://snomed.info/sct &source=http://snomed.info/sct?fhir_vs &target=http://snomed.info/sct?fhir_vs &url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_cm=900000000000523009
SELECT * FROM snap_refset_[refsetType] WHERE refsetId=[refsetId] [AND other-refset-type-specific-criteria];
SELECT * FROM snap_refset_association WHERE refsetId=900000000000523009 AND active=1 AND referencedComponentId=203004;
SELECT * FROM snap_refset_association
WHERE refsetId IN (900000000000523009)
AND active=1 AND referencedComponentId=203004
UNION
SELECT * FROM snap_refset_attributevalue
WHERE refsetId IN (900000000000489007)
AND active=1 AND referencedComponentId=203004;
SELECT * FROM snap_refset_association
WHERE refsetId IN (900000000000523009,900000000000489007)
AND active=1 AND targetComponentId=140004;
SELECT * FROM snap_refset_association WHERE refsetId IN (900000000000523009, 900000000000524003, 900000000000525002, 900000000000526001, 900000000000527005, 900000000000528000, 900000000000529008, 900000000000530003, 900000000000531004)
AND active=1 AND targetComponentId=140004;
uses a search term with two partial words "ren ston". This finds only 7 matches but even in this case, the search results contain concepts from five different SNOMED CT hierarchies (substance, specimen, disorder, procedure and situation).
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&amp;term=ren+ston&ecl=%3C64572001%7CDisease%7C
GET [fhir]/ValueSet/$expand?url=[versionURI]?fhir_vs&count=10&filter=[search-string]
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs&filter=knee
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs&filter=knee
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs&filter=ren ston
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs&filter=ren ston
A relationship is an association between a source concept and a destination concept.
Each of these components is associated with a set of attributes that support interpretation of the component at a given point in time. The data structures of the components and the associations between them are documented in the SNOMED CT Release File Specifications.
Getting data associated with identified concepts, descriptions or relationships is a fundamental requirement that must be met by any SNOMED CT terminology services provider. The required services are listed in the table below.
Service Name and Status
Input
Output
Get concept by identifier
REQUIRED
Edition and version
A concept identifier
Optional: Language/dialect
Concept not found: Return appropriate error message.
Concept found: Return data associated with the concept.
Get description by identifier
REQUIRED
Edition and version
A description identifier
Description not found: Return appropriate error message.
Description found: Return data associated with the description.
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
Snowstorm API
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
FHIR API
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of ().
SQL Illustration
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system . However, it is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the SNOMED CT - SQL Practical Guide.
Includes the definition status but does not include the stated or inferred definition of the concept.
Also includes human readable symbolic names for concept enumerations (e.g. " type ": "SYNONYM", "caseSignificance": "CASE_INSENSITIVE" )
A representation of the subtype relationships of the concept
GET [snowstorm]/[branchPath]/concepts/[relationshipId]
GET [snowstorm]/MAIN%2F2020-01-31/relationships/3303602028
GET [snowstorm]/MAIN%2F2020-01-31/relationships/3303602028
SELECT * FROM snap_relationship WHERE id=[relationshipId]
SELECT * FROM snap_relationship WHERE id=3303602028
GET [snowstorm]/[branchPath]/concepts/[conceptId]
GET [snowstorm]/MAIN%2F2020-01-31/concepts/6025007
GET [snowstorm]/MAIN%2F2020-01-31/concepts/6025007
GET [snowstorm]/[branchPath]/descriptions/[descriptionId]
GET [snowstorm]/MAIN%2F2020-01-31/descriptions/2156578010
GET [snowstorm]/MAIN%2F2020-01-31/descriptions/2156578010
GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct &code=[conceptId]&_format=json
GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct &code=6025007&_format=json
SELECT * FROM snap_concept WHERE id=[conceptId]
SELECT * FROM snap_concept WHERE id=6025007
SELECT * FROM snap_description WHERE id=[descriptionId]
SELECT * FROM snap_description WHERE id=2156578010
Identify Changes to the Terminology
Got it — here’s the GitBook-ready version with no section or table numbering, fully cleaned up for a smooth read.
Overview
\
SNOMED CT release files include data that allows tracking of all changes between different versions of any edition of the terminology.
\
In addition to a unique id, each row in every release file includes:
effectiveTime – the date when the row became the effective version of that component or reference set member, either as a new component or a revision of the previous version.
active – indicates whether the component is still intended for active use.
moduleId – identifies the module that the component belongs to. A change to the moduleId indicates that a component has been moved to a different module, which may be:
another module maintained by the same organization, or
a module maintained by a different organization.
Before updating to a newer SNOMED CT version, it is essential to:
Identify the inactivation of any concepts and descriptions used in:
data entry templates
picklists
This section focuses on services that identify and categorize these changes. Additional services that provide more detail about some changes are described later in Get History Data.
To identify changes, terminology services must be able to:
Identify components and reference set members in the full release of the new version with an effectiveTime greater than the date of the previously installed version.
For each identified component:
Check active status in the updated release (active or inactive).
Previous
Updated
Update Type
Comment
Actions to Consider
Service Name and Status
Input
Output
Other Services
Use Cases
(including support for selecting two versions for comparison)
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
Service Name
API Call
Result
FHIR API
Service Name
API Call 5
Result
Service Name
SQL Query
Result
Notes
The significance of changes to membership of reference sets depends on the extent to which they are used by a particular application. For example, a change to language reference set membership may mean that a description is no longer acceptable in the language or dialect used in by an application. Similarly, a change to a the membership of a simple reference set used to constrain a searches, reports or analytics may alter the results of those actions.
A delta release file may be available to provide information about changes since the previous release. However, in cases where an organization does not update the version they are using regularly, there may not be a single set of delta release files covering all the changes made between the version in use and the current version.
Language and/or dialect should be specified if the service returns terms associated with referenced concepts.
Explore and Review SNOMED CT
SNOMED CT browsers and other applications that enable access SNOMED CT concepts allow the content and structure of the terminology to be explored. This exploration can serve many different purposes, ranging from allowing people to get a broad idea of the scope of SNOMED CT to looking for specific concepts that interest them. The same applications can be used to enable a more thorough review of the terminology in a particular specialty area to assess the breadth, depth and applicability of SNOMED CT to a particular set of requirements. Tools that enable visual review of a released SNOMED CT Edition are also valuable for quality assurance and when considering requests for addition or changes to the terminology.
Practical Requirements and Related Terminology Services
The table below shows a summary of the terminology services required to support effective exploration and review of SNOMED CT content.
Practical Requirement
Status
Required Services
Dependencies
reporting and analytics queries
Review changes to reference set memberships where these sets are used to assist or constrain data entry.
Consider broader review of changes to other reference sets used in reporting or analysis.
Check whether it existed in the previous release and, if so, its status there (active, inactive, or none).
Based on these results, determine:
The type of update.
Actions to consider.
active
active
Change
Component changed but remains active. May include property changes or moduleId reorganization.
Review nature of change and assess impact.
active
inactive
Inactivation
Component inactivated since the previous release.
Concept: Review/replace in templates, picklists, constraints, queries; use history data to find replacements.Description: Review/replace in templates, picklists.Refset member: Assess impact on data entry, mapping, reporting.
inactive
active
Reactivation
Component reactivated, possibly correcting an earlier inactivation.
Reverse any prior adjustments if applicable.
inactive
inactive
Remains inactive
Unusual case – remains inactive but has changed in some way.
No action required.
none
inactive
Inactivated addition
Likely added in an intermediate release, now inactivated.
No local action required, but be aware it may appear in data from systems using that intermediate release.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of HL7 (www.hl7.org).
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system. It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the SNOMED CT - SQL Practical Guide. For instructions on how to build the example database refer to Appendix A: Building the SNOMED CT Example Database.
Note that to avoid issues if hours, minutes or seconds are included in previousVersionDate, the value should be set as 23:59:59 on the required date.
none
active
Addition
Component added since the previous release.
Get components or reference set members that have changed since a specified previous release
REQUIRED
Edition
Version release date/time (snapshot of components and refset members at this date/time represents the updated state)
Previous version release date/time (snapshot of components and refset members at this date/time represents the previous state)
Component type or reference set type
Optional: refsetId
Optional: Language/dialect
Identifiers of components or reference set members with the following characteristics:
specified component or reference set type
effectiveTime greater than previous release date/time (note that if only date is specified then component with any effectiveTime on that date must be excluded)
Indication of the update type. The update type indication should be applied either to:
the set of identifiers to which it applies; or
individually to each identifier.
Optionally other data associated with each changed component or reference set member could also be returned. However, requirements for additional data vary depending on the update type and the type of component or reference set. A service that returns sets of identifiers grouped by update type, and component or reference set type offers a more flexible solution. It allows additional data to be retrieved selectively by other services to support appropriate review of the changes.
Get components or reference set members that have changed since a specified previous release
N/A
This service is not currently supported.
When Snowstorm is running with write access enabled it is possible to export SNOMED CT content selected by a range between two effective times. This process could be adapted to allow the relevant information to be processed in an application to identify the components and reference set members that have been updated. However, this would require the client application to process the selected data after it has been exported in the release file format.
Get components or reference set members that have changed since a specified previous release
N/A
This service is not supported.
Get components or reference set members that have changed since a specified previous release
SELECT * FROM [snapshotTableName]
WHERE effectiveTime > [previousVersionDate];
Example 1
* FROM `snap_concept`where `effectiveTime` > '2019-07-31';
Example 2
SELECT * FROM `snap_description`
where `effectiveTime` > '2017-01-31';
Example 3
CALL setSnapshotTime(1, '2019-07-31);
SELECT * FROM snap1_refset_simple
WHERE effectiveTime > '2018-07-31';
Returns all rows in the specified snapshot view of the named release file that have an effectiveTime is later than the specified previous version date. The snapshot time for the snapshot view determines the date of the current version.
Example 1 returns all rows in the current snapshot of the concept release file that have an effectiveTime after 2019-07-31.
Example 2 returns all rows in the current snapshot of the description release file that have an effectiveTime after 2017-01-31.
Example 3 sets a specific snapshot time 1 as (2019-07-31). It then returns rows from the simple reference set table in that specific snapshot view that have an effectiveTime after 2018-07-31.
Minimum Review Checklist
Requirements and Options
Terminology Component Update Types
Note on Unusual Cases
The “Remains inactive” and “Inactivated addition” situations are uncommon. While they generally require no local action, they can appear in exchanged data from systems using different SNOMED CT release versions. Awareness of these scenarios helps avoid confusion when interpreting shared records.
Organizations that maintain SNOMED CT edition(s) or extension(s) must distribute one or more release package(s).
Each release package must contain a full release for the current version of an edition or extension for which they are responsible.
Optionally, each release package may also contain a snapshot release and/or delta release for the same version of the same edition or extension.
Terminology service providers must ensure their service can import data from either a full or snapshot release of a selected edition or extension.
They should also consider enabling their service to update a previously imported edition or extension using a delta release.
Healthcare application providers should ensure that their applications can work with terminology services that support importing and updating SNOMED CT using the available release types.
Terminology service users must confirm that the healthcare applications and terminology services they procure:
Provide access to the SNOMED CT editions and extensions they require.
Support updates to more recent versions of those editions and extensions.
Release Type
Description
The following sections illustrate the differences between delta, full, and snapshot release types across five releases of a simplified example release file.
Symbol
Meaning
Six components created.
Delta, Full, and Snapshot are identical (no previous release).
Delta, Full, Snapshot:
id
effectiveTime
active
term
Component 3 changed from 3rd → third.
id
effectiveTime
active
term
Components 7 (fourth) and 8 (fifth) added.
id
effectiveTime
active
term
Component 4 inactivated.
id
effectiveTime
active
term
Component 5 inactivated.
Component 6 changed to sixth.
Component 9 added (seventh).
id
effectiveTime
active
term
All SNOMED CT release packages must include a set of full release files for a SNOMED CT edition or extension.
A full release includes the complete history of the content of that edition or extension.
This allows a terminology server to enable access to versioned views of the content of this edition or extension as it was at any point between its first release and the current release.
A versioned view is a set of component versions and reference set member versions defined by the characteristics of their effectiveTime.
Versioned views and release types are closely related.
A release type is a physical representation of a particular versioned view.
Some versioned views are not instantiated as release types, but all valid views of a SNOMED CT edition can be generated from a full release.
Includes the most recent version of all components and reference set members at a specified point in time.
Uses:
The current snapshot view is the most important and is in constant use during daily operations.
Includes only rows representing changes to components and reference set members since a specified date or between two dates.
Uses:
When updating to a new version, delta views identify components that were added, updated, or inactivated between releases.
Includes all versions of all components and reference set members in a full release.
Uses:
Useful for organizations that do not apply every update, but still need to interpret data that references content not in the snapshot view they use.
View
Description
View
Description
To enable terminology services to access a full view of a SNOMED CT edition:
Import a full release of the edition into an appropriate datastore.
To update:
Import the latest full release, replacing the old data; or
To provide access to a snapshot view:
Import the current snapshot release; or
Selectively import data from the current full release (most recent versions only); or
Filter the full view to include only the most recent version of each component before a specified date.
To update to a new snapshot view:
Use any of the above methods to add or replace a snapshot view; or
Import the latest delta release and update the snapshot accordingly.
To provide access to a delta view:
Import the delta release for that edition; or
Selectively import rows from the full release where effectiveTime is after the previous release date and on or before the current release date; or
Filter a full release to generate configurable delta views between arbitrary dates.
Configurable delta views may include:
Only the most recent change to each component within the period, or
All changes to each component during that period.
Get Definition of a Concept
Overview
Each SNOMED CT concept has a concept definition.
A concept definition is a set of one or more axioms that partially or sufficiently specify the meaning of a SNOMED CT concept.
Notes
Concept definitions are represented in two ways in SNOMED CT release files:
* As a stated view represented by axioms that conform to the OWL Functional Syntax distributed in the OWL Expression Reference Set file.
* As an inferred view represented by defining relationships that are distributed in the relationship file. The inferred view is generated by applying description logic classification to the stated view.
Requirements and Options
The table below describes several distinct types of access to concept definitions and the client application functionalities that each of these access types supports.
General purpose terminology services that are able to access subtype relationships relationships can be used to meet a limited set of SNOMED CT use cases. However, SNOMED CT terminology services should also provide access to the inferred view of concept definitions.
Advanced SNOMED CT terminology services require the ability to access and interpret the axioms that represent the stated view of concept definitions. They should also enable description logic classification either as a built in service or via an interface to separate classifier. Services that support classification provide added value for data retrieval and analysis by enabling post-coordinated expressions to be classified and appropriately located in the subtype hierarchy.
The required services listed in the table below omit services that only require access to subtype relationships, as these are described in .
Access to the complete inferred view of concept definitions, including subtype relationships and attribute relationships
- Concept identifier
- Edition and version
- Inferred definition of the specified concept represented as a compositional grammar expression or as a data object representing all active rows in the snapshot view of the relationship file.
- Optionally, concept identifiers in the definition may be supplemented with the preferred term or fully specified name in a specified language or dialect.
Access to the complete stated view of concept definitions, as OWL axioms
- Concept identifier
- Edition and version
- Stated definition of the concept represented as a set of one or more OWL axioms or as a SNOMED CT compositional grammar expression.
- Optionally, concept identifiers in the definition may be supplemented with the preferred term or fully specified name in a specified language or dialect.
-- Get inferred defining relationshipsSELECTtypeId,destinationId,groupFROMsnap_relationship WHEREANDactive=1 ANDsourceId=[conceptId] ANDcharacteristicType=900000000000011006;
-- Get inferred defining relationshipsSELECTtypeId,destinationId,groupFROMsnap_relationship WHEREactive=1 ANDcharacteristicType=900000000000011006 ANDsourceId=6025007;
-- Get inferred defining relationships with termsSELECT CONCAT(typeId,"|",typeTerm,"|=", destinationId,"|",destinationTerm,"|") 'value', relationshipGroup 'group'FROMsnap_rel_def_fsn WHEREsourceId=6025007;
-- Get inferred defining relationshipsSELECTtypeId,destinationId,groupFROMsnap_relationship WHEREANDactive=1 ANDsourceId=[conceptId] ANDcharacteristicType=900000000000011006;
-- Get inferred defining relationshipsSELECTtypeId,destinationId,groupFROMsnap_relationship WHEREactive=1 ANDcharacteristicType=900000000000011006 ANDsourceId=6025007;
-- Get inferred defining relationships with termsSELECT CONCAT(typeId,"|",typeTerm,"|=", destinationId,"|",destinationTerm,"|") 'value', relationshipGroup 'group'FROMsnap_rel_def_fsn WHEREsourceId=6025007;
Get the stated definition of a concept
for example
or as example of a concept defined by more than one axiom
Returns the set of rows each containing one OWL axiom.
The sort order used in this query ensures that class axioms appear before any GCI axioms
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=[conceptId] ORDERBYowlExpression;
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=6025007 ORDERBYowlExpression;
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=473011001 ORDERBYowlExpression;
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=[conceptId] ORDERBYowlExpression;
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=6025007 ORDERBYowlExpression;
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=473011001 ORDERBYowlExpression;
Concept definitions include two distinct elements
Axioms that assert that a concept is a subtype of one or more other concepts. In the inferred view these are represented as subtype relationships.
Axioms that assert characteristics of a concept that distinguish it from its supertypes. In the inferred view these are represented as attribute relationships.
Access to subtype relationships
- Concept identifier
- Edition and version
- Set of conceptIds of all concepts with a direct subtype relationship to or from the specified concept.
- Optionally, additional information such as the fully specified name or preferred term of each concept in the set.
Access to the transitive closure of subtype relationships
- Concept identifier
- Edition and version
- Set of conceptIds of all concepts with a direct or transitive subtype relationship to or from the specified concept.
- Optionally, additional information such as the fully specified name or preferred term of each concept in the set.
Get inferred necessary normal form definition of a conceptREQUIRED
- Edition and version
- Concept identifier
- Language/dialect (optional)
- Inferred definition of the specified concept as a SNOMED CT compositional grammar expression or as a data object representing all active rows in the snapshot view of the relationship file.
- Optionally, concept identifiers in the definition may be supplemented with the preferred term or fully specified name in a specified language or dialect.
Get stated definition of a conceptADVANCED
- Edition and version
- Concept identifier
- Language/dialect (optional)
- Stated definition of the concept as a set of one or more OWL axioms or as a SNOMED CT compositional grammar expression.
- Optionally, concept identifiers in the definition may be supplemented with the preferred term or fully specified name in a specified language or dialect.
Get the inferred necessary normal form definition of a concept
for example
Encoded URL
or without including the terms
Encoded URL
Returns a JSON data object containing a compositional grammar expression representing the inferred definition of the concept.
If the optional includeTerms parameter is set to true the expression includes the fully specified names of each concept referenced in the expression. Otherwise only the expression only includes the concept identifiers.
Get the stated definition of a concept
for example
Encoded URL
or as example of a concept defined by more than one axiom
Encoded URL
This service returns a JSON representation of one or more members of in the OWL expression reference set that together represent the stated definition of the identified concept. Each of these reference set members contains an axiom, represented using OWL Functional Syntax, in the additionalFields.owlExpression property string.
Get the inferred necessary normal form definition of a concept
for example
Returns a JSON representation of information containing the definition of the concept.
The data returned includes the necessary inferred, normal form definition of the concept represented as a compositional grammar expression.
Get the stated definition of a concept
N/A
This service is not supported by the FHIR terminology services API
Get the inferred necessary normal form definition of a concept
for example
or including terms
Returns the set of rows each containing one defining relationship with its associated relationship group number.
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=473011001 ORDERBYowlExpression;
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=6025007 ORDERBYowlExpression;
-- Get stated defining axiomsSELECTowlExpressionFROMsnap_refset_owlexpression WHEREactive=1 ANDrefsetId=733073007 ANDreferencedComponentId=[conceptId] ORDERBYowlExpression;
-- Get inferred defining relationships with termsSELECT CONCAT(typeId,"|",typeTerm,"|=", destinationId,"|",destinationTerm,"|") 'value', relationshipGroup 'group'FROMsnap_rel_def_fsn WHEREsourceId=6025007;
-- Get inferred defining relationshipsSELECTtypeId,destinationId,groupFROMsnap_relationship WHEREactive=1 ANDcharacteristicType=900000000000011006 ANDsourceId=6025007;
-- Get inferred defining relationshipsSELECTtypeId,destinationId,groupFROMsnap_relationship WHEREANDactive=1 ANDsourceId=[conceptId] ANDcharacteristicType=900000000000011006;
Practical Requirements for Access to Concept Definitions
Services Required
Interdependencies
Required By
Depends On
Service Examples
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see IETF RFC1738).
GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct&code=6025007&property=normalForm&_format=json
🟥
Inactivated version of a component
◼️
Not the most recent version (historical row)
1
second
🟩 3
20010131
1
3rd
🟩 4
20010131
1
forth
🟩 5
20010131
1
V
🟩 6
20010131
1
VI
id
effectiveTime
active
term
⚪ 1
20010131
1
first
⚪ 2
id
effectiveTime
active
term
⚪ 1
20010131
1
first
20030131
1
fifth
id
effectiveTime
active
term
⚪ 1
20010131
1
first
id
effectiveTime
active
term
⚪ 1
20010131
1
first
id
effectiveTime
active
term
⚪ 1
20010131
1
first
⚪ 2
id
effectiveTime
active
term
⚪ 1
20010131
1
first
20050131
1
sixth
🟩 9
20050131
1
seventh
id
effectiveTime
active
term
⚪ 1
20010131
1
first
id
effectiveTime
active
term
⚪ 1
20010131
1
first
The extent to which a terminology service supports access to different versioned views may vary.
Terminology service providers must:
Optimize performance of access to the current snapshot view of a selected edition or extension.
Provide access to earlier snapshot views and delta views to support:
Analysis of data entered using earlier versions.
Terminology change management when updating to newer versions.
Healthcare application providers must ensure that their applications can use terminology services that provide access to required versioned views of SNOMED CT.
Services that support access to the current snapshot view should be selected and optimized.
Services that enable access to a new version of the same edition should also be accessible to manage updates.
Access to earlier versions should be available to support analysis of data recorded with content that has since been inactivated.
Terminology service users must procure applications and services that:
Optimize access to the current snapshot view of the selected versioned edition.
Support updates to newer versions.
Support analysis of data recorded using content that has since been inactivated.
When updating to a new version, access to the earlier snapshot is required to determine the type of change made to each component.
When reviewing, analyzing, or reporting older data, snapshot views from the relevant time may help interpret unexpected variations.
Access to earlier full views may be required for forensic review or anomaly resolution.
All snapshot views of a range of different editions
Supports snapshot views for multiple editions.
✅ Meets requirements for data entry, display, change management, retrospective data analysis, and access to modules from any supported edition.
Configurable delta views across multiple editions
Shows changes between two points across one or more editions. Useful in cases where multiple editions are in use.
Import the latest delta release and append it to the existing full release data.
Full
Release files contain every version of every component and reference set member ever released. Enables access to any snapshot view and comparisons between releases.
Snapshot
Release files contain only the most recent version of every component and reference set member as at the release date. Enables access to the current release snapshot and comparison of changes between snapshots.
Delta
Release files contain only rows representing versions created since the previous release date. Supports incremental updates to full or snapshot data and reviewing changes between releases.
⚪
Unchanged component (still active and unchanged in this release)
🟩
New component added in this release
🟨
Updated version of an existing component
🟩 1
20010131
1
first
🟩 2
🟨 3
20020131
1
third
🟩 7
20030131
1
fourth
🟥 4
20040131
0
forth
🟥 5
20050131
0
V
Single snapshot view of an edition
Supports only one preset snapshot view (the current version). The server is reconfigured when updating to a newer version.
✅ Meets requirements for current data entry and display.
❌ Does not meet requirements for change management, retrospective data analysis, or access to modules outside the edition.
Multiple snapshot views of an edition
Supports snapshot views for a limited set of versions (e.g., current and previous). Versions can be specified in requests.
✅ Meets requirements for data entry, display, and change management.
⚠️ Partially meets requirements for retrospective data analysis.
❌ Does not meet requirements for access to modules outside the edition.
All snapshot views of an edition
Supports snapshot views for any point in time within an edition.
✅ Meets requirements for data entry, display, change management, and retrospective data analysis.
❌ Does not meet requirements for modules outside the edition.
Single delta view (current vs. previous version)
Shows changes between the current version and the previous version of an edition. Useful for reviewing the most recent changes. Also requires access to the snapshot of the previous release.
Multiple delta views (between adjacent versions)
Shows changes between earlier releases (each version vs. its predecessor). Useful for reviewing historical changes and addressing issues retrospectively. Requires access to the snapshot view prior to each delta.
Configurable delta views (between any two dates)
Flexible solution showing changes between any two specified points. Requires access to a full release. Supports identifying all changes within the period. May include one or all changes for each component.
Release Type Characteristics and Uses
Note: Delta files have been removed from the SNOMED International release package, Managed Service Extensions and Derivative packages. Instead, a Delta Generation Tool is available to create deltas between two fixed release dates.
If the release package does not include a snapshot release or delta release, equivalent views can be derived from the full release.
The inferred definition of each concept includes a set of one or more subtype relationships relationships.
A subtype relationship is a relationship that asserts that a concept is a subtype of another concept.
Subtype relationships are represented by relationship type 116680003 | is a| .
A subtype relationship asserts that a concept conforms to all the defining characteristics the supertype concept but also has at least one feature or refinement that distinguishes it from that concept.
Subtype relationships are transitive. Each individual subtype relationship links a concept to a supertype parent concept. That concept will also have one or more subtype relationships to its own supertype parents.
These transitive chains of subtype relationships link every active concept to a set of supertype ancestors and eventually to the .
The meaning of a concept subsumes the meaning of its subtype children and descendants. Therefore, service that test or traverse subtype relationships are essential for effective meaning-based reporting and analysis.
Requirements and Options
Display of the SNOMED CT hierarchy requires access to the direct supertype parents and subtype children of a specified concept.
Effective use of SNOMED CT for retrieval, analysis and constrained data entry requires rapid identification of concepts that are supertype ancestors or subtype descendants of a specified concept.
The requirements listed in the table below include services that return the full set of children, parents, descendants or ancestors of a concept. However, other requirements can be more efficiently met by testing for a transitive subtype or supertype relationship between a specified concept and a set of one or more candidate concepts.
Service Name and Status
Input
Output
Other Services
Service Name
API Call 4
Result
Service Name
API Call 6
Result
Service Name
SQL Query
Result
Notes
The services in this table that list subtype and supertype concepts are a subset of the services required to implement expression constraints (see see [4.7 Validate and Apply Expression Constraints" style="width: 100%;">). Therefore, it is recommended that the is used when requesting these services.
Language and/or dialect should be specified if the service returns terms associated with referenced concepts.
The subsumption test services are marked as recommended rather than required because they can be implemented by the client application using the results of the get subtype descendants and/or get supertype ancestors services.
Select Edition and Version
Overview
Editions
Several different SNOMED CT editions are available. All editions include the content of the SNOMED CT International Edition but some also include extensions that contain additional content designed for use in a particular country, region, speciality or organization. Terminology services may support access to more than one edition, so the service must enable the client to select the appropriate edition.
It is important to specify the edition to enable access to national or local terminology content that is not available in other editions. Content specific to an edition may include locally added concepts and additional descriptions that provide terms in a national language or local dialect. An edition may also include additional reference sets representing subsets or maps.
Versions
SNOMED CT editions are maintained with regular updates. Each update to an edition is referred to as a SNOMED CT versioned edition. Terminology services should enable access to more than one edition, so the service must enable the client to select the appropriate version.
It is important to specify the version as each version update adds, changes or inactivates some components and reference set members. Therefore, the result of a terminology service may differ depending on the version.
An organization maintaining a SNOMED CT edition or extension will also have internal development versions and prerelease versions for testing. Therefore, services designed to support terminology development and maintenance also need to enable selection of specific terminology development versions or branches.
SNOMED CT specifications define a full release that represents a complete record of the history of all released components, and a snapshot release type that only represents the state of those components at a specified date.
Some services described in this guide involve checking for changes between versions. Direct support for these services requires two versions to be specified to enable comparison of the before and after state of components that have changed between versions.
Selection of a specified edition, versioned edition or extended versioned edition is a prerequisite for all other terminology services as it determines the terminology substrate to be used when responding to those service requests. The selection process needs to be supported by services that enable the client application to find out information about available editions, versioned editions, and extended versioned editions. The required services are listed in the table below.
Service Name and Status
Input
Output
For performance reasons, scalable terminology services should be stateless and this rules out prior configuration of a session to work with a particular edition or version. Therefore, all service requests must explicitly identify the edition and version to be accessed.
Servers that support access to development versions of an edition must enable access to specified development branches as well as versions.
Servers that provides access to development branches needs to provide a service that identifies the available development branches.
Terminology services that support comparison between versions (or between development branches), must allow both the versions (or branches) to be specified.
Required By:
All other terminology services
All use cases
Explanation:
Terminology services depend on the explicit selection of an edition and version (or development branch) to ensure accurate querying, classification, and interpretation of SNOMED CT data.
In minimal implementations (e.g., a server with only a single pre-configured snapshot), version/edition selection may not be an explicit service. Instead, the selection is implicitly determined by the data loaded into the server.
However, more flexible and scalable systems—especially those supporting multiple editions and version comparisons—must expose version selection as a configurable parameter in every request.
Depends On:
The terminology server must contain data for all versioned editions that may be requested.
Service Name
API Call
Result
Service Name
API Call
Result
Service Name
SQL Query
Result
Any version of the edition supported by the schema, can be accessed provided the schema was built using the full release files. The most recent version and two earlier versions can be accessed simultaneously by referring to different views (snap1 and snap2). The versions in each of the two earlier views are specified in a configuration file. The version settings for each of these the earlier views can be set to specify the version at any past date.
Queries run on a specific snapshot view return the data as it was at the configured date.
20010131
1
second
◼️ 3
20010131
1
3rd
🟨 3
20020131
1
third
⚪ 4
20010131
1
forth
⚪ 5
20010131
1
V
⚪ 6
20010131
1
VI
⚪ 2
20010131
1
second
🟨 3
20020131
1
third
⚪ 4
20010131
1
forth
⚪ 5
20010131
1
V
⚪ 6
20010131
1
VI
⚪ 2
20010131
1
second
◼️ 3
20010131
1
3rd
🟨 3
20020131
1
third
⚪ 4
20010131
1
forth
⚪ 5
20010131
1
V
⚪ 6
20010131
1
VI
🟩 7
20030131
1
fourth
🟩 8
20030131
1
fifth
⚪ 2
20010131
1
second
🟨 3
20020131
1
third
⚪ 4
20010131
1
forth
⚪ 5
20010131
1
V
⚪ 6
20010131
1
VI
🟩 7
20030131
1
fourth
🟩 8
20030131
1
fifth
20010131
1
second
◼️ 3
20010131
1
3rd
🟨 3
20020131
1
third
⚪ 4
20010131
1
forth
🟥 4
20040131
0
forth
⚪ 5
20010131
1
V
⚪ 6
20010131
1
VI
⚪ 7
20030131
1
fourth
⚪ 8
20030131
1
fifth
⚪ 2
20010131
1
second
🟨 3
20020131
1
third
🟥 4
20040131
0
forth
⚪ 5
20010131
1
V
⚪ 6
20010131
1
VI
⚪ 7
20030131
1
fourth
⚪ 8
20030131
1
fifth
⚪ 2
20010131
1
second
◼️ 3
20010131
1
3rd
🟨 3
20020131
1
third
⚪ 4
20010131
1
forth
🟥 4
20040131
0
forth
⚪ 5
20010131
1
V
🟥 5
20050131
0
V
⚪ 6
20010131
1
VI
🟨 6
20050131
1
sixth
⚪ 7
20030131
1
fourth
⚪ 8
20030131
1
fifth
🟩 9
20050131
1
seventh
⚪ 2
20010131
1
second
🟨 3
20020131
1
third
🟥 4
20040131
0
forth
🟥 5
20050131
0
V
🟨 6
20050131
1
sixth
⚪ 7
20030131
1
fourth
⚪ 8
20030131
1
fifth
🟩 9
20050131
1
seventh
Get subtype descendants of a concept
conceptId
Optionally, language or dialect code
Set of conceptIds of all concepts with a direct or transitive 116680003 | is a | relationship to the specified concept.
Optionally additional information such as the fully specified name or preferred term of each concept in the set.
Get supertype ancestors of a concept
conceptId
Optionally, language or dialect code
Set of conceptIds of all concepts with a direct or transitive 116680003 | is a | relationship from the specified concept.
Optionally additional information such as the fully specified name or preferred term of each concept in the set.
Test subsumption between two concepts 3
Predicate.conceptId
Candidate.conceptId
If Candidate concept is a subtype descendant of the predicate concept: TRUE
Otherwise: FALSE
Test a set of concepts for subsumption 3
Predicate.conceptId
Set of candidate.conceptIds
Set of conceptIds of all concepts in the candidate set that have a direct or transitive 116680003 | is a | relationship from the specified concept.
Returns a JSON representation of data about each of the descendant concepts.
The data returned for each concept includes:
All concept release file data
The preferred term and fully specified name.
Also returns the total number of descendant concepts.
Get supertype ancestors of a concept
for example
Encoded URL
Returns a JSON representation of data about each of the ancestor concepts.
The data returned for each concept includes:
All concept release file data
The preferred term and fully specified name.
Also returns the total number of ancestor concepts.
Test subsumption between two concepts
Snowstorm does not provide a specific service for this test, but the test can be accomplished using the Get Concepts service (see ) with a combination of an expression constraint to represent the subsumption requirement and a list of concept identifiers.
For example
Encoded URL
Returns a JSON object with contents that depend on whether the candidate concept is a subtype of the predicate concept:
If it is a subtype descendant the returned object contains:
The property total with value 1; and
An item array that contains data about the candidate concept (as it is the only concept that is both a subtype of the predicate and equal to the candidate concept).
Test a set of concepts for subsumption
Snowstorm does not provide a specific service for this test but the technique used in the row above can be used with all the candidate concept identifiers included in the comma separated list.
For example
Encoded URL
Returns a JSON representation of the candidate concepts that are subtypes descendants of the predicate concept.
If one or more of the predicate concepts are subtypes of the candidate concept the returned object contains:
The property total with value equal to the number of candidate concepts that are subtypes of the predicate concept; and
Get subtype descendants of a concept
Option 1)
for example:
Option 2)
Returns a JSON representation of data about each of the descendant concepts.
The data returned for each concept includes:
code: the code for each descendant
display: the preferred term for each descendant
Also returns the total number of descendant concepts.
Get supertype ancestors of a concept
FHIR does not provide a specific operation for this service, but the supports that retrieval of the ancestors of SNOMED CT concept, and can thus be used to enable this service through the ValueSet/$expand operation.
for example:
Returns a JSON representation of data about each of the ancestor concepts.
The data returned for each concept includes:
code: the code for each descendant
display: the preferred term for each descendant
Also returns the total number of descendant concepts.
Test subsumption between two concepts
for example:
Returns a JSON representation of information about the subsumption relation between the two concepts:
subsumed-by indicates that the concept provided as the value for codeA is a subtype of the concept provided as the value for codeB
subsumes indicates that the concept provided as the value for codeA is a supertype of the concept provided as the value for codeB
Get subtype descendants of a concept
for example
Returns rows containing the id and term for each subtype descendant of the specified concept.
The query shown return the preferred term for each concept
Replace the view suffix _pref with _fsn to return the fully specified name for each concept
Get supertype ancestors of a concept
for example
Returns rows containing the id and term for each supertype ancestor of the specified concept.
The query shown return the preferred term for each concept
Replace the view suffix _pref with _fsn to return the fully specified name for each concept
Test subsumption between two concepts
for example
Returns 1 if the candidate concept is a subtype of the supertype concept.
Test a set of concept for subsumption
Different approaches can be used depending on the specific requirement. As with the options for
Use the get descendants service to generate the list of descendants of the predicate concept and use this list as part of a query for records containing subtypes of that concept;
Individually, apply the test for subsumption between two concepts to each candidate concept;
Extend the ECL query to include all the candidate concepts as illustrated below.
Option 3 will return the ids of concepts in the bracketed list that are subtypes descendants of the predicate concept.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
Data in the definitionStatusId and active columns is represented as symbolic names rather than the boolean and SCTID data types used in release file columns.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of HL7 (www.hl7.org).
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system . It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the SNOMED CT - SQL Practical Guide. For instructions on how to build the example database refer to Appendix A: Building the SNOMED CT Example Database.
Get subtype children of a concept
conceptId
Optionally, language or dialect code
Set of conceptIds of all concepts with a direct 116680003 | is a | relationship to the specified concept.
Optionally additional information such as the fully specified name or preferred term of each concept in the set.
Get supertype parents of a concept
conceptId
Optionally, language or dialect code
Set of conceptIds of all concepts with a direct 116680003 | is a | relationship to the specified concept.
Optionally additional information such as the fully specified name or preferred term of each concept in the set.
Get subtype children of a concept
GET [snowstorm]/browser/[branch]/concepts/[conceptId]/children
for example
GET [snowstorm]/browser/MAIN/2020-01-31/concepts/80146002/children
Encoded URL
GET [snowstorm]/browser/MAIN%2F2020-01-31/concepts/80146002/children
Returns a JSON representation of data about each of the child concepts.
The data returned for each concept includes:
All concept release file data
The preferred term and fully specified name.
Also returns the total number of child concepts.
Get supertype parents of a concept
GET [snowstorm]/browser/[branch]/concepts/[conceptId]/parents
for example
GET [snowstorm]/browser/MAIN/2020-01-31/concepts/80146002/parents
Encoded URL
GET [snowstorm]/browser/MAIN%2F2020-01-31/concepts/80146002/parents
Returns a JSON representation of data about each of the parent concepts.
The data returned for each concept includes:
All concept release file data
The preferred term and fully specified name.
Also returns the total number of parent concepts.
Get subtype children of a concept
FHIR does not provide a specific operation for this service, but the SNOMED CT Expression Constraint Language supports that retrieval of the direct children of SNOMED CT concept, and can thus be used to enable this service through the ValueSet/$expand operation.
GET [fhir]/ValueSet/$expand?url=[editionURI/versionURI]?fhir_vs=ecl/<![predicateSupertypeId]&count=10
for example:
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/<!26322001&count=10
Returns a JSON representation of data about each of the subtype children concepts.
The data returned for each concept includes:
code: the code for each subtype child
display: the preferred term for subtype child
Also returns the total number of children concepts.
As some concepts have very large numbers of children, this service is paged. Requests parameters include:
count to restrict the number of children returned.
offset to specify the start in the results (in multiples of the limit).
Get supertype parents of a concept
FHIR does not provide a specific operation for this service, but the SNOMED CT Expression Constraint Language supports that retrieval of the direct parents of SNOMED CT concept, and can thus be used to enable this service through the ValueSet/$expand operation.
GET [fhir]/ValueSet/$expand?url=[editionURI/versionURI]?fhir_vs=ecl/>![predicateSubtypeId]&count=10
for example:
GET [fhir]/ValueSet/$expand?url=[editionURI/versionURI]?fhir_vs=ecl/>!26322001&count=10
Returns a JSON representation of data about each of the parent concepts.
The data returned for each concept includes:
code: the code for each parent
display: the preferred term for each parent
Also returns the total number of parent concepts.
As some concepts have very large numbers of parents, this service is paged. Requests parameters include:
count to restrict the number of parents returned.
offset to specify the start in the results (in multiples of the limit).
Get subtype children of a concept
SELECT id,term FROM snap_rel_child_fsn WHERE conceptId=[conceptId]
for example
SELECT id,term FROM snap_rel_child_fsn WHERE conceptId=80146002
Returns rows containing the id and term for each subtype child of the specified concept.
The query shown return the fully specified name as the term for each concept
Replace the view suffix _fsn with _pref to return the preferred term for each concept
Get supertype parents of a concept
SELECT id,term FROM snap_rel_parent_fsn WHERE conceptId=[conceptId]
for example
SELECT id,term FROM snap_rel_parent_fsn WHERE conceptId=80146002
Returns rows containing the id and term for each supertype parent of the specified concept.
The query shown return the fully specified name as the term for each concept
Replace the view suffix _fsn with _pref to return the preferred term for each conce
Services Required
Interdependencies
Required By
Depends On
Service Examples
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see IETF RFC1738).
Data associated with available versions of the specified edition:
The name of the edition
Data related to the development branch
Specify a versionededition
REQUIRED
Versioned edition identifier
In most cases, specification of a versioned edition, extended versioned edition or development branch should be an integral part of a request for another terminology service. It simply identifies the terminology substrate to which those requests apply and does not produce specific output.
There are two exceptions to this:
Versioned edition selection services without a request for another service should provide data about the versioned edition (or extended versioned edition), in a similar as specified for the "Get available versions" service.
If the specified version is not accessible, the output should be an appropriate error message.
Specify an extended versioned edition
OPTIONAL
Versioned edition identifier
moduleId(s) and version dates of each of the modules to be included in the extended versioned edition.
Same as above
Specify development branch
DEVELOPMENT
Development branch identifier.
Same as above
Specify a specific versioned edition
for example
Encoded URL
Returns information about the identified versioned edition specified by the branchPath. This includes information about all the modules included in the edition.
In practice the branchPath may refer to an extended versioned edition containing additional modules that are not part of the formally defined edition (see ). In this case, these modules will also be listed.
Other Snowstorm API calls use the same branchPath mechanism to refer to specific versioned editions or development branches.
Specify an extended edition
An edition supplemented by a set of compatible extension modules can be built as a separate schema by importing the full release of the edition and the full release for each of the extension packages required. Once this schema has been built, queries run on that schema provide access to data in that extended edition.
-
Get available versions of an edition
Not required.
Any version of that edition, can be accessed from a schema built using the full release files. The version is accessed simply by specifying an appropriate snapshot date.
-
Specify a specific versioned edition
for example
After applying the two procedure calls shown, queries that refer to views with the prefix snap1_ will be applied to the 2019-07-31 version and queries that refer to views with the prefix snap2_ will be applied to the 2015-01-31 version.
Data associated with available SNOMED CT editions:
The name of the edition
An identifier that can be used to select that edition
See note on input to the "Get available versions" service
Optionally other data including:
Information about the organization responsible for maintenance and distribution
Information about available versions of this edition (as specified for the "Get available versions" service)
Get available versions
REQUIRED
Edition identifier
Notes
Data associated with available versions of the specified edition:
The name of the edition
The version date
An identifier that can be used to select that versioned edition (or extended versioned edition):
See note on input to the "Specify a versioned edition" service
Identifiers of the versioned modules included in that version of the edition.
Optionally:
Information about the organization responsible for maintenance and distribution
Get available editions
GET [snowstorm]/codesystems
Returns JSON representation of all SNOMED CT Editions that are available in the server.
The data for each edition includes a shortname property used to refer that edition in subsequent API calls.
For the International Edition the shortname is "SNOMEDCT".
Get available versions of an edition
GET [snowstorm]/codesystems/[shortname]/versions
for example
GET [snowstorm]/codesystems/SNOMEDCT/versions
Returns JSON representation of each version of the edition specified by shortname that are available in the server.
The data for each edition version includes a branchPath property used to refer that edition in subsequent API calls. For the 2020-01-31 release of the International Edition the branchPath is "MAIN/2020-01-31". The data returned also includes details of the modules in included in each versioned edition.
Note that URL encoding rules requires the / (slash) character to be replaced with %2F. Thus in subsequent API calls the branchPath is represented as MAIN%2F2020-01-31
Get available code systems
GET [fhir]/CodeSystem?_elements=name,url
Returns a JSON representation of the name and URL of each supported code system.
The URL is then used in other commands to specify the code system to be accessed.
Get available editions
Not supported. Available editions are determined by importing each edition into a separate schema.
-
Specify an edition
To select an edition in the SNOMED CT example database it is necessary to build an instance of the database schema using the set of SNOMED CT release files representing a full release of that edition. Once this schema has been built, queries run on that schema provide access to data in that edition.
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see IETF RFC1738).
Snowstorm API
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
FHIR API
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of HL7 (www.hl7.org).
The SNOMED CT MySQL example database is used as an illustration and is not intended for use as a terminology server. In particular, note that the version setting approach described above is not stateless. Configuration changes made by any user apply to all the queries they or other users of the database run. This approach to versioning makes it easier to demonstrate processes that require simultaneous access to current and previous versions of an edition. However, this stateful approach is clearly unsafe in a multiuser environment.
With each new release version of SNOMED CT there are requirements to manage changes in the terminology. One key element of this was covered by the requirements in section Identify Changes to the Terminology. However, in addition to this there is a requirement access data that indicates the reasons for each of those changes and data that, where possible, provides links to active content that replaces components that have been made inactive. This data is distributed in historical reference sets.
An historical reference set is a reference set that provides information about concepts or descriptions that have been inactivated.
Notes
There are two types of historical reference sets :
Inactivation Reference Sets which indicate the reason for inactivation of a particular component.
Historical Association Reference Sets which associate inactive concepts with one or more active concepts that represent the same, similar or a possible meaning of an inactive concept.
As noted in section it is important to identify concepts and descriptions that have been inactivated since an earlier version. Once this has been done:
Information about the reasons for inactivation of each description should be accessed from the
Information about the reasons for inactivation of each concept should be accessed from the
Associations between each inactivated concepts and active concepts which represent similar meanings must be accessed from one of the < subtypes.
The required services are listed in the following table.
Service Name and Status
Input
Output
Use Cases
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
GET [snowstorm]/[branch]/concepts/[conceptId]/descendants
GET [snowstorm]/MAIN/2020-01-31/concepts/80146002/descendants?limit=50&offset=0
GET [snowstorm]/MAIN%2F2020-01-31/concepts/80146002/descendants?limit=50&offset=0
GET [snowstorm]/browser/[branch]/concepts/[conceptId]/ancestors
GET [snowstorm]/browser/MAIN/2020-01-31/concepts/80146002/ancestors
GET [snowstorm]/browser/MAIN%2F2020-01-31/concepts/80146002/ancestors
GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=<[predicateSupertypeId]&conceptIds=[candidateSubtypeId]
GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=<404684003&conceptIds=703264005
GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%3C404684003&conceptIds=703264005
GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=<[predicateSupertypeId]&conceptIds=[candidateSubtypeIdList]
GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=<404684003&conceptIds=703264005,307581005,195967001
GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%3C404684003&conceptIds=703264005%2C307581005%2C195967001
GET [fhir]/ValueSet/$expand?url=[editionURI/versionURI]?fhir_vs=isa/[predicateSupertypeId]&count=10
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=isa/27624003&count=10
GET [fhir]/ValueSet/$expand?url=[editionURI/versionURI]?fhir_vs=ecl/[predicateSupertypeId]&count=10
GET [fhir]/ValueSet/$expand?url=[editionURI/versionURI]?fhir_vs=ecl/<26322001&count=10
GET [fhir]/ValueSet/$expand?url=[editionURI/versionURI]?fhir_vs=ecl/>[predicateSubtypeId]&count=10
GET [fhir]/ValueSet/$expand?url=[editionURI/versionURI]?fhir_vs=ecl/>26322001&count=10
GET [fhir]/CodeSystem/$subsumes?system=[systemURI]&version=[versionURI]&codeA=[conceptId]&codeB=[conceptId]
GET [fhir]/CodeSystem/$subsumes?system=http://snomed.info/sct&version=http://snomed.info/sct/900000000000207008/version/20200131&codeA=307355007&codeB=118940003
SELECT id,term FROM snap_tc_descendant_pref WHERE conceptId=[conceptId]
SELECT id,term FROM snap_tc_descendant_pref
WHERE conceptId=80146002
SELECT id,term FROM snap_tc_ancestor_pref
WHERE conceptId=[conceptId]
SELECT id,term FROM snap_tc_ancestor_pref
WHERE conceptId=80146002
SELECT count(supertypeId) FROM snap_transclose
WHERE supertypeId=[predicateConceptId]
AND subtypeId=[candidateConceptId] WHERE conceptId=80146002
SELECT count(supertypeId) FROM snap_transclose
WHERE supertypeId=80146002 AND subtypeId=6025007
WHERE supertypeId=80146002 AND subtypeId=602500
GET [snowstorm]/codesystems/[branchPath]
GET [snowstorm]/codesystems/MAIN/2020-01-31
GET [snowstorm]/codesystems/MAIN%2F2020-01-31
Get historical associations between an inactive concept and one or more active concepts
Edition and version Identifier of an inactive concept
Optional: Language/dialect 1
Identifiers and term(s) of related active concept(s) and the nature of the historical association between the inactive and active concept.
Get historical associations between an inactive concept and one or more active concepts
for example
Encoded URL
Returns a JSON representation of the historical association(s) of the specified inactive concept.
Each reference set member returned represents a historical association of the inactive concept with an active concept:
The refsetId indicates the specific historical reference set(s) in which associations are found. This represents the nature of the association.
The preferred term and fully specified name associated with the refsetId describe the association. These terms can be looked up using Snowstorm services listed in
Get historical associations between an inactive concept and one or more active concepts
The FHIR TS API supports retrieval of targets for specific SNOMED CT reference sets. Please refer to this document for detailed guidance: . Thus, the ConceptMap/$translate operation enables the retrieval of targets for a specific referenced component.
for example,
Encoded URL
Returns a JSON representation of data about each of the target components.
The data returned for each concept includes:
boolean: True if the concept could be translated successfully. The value can only be true if at least one returned match
match: Each match represents data for the map or associated target. Note that there may be multiple matches, where each element represents a mapTarget. For each mapTarget, following data is provided
Columns
Description
id
Identifier of the inactivated description.
effectiveTime
Effective time of the row that inactivated the description
active
Active state of description. Should always be zero (0)
conceptid
Identifier of the concept to which the description applies
term
Term of the inactivated description
concept_fsn
The fully specified name of the concept.
concept_active
Active state of the concept.
reason
The reason for inactivation represented by the preferred term associated with the valueId concept in the relevant row of the description inactivation reference set.
Get reason for concept inactivation & historical associations
Returns one or more rows of data for each concept inactivated after the deltaStartTime up to and including the deltaEndTime. Each row contains the following columns:
Note that in the case of a concept that has been inactivated due to ambiguity, there will usually be two or more rows in the results, one for each possible meaning represented by an active concepts. However, in some cases it is possible that only one of the possible meanings is represented by an active concept
Columns
Description
id
Identifier of the inactivated concept
effectiveTime
Effective time of the row that inactivated the concept
active
Active state of concept. Should always be zero (0)
definitionStatusId
Definition status of the inactivated concept
FSN
Fully specified name of the inactivated concept
reason
The reason for inactivation represented by the preferred term associated with the valueId concept in the relevant row of the concept inactivation reference set.
assoc_type
The preferred term for the name of the association reference set containing the association between the inactive and active concept.
ref_conceptId
The identifier of the active concept (or one of the active concepts) with which the inactive concept is associated.
ref_concept_FSN
The fully specified name of the active concept with which the inactive concept is associated.
definitionStatusId
Definition status of the inactivated concept
FSN
Fully specified name of the inactivated concept
reason
The reason for inactivation represented by the preferred term associated with the valueId concept in the relevant row of the concept inactivation reference set.
assoc_type
The preferred term for the name of the association reference set containing the association between the inactive and active concept.
ref_conceptId
The identifier of the active concept (or one of the active concepts) with which the inactive concept is associated.
ref_concept_FSN
The fully specified name of the active concept with which the inactive concept is associated.
conceptid
Identifier of the concept to which the description applies
term
Term of the inactivated description
concept_fsn
The fully specified name of the concept.
concept_active
Active state of the concept.
reason
The reason for inactivation represented by the preferred term associated with the valueId concept in the relevant row of the description inactivation reference set.
Get reason for description inactivation
Edition and version Identifier of an inactive description
Optional: Language/dialect1
Identifier and term representing the reason for inactivation of the description.
Get reason for concept inactivation
Edition and version Identifier of an inactive concept
Optional: Language/dialect1
Identifier and term representing the reason for inactivation of the concept.
Get reason for description inactivation
GET [snowstorm]/[branchPath]/members?active=true&referenceSet=900000000000490003|Description inactivation indicator attribute value reference set |&referencedComponentId=[inactiveDescriptionId]
for example
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=900000000000490003|Description inactivation indicator attribute value reference set |&referencedComponentId=78334016
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;referenceSet=900000000000490003%7CDescription+inactivation+indicator+attribute+value+reference+set+%7C&referencedComponentId=78334016
Returns a JSON representation of data related to the specified description.
A single reference set member is returned and the targetComponentId refers to a concept that indicates the reason for inactivation of the concept:
The referencedComponentId returned is the inactive concept to which the inactivation reason applies.
The additionalFields / valueId refers to the concept that indicates the reason for inactivation.
The preferred term and fully specified name associated with the valueId describe the reason for inactivation. These terms can be looked up using Snowstorm services listed in .
Get reason for concept inactivation
GET [snowstorm]/[branchPath]/members?active=true&referenceSet=900000000000489007|Concept inactivation indicator attribute value reference set|&referencedComponentId=[inactiveConceptId]
for example
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=900000000000489007|Concept inactivation indicator attribute value reference set|&referencedComponentId=20559007
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;referenceSet=900000000000489007%7CConcept+inactivation+indicator+attribute+value+reference+set%7C&referencedComponentId=20559007
Returns a JSON representation of data related to the specified concept.
A single reference set member is returned and the targetComponentId refers to a concept that indicates the reason for inactivation of the concept:
The referencedComponentId returned is the inactive concept to which the inactivation reason applies.
The additionalFields / valueId refers to the concept that indicates the reason for inactivation.
The preferred term and fully specified name associated with the valueId describe the reason for inactivation. These terms can be looked up using Snowstorm services listed in
Get reason for description inactivation
N/A
The FHIR TS API does not provide a service for this purpose
Get reason for concept inactivation
N/A
The FHIR TS API does not provide a service for this purpose
Get reason for description inactivation
CALL setDeltaRange(1,[deltaStartTime], [deltaEndTime]);
SELECT * FROM delta_inactive_descriptions;
For example:
CALL setDeltaRange(1,'2019-07-31', '2020-01-31');
SELECT * FROM delta_inactive_descriptions;
Returns a row of data for each description inactivated after the deltaStartTime up to and including the deltaEndTime. Each row contains the following columns:
Columns
Description
id
Identifier of the inactivated concept
effectiveTime
Effective time of the row that inactivated the concept
active
Active state of concept. Should always be zero (0)
Columns
Description
id
Identifier of the inactivated description.
effectiveTime
Effective time of the row that inactivated the description
active
Active state of description. Should always be zero (0)
If required, the refsetId returned can looked up using the get concept service to find the preferred term or fully specified name of the association reference set.
The referencedComponentId returned is the inactive concept to which the association applies.
The additionalFields / targetComponentId represents associated active concept.
In the case of an ambiguous concept, each reference set member represents one possible meaning of the inactive concept.
system: the codesystem of the mapTarget
code: The identifier of the mapTarget
The example shows the retrieval of the active replacement for the inactive concept 134811001 |Anaesthetist (occupation)|. The historical association reference set is the 900000000000527005 |SAME AS association reference set (foundation metadata concept)|, and the request result shows the concept Id of the active concept 88189002 |Anesthesiologist (occupation)|.
GET [snowstorm]/[branchPath]/members?active=true&referenceSet=<900000000000522004|Historical association reference set|&referencedComponentId=[inactiveConceptId]
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=<900000000000522004|Historical association reference set|&referencedComponentId=20559007
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C&referencedComponentId=20559007
GET [fhir]/ConceptMap/$translate?code=[componentId] &system=http://snomed.info/sct &source=http://snomed.info/sct?fhir_vs &target=http://snomed.info/sct?fhir_vs &url=[version]?fhir_cm=[refesetId]
GET [snowstorm]/ConceptMap/$translate?code=134811001&system=http://snomed.info/sct&source=http://snomed.info/sct?fhir_vs&target=http://snomed.info/sct?fhir_vs&url=http://snomed.info/sct?fhir_cm=900000000000527005
GET [snowstorm]/ConceptMap/$translate?code=134811001&amp;amp;amp;system=http%3A%2F%2Fsnomed.info%2Fsct&amp;amp;source=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs&amp;target=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs&url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_cm%3D900000000000527005
Specifying value set bindings that constrain the values that can be entered in a particular data entry context.
Representing an intensional subset definition, which may be used to determine the membership of a reference set
Querying electronic health records for record entries that contain specified sets of concepts and/or expressions
Defining the SNOMED CT concept model by specifying the sets of concepts in a | concept model domains| and the range of values applicable to each attribute.
The Expression Constraint Language - Specification and Guide defines the syntax used to represent expression constraints. It also defines the rules for applying constraints specified using expression constraint language (ECL) to SNOMED CT concepts and expressions.
Effective use of SNOMED CT requires the ability to constrain searches for concepts in a variety of ways. Subtype constraints and reference set membership constraints are identified as specific service requirements in sections Get and Test Concept Subtypes and Supertypes and Get and Test Reference Set Membership. Expression constraints can represent combinations of those constraints. They can also include rules that apply to specific aspects of the definition of a concept. For example, limiting concepts to those that are associated with particular body structures.
Expression constraints can be applied for a range of different purposes. In some cases, these may require enumeration of the set of all the concepts that conform to the constraint, while in other cases it may be more appropriate to apply a specific test to an individual concept. The required services are listed in the table below.
Service Name and Status
Input
Output
Validate an expression constraint
RECOMMENDED
Edition and version
Expression constraint
Error message if expression constraint contains syntax errors
Error message if any concept identifiers in the expression constraint are not present in the specified edition
Get all concepts that conform to an expression constraint
Edition and version
Expression constraint
Optional: Language/dialect
Set of conceptIds of all concepts that conform to the expression constraint
Optionally additional information such as the fully specified name or preferred term of each concept in the set.
Error message if expression constraint contains syntax errors
Not supported as individual service. Limited validation is possible by applying an expression constraint (as shown in next row).
An error message is returned if the expression constraint contains a syntax error. The error message does not indicate the specific cause of the validation error. No error message is shown if a concept identified in the expression constraint is not present in the selective edition or version.
Get all concepts that conform to an expression constraint
The two examples are shown first as the expression constraint complete with the terms for each of the concepts. This is followed by the API service calls in which the terms have been removed (as an optional simplification). The constraint has been URL encoded as required for the REST API.
Bone fractures with sites that are members of the lateralizable body structure reference set
< :
= ^
Encoded URL
Bone fractures with sites that are NOT members of the lateralizable body structure reference set:
< :
!= ^
Encoded URL
Returns a JSON representation of data related to the concepts that conform to the expression constraint.
The data returned for each concept includes:
All concept release file data
The preferred term and fully specified name.
Also returns the total number of concepts that match the constraint.
Service Name
API Call 5
Result
Validate an expression constraint
N/A
Not supported as indi vidual service. Limited validation is possible by applying an expression constraint (as shown in next row).
Get all concepts that conform to an expression constraint
Example 1
Bone fractures with sites that are members of the lateralizable body structure reference set
< :
=^
Encoded URL
Example 2
Bone fractures with sites that are NOT members of the lateralizable body structure reference set
< : != ^
Returns a JSON representation of data about each of the concepts in the specified version that conform to the expression constraint.
The data returned for each concept includes:
code: the conceptId of the reference set member
display: the preferred term for the reference set member
Also returns the total number of reference set members
Service Name
SQL Query
Result
Validate an expression constraint
Not supported.
Get all concepts that conform to an expression constraint
Examples
Bone fractures with sites that are members of the lateralizable body structure reference set
Bone fractures with sites that are members of the lateralizable body structure reference set
Returns a row of data containing the conceptId and term for each concept that conforms to the constraint.
If the expression constraint is invalid, no rows are returned.
This and the following service examples can also use the following alternative procedure calls:
The procedure eclQueryCount() sets a count output parameter with the number of concepts that match the constraint.
The procedure eclSelect() returns the concepts that match the constraint in a specified style. Styles include: exp (expression with preferred term), expfsn (expression with FSN), pref (id, preferred term), fsn (id,FSN), allsyn (id,synonym - one row per synonym).
The procedure eclGetIds() outputs the concept identifiers to rows in the table config_resultsets with keyed by by a specified setId. This allows other queries or procedures to access the results.
Footnotes
The validation service is recommended rather than required as minimal validation can be provided by attempting to apply the expression constraint. However, a validation service that reports specific errors, is required for use cases that involve creating or editing expression constraints (e.g EHR Data Entry Design).
Language and/or dialect should be specified if the service returns terms associated with referenced concepts.
The test service is recommended rather than required because this can be delivered by the get service simply by adding an additional constraint as shown in the Snowstorm illustration.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of ().
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system. It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the . For instructions on how to build the example database refer to .
Snowstorm expression validation has been raised as an open issue see .
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
Snowstorm API
FHIR API
MySQL Example Database
Terminology Change Management
The following sections present terminology services use cases related to the management of terminology changes.
Access Details of Terminology Changes
SNOMED CT has rich versioning mechanism that retains the full history of changes to every component and reference set member. As a result, it is possible to review the content of the terminology as it was at any time in the past and to make comparisons between two versions. In addition to tracking the state of the terminology at specific times in the past, the versioning mechanism also provides and indication of the reason for inactivation of each concept or description. In the case of concepts, there is also data linking inactive concepts to active concepts that may be used to replace them.
Services Required to Access Details of Terminology Changes
The following table shows the terminology services required to access each of these different types of versioning data.
Practical Requirement
Required Services
Dependencies
The services described in 'Access Details of Terminology Changes' get versioning data related to the addition, modification, or inactivation of individual terminology components. Many practical uses of this data require interpretation of the overall effect of a combination of changes to a concept. Therefore, it may be useful to integrate versioning data in ways that facilitate a review of the impact of these changes. A possible way to achieve this is illustrated by the data model in the diagram below
A data structure of this type could be used to assist the identification of changes relevant to managing the impact of changes on EHR applications and Extensions in two ways:
By generating a human-readable version of the change data for use in manual review of existing data
As a computer processable resource from which queries can be generated to search records, user interface templates, reporting, and analytics queries and extensions for references for changed or inactivated concepts and descriptions.
Each instance of the Component Version Data object represents the previous and new states of an identified concept, description, relationship or OWL axiom reference set member that has been added, changed, inactivated or reactivated between two specified versions of the same edition.
Component Version Data Object
Details of the data items in the example Component Version Data object are shown in the following table.
Data Item
Notes
There is an instance of the Full Concept Version Data object for each concept to which one or more of the following conditions applies:
The concept has been added, changed, inactivated or reactivated
OWL axioms or relationships that contribute to the stated and/or inferred definition of the concept have been added, changed, inactivated or reactivated
Descriptions associated with the concept have been added, changed, inactivated or reactivated
Each instance of the Full Concept Version Data object represents the previous and new state of a concept including all its active descriptions (with relevant language acceptability data), all its active relationships and all associated active OWL axioms.
Full Concept Version Data Object
Details of the data items in this object are shown in the following table.
Data Item
Notes
The table below summarizes change management issues that may affect and EHR application when moving to a new version of a SNOMED CT edition. It also outlines approaches to checking for and resolving issues of different types.
Change Type
Significance
Risks
Factors Affecting Risk Level and Likely Impact
Change Management Actions
Step
Input
Output Description
Output Name
Output Name
Description
Impact
Recommended Action
The following table summarizes change management issues that may affect and EHR application when moving to a new version of a SNOMED CT edition. It also outlines approaches to checking for and resolving issues of different types.
Change Type
Significance
Examples of Potential Impact
Change Management Actions
Get Terms for a Concept
Each concept is associated with descriptions. Each description is an association between a human-readable phrase (term) and a particular SNOMED CT concept.
There are different types of descriptions and there may be descriptions of each of the following types in several languages:
A synonym is a word or phrase that expresses the meaning of a SNOMED CT concept in a specified language.
Synonyms are terms that represent the meaning of the concept in a way that is familiar and readily understandable. However, when taken out of context a synonym may not be unambiguous and in some cases the same term may be associated with more than one concept.
Note that the ECL memberOf function needs to be url encoded. The URL encoding for ^ is %5E
As some expression constraints are matched by large numbers of concept, this service is paged. Requests parameters include:
limit to restrict the number of concepts returned (default 50).
offset to specify the start in the results (in multiples of the limit).
With the data from the 2020-01-31 International release
The first example returns 1442 concepts.
The second example returns 737 concepts.
If the expression constraint contains a syntax error, the returned data is an error message.
Encoded URL
As some expression constraints are satisfied by many concepts, this service is paged. Requests parameters include:
count to restrict the number of members returned.
offset to specify the start in the results (in multiples of the limit).
Example 1 returns 1442 concepts.
Example 2 returns 737 concepts.
Test if a specific concept conforms to an expression constraint
RECOMMENDED
Edition and version
Expression constraint
Candidate concept identifier
A true or false result depending on whether the candidate concept conforms to the constraint
Test if a specific concept conforms to an expression constraint
The service used for getting concepts that conform to an expression constraint can be adapted to test whether one or more specific concepts conform to the constraint by simply extending the constraint so it also constrains the results to only include the specified concept(s).
Test if fracture of mandible (jaw bone) is a bone fracture with a site that is a member of the lateralizable body structure reference set
GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=(<125605004: 363698007=^723264001) and (71620000)
Encoded URL
Test if osteomyelitis of femur is a bone fracture with a site that is a member of the lateralizable body structure reference set
(< :
= ^ ) and ( )
Encoded URL
Returns a JSON representation of data related to the concept if it conforms to the expression constraint as described above.
When testing a single candidate concept the value of the property total is sufficient to tell whether the candidate concept conforms to the constraint:
Fracture of mandible total: 0
It is a subtype fracture of bone but the mandible is not lateralizable
Fracture of femur total: 1
It is a subtype fracture of bone and the femur is lateralizable (there a left femur and a right femur)
Osteomyelitis of femur total : 0
Femur is lateralizable and is the finding site but the osteomyelitis is not a subtype of fracture.
Test which of a specific set of concepts conform to an expression constraint
The technique used for testing whether a single concept conforms to an expression constraint can also be used to determine which members of a specified set of concepts conform to that constraint. In the case each of the member of the set of candidates is included in the constraint as shown below:
GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=(<125605004: 363698007=^723264001) and (263172003 or 71620000 or 15510011551001 or 37449000)
Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%28%3C125605004%3A+363698007%3D%5E723264001%29+and+%28263172003+or+71620000+or+15510011551001+or+37449000%29
Returns a JSON representation of data related to concepts in the set that conforms to the expression constraint.
The example shown returns an array containing data about the following concepts:
The /ValueSet/$validate-code operation can be used to test whether a concept is included in a specific value set, where the value set is identified as an implicit value set.
GET [fhir]/ValueSet/$validate-code?system=http://snomed.info/sct&code=[conceptId]&url=[versionURI]?fhir_vs=ecl/[expressionConstraint]
Example 3
Test if fracture of mandible (jaw bone), 263172003|Fracture of mandible|, is a bone fracture with a site that is a member of the lateralizable body structure reference set.
The subset of concepts that are bone fractures with a site that is a member of the lateralizable body structure reference set can be determined by the following expression constraint:
GET [fhir]/ValueSet/$validate-code?system=http://snomed.info/sct&code=1551001&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<125605004: 363698007=^723264001
Encoded URL
GET [fhir]/ValueSet/$validate-code?system=http%3A%2F%2Fsnomed.info%2Fsct&amp;code=1551001&url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C125605004%3A%0A363698007%3D%5E723264001
Example 4
Test if fracture of femur (thigh bone), 71620000 |Fracture of femur|, is a bone fracture with a site that is a member of the lateralizable body structure reference set
Encoded URL
Returns a JSON representation of data about whether the concept is included in the set.
result: true, if the concept is included and false if the concept is not included
display: the display term for the concept
With the data from the 2020-01-31 International release
Example 3
result: false
Example 4
Test which of a specific set of concepts conform to an expression constraint
The /ValueSet/$validate-code operation only supports testing whether a single concept conforms to an expression constraint. Therefore, to determine which members of a specified set of concepts conform to an expression constraint, a dedication expression constraint needs to be designed to enable this test. In this case, each member of the set of candidates is included in the expression constraint as shown below:
([intensionalDefinition])AND([candidate1] OR [candidate2] OR [candidate3] OR ...[candidateN])
The following general request template will test which of the candidates matches the expression constraint represented in the [intensionalDefinition]
GET [fhir]/ValueSet/$expand?system=http://snomed.info/sct&code=[conceptId]&url=[versionURI]?fhir_vs=ecl/[expressionConstraint]
Example 5:
Test which of the following concepts is a bone fracture with a site that is a member of the lateralizable body structure reference set
263172003 |Fracture of mandible|
71620000 |Fracture of femur|
1551001 |Osteomyelitis of femur|
37449000 |Open fracture of ulna|
(< :
= ^ ) and ( or or or )The resulting FHIR request:
Encoded URL
Returns a JSON representation of data about each of the candidate concepts that conform to the expression constraint.
The data returned for each concept includes:
code: the conceptId of the reference set member
display: the preferred term for the reference set member
Also returns the total number of concepts satisfying the expression constraint.
Note: If none of the candidate concepts which are tested for membership are included in the reference set, the service will return 0 results.
The request in Example 5 shows that the following two concepts conform to the expression constraint:
71620000 |Fracture of femur|
37449000 |Open fracture of ulna|
Test if a specific concept conforms to an expression constraint
call eclQuery(([expressionConstraint]) and ([conceptId]))
for example
call eclQuery("(<125605004=^723264001) AND (71620000)")
If the concept conforms to the constraint, this returns a row of data containing that conceptId and its term. If it does not conform, no rows are returned.
Test which of a set of specified concepts conform to an expression constraint
call eclQuery("(<125605004:363698007=^723264001) AND (71620000) or (15510011551001) or (37449000)")
Returns the conceptId and term for concepts in the set that conform to the expression constraint.
GET [snowstorm]/snomed-ct/[branchPath]/concepts?activeFilter=true&ecl=[expressionConstraint]
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&ecl=<125605004:363698007=^723264001
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&ecl=%3C125605004%3A363698007%3D%5E723264001
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&ecl=<125605004:363698007!=^723264001
GET [fhir]/ValueSet/$expand?url=[versionURI]?fhir_vs=ecl/[expressionConstraint]
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<125605004: 363698007=^723264001
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C125605004%3A%0A363698007%3D%5E723264001
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<125605004: 363698007!=^723264001
SELECT call eclQuery([expressionConstraint])
call eclQuery("<125605004|Fracture of bone|:
363698007|Finding site| = ^723264001|Lateralizable body structure reference set|")
call eclQuery("<125605004|Fracture of bone|:
363698007|Finding site| = ^723264001|Lateralizable body structure reference set|")
GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&ecl=%3C125605004%3A363698007%21%3D%5E723264001
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C125605004%3A%0A363698007%21%3D%5E723264001
Identify descriptions that have been inactivated between the specified versions.
REQUIRED
Description
Get description by identifier
Get inactivation reason for each inactive description
REQUIRED
Description inactivation reference set
N/A
Get changes to inferred definitions
OPTIONAL
Relationship
Get inferred necessary normal form definition of a concept
Get relationship by identifier
Get changes to stated definitions
OPTIONAL
OWL reference set
Get stated definition of a concept
OWL reference set
newComponentData
The ComponentData for the identified component in the snapshot release of the later of the two versions being compared.
ComponentData refers to a representation of the data in the relevant release file row for the identified concept, description, relationship or OWL axiom.
In the case of a description, the ComponentData should also include the acceptability values for that description in the language reference sets of that snapshot release.
previousComponentData
Represents the release file data for the identified component in the earlier of the two versions being compared.
Empty if the component was not present in the earlier version of the release file.
reason
Only applicable to concepts and descriptions that are active in the previousComponentData view and inactive in the newComponentData view:
In the case of a concept, the reason for inactivation as represented in the concept inactivation reference set.
In the case of a description, the reason for inactivation as represented in the description inactivation reference set.
alternatives
Only applicable to concepts that inactive in the newComponentData view:
An array of historically associated concepts derived by selecting active rows from most recent snapshot view the historical association reference sets with a referenceComponentId that matches the identifier of the concept.
Each element of the array should include the refsetId, which indicates the type of association, and the targetComponentId, which refers to associated concept.
conceptId
The identifier of the concept with which this component is associated. This provides a link to the id of the relevant Complete Concept Version Data.
In the case of a concept, this is the same as the id (i.e. same as the id data item above).
In the case of a description, this is the conceptId.
Language reference set rows that specify the acceptability of an associated description have been added, changed, inactivated or reactivated.
Addition of a concept
MODERATE
Inconsistent reporting and analytics may occur if a new concept is omitted from reporting query criteria.
• Risk is higher when queries use fixed reference sets or lists.
• Hierarchy-based queries are more likely to include relevant new concepts.
• Review and revise reporting query criteria to ensure they include the new concepts where appropriate.
Inactivation of a concept
HIGH
Inactive concepts may still be referenced by UI bindings, causing errors:
• Inactive concept might still be selectable (serious error)
• Or it might be blocked entirely, making it impossible to enter needed data.
• High risk with fixed value sets or individual concept lists.
• Lower risk when using hierarchy-based constraints (which auto-exclude inactive concepts).
• Identify UI bindings referencing inactive concepts.
• Replace references with active concepts using historical associations.
• Ensure updates only apply to new entries to preserve legal record integrity.
Inactivation of a concept
HIGH
Inactive concepts in query criteria can significantly change query results.
• High risk if used in subsumption constraints.
• Lower risk if referenced directly.
• Check and revise query criteria that reference inactivated concepts.
• Adjust queries to continue delivering intended results.
Inactivation of a concept
HIGH
Inactive concepts may still exist in EHR records from earlier data entry. These will no longer be subsumed or included in relevant queries.
• Especially problematic if concept was inactivated due to ambiguity (no direct replacement).
• Options:
– Explicitly include the inactive concept in queries
– Create reference sets of formerly-included inactive concepts
– Use historical associations to extend subsumption
– Accept exclusion where appropriate
– Add mapped active concept (as a supplement, not a replacement)
Change to a concept
NONE
Only definitionStatusId can change, indicating redefinition. Not significant by itself.
-
-
Addition of a description
LOW
New display term added. Minimal impact unless tied to inactivation or changes in acceptability.
• If preferred/acceptable terms are removed, the new term may need to be adopted.
• By default, preferred term in target language is displayed.
• Evaluate whether the new description should be used in data entry templates or reports.
• Existing records remain unaffected.
Change to a description
LOW
Term or caseSignificanceId might change. May affect display consistency.
• QA rules limit term changes.
• Display logic might be impacted.
• Review and update data entry templates or reports that display the changed term.
• Ensure correct casing per caseSignificanceId.
Note: Stored records typically should not be changed.
Inactivation of a description
HIGH
Inactivated descriptions can't be used as display terms for data entry or reporting.
• Especially impactful if no acceptable alternative term is defined in the language reference set.
• Replace use of inactive terms in UI and reporting templates with preferred or acceptable alternatives.
• Don't retroactively modify stored records.
Change to acceptability of a description
MODERATE
Description that is no longer acceptable in a language/dialect should not be used as display term.
• Impacts systems with multilingual language bindings.
• Review language reference sets used by the system.
• Ensure display terms remain acceptable/preferred.
Changes to relationships or OWL expressions
MODERATE
These changes alter concept definitions, which may impact expression constraints and queries.
• Queries based on subsumption or logical definitions may behave differently.
• Review all expression constraints, value sets, and queries.
• Revalidate and adjust per guidance in Tables 3.7.3-2 and 3.7.3-3.
Changes to reference set members
MODERATE
Additions or inactivations of members may change inclusion in queries and templates.
• Can affect data entry templates, reporting outputs, or analytics logic.
Apply the Expression Constraint (ECL) to each version to identify subsets of concepts that conform to the constraint
V1-snapshot
Set of concepts in V1-snapshot that conform to the ECL
V1-ECL-result
V2-snapshot
Set of concepts in V2-snapshot that conform to the ECL
V2-ECL-result
Compare the subsets to identify concepts that conform in one version but not the other
V1-ECL-result
Concepts in V1-ECL-result but not in V2-ECL-result
V1-ECL-only
V2-ECL-result
Concepts in V2-ECL-result but not in V1-ECL-result
V2-ECL-only
Subdivide V1-only concepts by active status in the new version
V1-ECL-only
Concepts in V1-ECL-only that are active in V2-snapshot
V1-ECL-only-V2-active
V1-ECL-only
Concepts in V1-ECL-only that are inactive in V2-snapshot
V1-ECL-only-V2-inactive
Subdivide V2-only concepts by status in or absence from the old version
V2-ECL-only
Concepts in V2-ECL-only that are active in V1-snapshot
V2-ECL-only-V1-active
V2-ECL-only
Concepts in V2-ECL-only that are inactive in V1-snapshot
V2-ECL-only-V1-inactive
V2-ECL-only
Concepts in V2-ECL-only that are absent from V1-snapshot
V2-ECL-only-V1-absent
LOW
If this subset contains any concepts, be aware that this may affect result of rerunning an earlier reports or analytics on retrospective data. However, in most cases no action is required.
V2-ECL-only-V1-active
Concepts that only conform to the ECL in V2 although they are active in both versions. Retrospective reports will now include concepts that were previously excluded from the report.
HIGH
Concepts in this subset will be included in reports or analytics performed after upgrading to the new version but would not have been included when using the current version.
This may be due to an revision of concept definitions or addition of concepts to a reference set. Assuming these changes were intentional improvements the revised result should be more accurate and more complete.
In some cases, this type of change may have unintended consequences. Therefore a review of the context in which these constraints are used is recommended. If necessary the constraint can then be refined to exclude some or all of the added concepts.
V1-ECL-only-V2-active
Concepts that only conform to the ECL in V1 although they are active in both versions. Retrospective reports will now exclude concepts that were included in the report.
HIGH
Concepts in this subset will be excluded from reports or analytics performed after upgrading to the new version but would have been included when using the current version.
This may be due to an revision of concept definitions or removal of concepts from a reference set. Assuming these changes were intentional improvements the revised result should be more accurate.
In some cases, this type of change may have unintended consequences. Therefore a review of the context in which these constraints are used is recommended. If necessary the constraint can then be refined to specifically include some or all of the excluded concepts.
V1-ECL-only-V2-inactive
Concepts that only conform to the ECL in V1 that are inactive in V2. In this case, inactivation of the concept means that retrospective reports will exclude these concepts that were previously included in the report.
MODERATE
Concepts in this subset will be excluded from reports or analytics performed after upgrading to the new version but would have been included when using the current version.
In this case, the reason for exclusion is that the concept is inactive rather than being a direct consequence of the constraint. There are two ways to enable an inactive concept to conform to a constraint. A direct reference to a concept identifier or a reference to the members or a reference set that includes that concept.
MODERATE
A new concept may be a supertype of an extension concept.
Classification may infer new subtype relationships. But if the extension's definition lacks necessary axioms, the new relationship won't be inferred.
Review new concepts to identify if they should subsume any extension concepts. If so, update the extension concept's definition with additional axioms to support accurate classification.
MODERATE
If the extension includes a language reference set, additions are required for acceptability of new concept descriptions.
Add necessary descriptions in the relevant language/dialect. Update the language reference set to include the new fully specified name and preferred term.
Inactivation of a concept
HIGH
A component or reference set member in the extension may reference an inactivated concept in the base module.
Concept definitions must not reference inactive concepts.
• Remove inactive concept references from OWL expressions and active relationships.
• Descriptions may still reference inactive concepts for display purposes.
HIGH
Reference sets like OWL or Mapping sets must be reviewed.
Inactivate or replace refset members that refer to inactive concepts. Update OWL reference set rows. Reclassify to confirm no active relationships point to inactive concepts.
Addition of a description
NONE
No impact unless the extension uses a language reference set.
-
MODERATE
A new description may need to be reflected in the extension's language reference set.
Consider adding the new description as an acceptable term in the extension's language refset.
Inactivation of a description
LOW
References to inactivated descriptions in refsets may be affected.
Review and update reference sets that refer to now-inactive descriptions.
MODERATE
If the description is referred to in a language reference set as a preferred term or FSN, updates are required.
• Inactivate reference set members pointing to inactive descriptions.
• If the inactivated term was "preferred", add a new active preferred description of the same type.
• Do not overwrite inactive descriptions — add replacements.
Changes to concept definitions
NONE
No impact unless the extension contains additional clinical concepts.
-
HIGH
Changes to the base module's concept model or specific definitions may affect extension definitions.
• Review and update impacted extension concept definitions.
• Align with changes in the base module.
• Reclassify to maintain consistency.
Enable the selection of SNOMED CT edition and the versions of that edition to be compared
REQUIRED
Identify concepts that are candidates to replace each inactivated concept
REQUIRED
componentType
Indicates whether the component is a concept, description, relationship (part of the inferred view of the concept definition), or OWL axiom (part of the stated view of the concept definition).
action
Indicates the nature of the change:
added : This component was not present in previous release
changed : The active value is unchanged and change has been made to a data value
inactivated : The active value of the component has been changed from 1 to 0
reactivated : The active value of the component has been changed from 0 to 1
id
The identifier of the concept, description, relationship or OWL axiom reference set member.
id
The identifier of a concept that has been affected directly or indirectly by updates between two specified versions of the same edition.
newFullConceptData
A representation of the FullConceptData for the identified concept in the snapshot release of the later of the two versions being compared.
FullConceptData represents all pertinent active release file entries that describe and define a specific concept.
This includes all the data in:
the row of the concept snapshot release file with the relevant id value.
all active rows of the description snapshot release file with a conceptId value matching the identifier of the concept and for each of these descriptions
and all active rows of the language reference set snapshot release file with the a referencedComponentId value matching the identifier of that description
all active rows of the relationship snapshot release file with a sourceId value matching the identifier of the concept.
all active rows of the OWL reference set snapshot release file with refsetId and a referencedComponentId value matching the identifier of the concept.
The data should be represented in a way that supports the data structures of all of the above data components. For example, the data could be represented as the string serialization of a JSON object combining representations of each of the different data items.
previousFullConceptData
A representation of the FullConceptData for the identified concept in the snapshot release of the earlier of the two versions being compared.
Empty if this concept was not present in the earlier release.
Addition of a concept
MODERATE
The new concept may not be available in some data entry contexts.
Although all new concepts will be available for ad-hoc searches, it may not be possible to enter a new concept in data entry fields with tightly defined value set bindings.
• Risk is higher if the value set binding specifies members of a reference set or individual concepts.
• Hierarchy-based constraints are more likely to include new concepts automatically.
Identify snapshot views of two versions of the same SNOMED CT edition
Current edition
Edition in use before planned update
V1-snapshot
V2-ECL-only-V1-absent
New concepts in V2 release that were not present in V1.
Inclusion of these concepts will not affect retrospective reports or analytics because the new concepts could not have been used previously.
Inclusion of these new concepts is appropriate as they conform to the stated constraint.
NONE
None
V2-ECL-only-V1-inactive
Addition of a concept
MODERATE
A new concept in a module on which the extension depends may have the same meaning as an existing concept in the extension.
Consider inactivating the extension concept and create a historical association from it to the new concept in the base module.
Integrate and Interpret Versioning Data
Full Concept Version Data
Manage Impact of Changes on EHR Applications
Impact of Version Updates on EHR Applications
Comparing Results of Applying an Expression Constraint to Two Versions of a SNOMED CT Edition
Check the content of the five sets of concepts generated by the last two steps using the notes in the following table.
Evaluation of Differences between ECL Results
Manage Impact of Changes on Extensions
The changes outlined in this section must be applied when an extension module is updated to align with the new versions of the modules on which it depends. Before an updated extension module is released, updates must also be made to its module dependencies. Please refer to the Extensions Practical Guide for more detailed information about extension modules and the Module Dependency Reference Set.
• Review newly added concepts, especially those in frequently used hierarchies.
• Consider if new concepts should be added to reference sets, search constraints, UI bindings, or queries.
Recommendation: Use hierarchy constraints rather than fixed concept lists to reduce manual maintenance.
New edition
It is unusual for concepts to be reactivated so this set will usually be empty.
Concepts reactivated in V2 release after being inactive in V1 release. However, in theory this could alter the result of retrospective reports because reactivation of the concept causes these concepts to be included whereas previously they were excluded.
Each concept has at least one synonym and a concepts may have several synonyms. One of the synonym descriptions in each language is marked as the preferred term for the associated concept and others may be marked as acceptable for use. The preferred term is the term deemed to be the most clinically appropriate way of expressing a concept in specified language context.
A fully specified name is a description that represents the meaning of a concept in a way that is unambiguous and independent of the context in which it is used.
Fully specified names are essential for disambiguation of the meaning of a concept. These term used in the fully specified name includes a hierarchy tag that specifies the branch of the SNOMED CT hierarchy the concept is in. The hierarchy tag is enclosed in brackets at the end of the term.
There is only one fully specified name in each language. In some languages there may not be a fully specified name, in which case the English fully specified name may be used where necessary for disambiguation.
A text definition is a narrative text explanation of the meaning of a concept that may exceed the maximum permitted length for a fully specified name.
Text definitions are only included for some concepts where longer terms are deemed to be necessary or useful to add clarity to the meaning of the concept.
Terminology services must enable access to the term in each active description associated with an identified concept. They should also be able to selectively filter the descriptions for which terms are returned based on the following criteria:
Active status (description.active)
Inactive descriptions associated with a concept should not be returned unless explicitly requested.
Description type (description.typeId)
Fully specified name
Synonyms (including the preferred term)
Textual definitions (and other types where these are used)
Acceptability in a specified Language Reference Set
Preferred: To access the fully specified name or preferred term
Acceptable: To access synonyms
The required services are listed in the table below.
Service Name and Status
Input
Output
Get fully specified name of a concept
Edition and version
Concept identifier
Language refset set identifier (optional)
Description not found: Return appropriate error message
Description found: Return data associated with the description:
Required: id, term, caseSignificanceId
Get preferred term of a concept
Edition and version
Concept identifier
Language refset set identifier (optional)
Description not found: Return appropriate error message
Description found: Return data associated with the description:
Get fully specified name of a conceptGet preferred term of a concept
for example
Encoded URL
Returns a JSON representation of data about the selected concept. This include both the fully specified name and the preferred term.
This is the same Snowstorm API call used in to get the concept by identifier. If the fully specified name and/or preferred term there is no need for a specific service to get these terms.
Get all terms for a concept
for example
Encoded URL
Returns a JSON representation of data about all descriptions in the selected edition and version that are associated with the concept specified.
The descriptions returned include:
Active and inactive descriptions
All types of descriptions
Service Name
API Call
Result
Get all descriptions for a concept
for example
Returns a JSON representation of data about the selected concept. This include both the fully specified name and all synonyms of the concept.
This is the same FHIR API call used in to get concept by identifier. If the fully specified name and/or preferred term there is no need for a specific service to get these terms.
Service Name
API Call
Result
Get fully specified name of a concept
for example
Returns the fully specified name of a specified concept and its caseSignificanceId.
Get preferred term of a concept
for example
Returns the preferred term of a specified concept and its caseSignificanceId
The services described in require access to data about individual components based on their unique identifiers. Therefore, a service that gets a description is only required to return the data in the identified description. However, some implementations of those services may also meet some of the requirements for getting terms associated with a concept.
Services that get concepts may also return some or all of the terms associated with the selected concept.
Services Required
Interdependencies
Required By
Depends On
This service requires access to description acceptability data in a language reference set. This could be regarded as a dependency on . However, access to language reference set data is an essential part of the process of displaying appropriate terms for a concept. Therefore access to the language reference set is included as an integral part of this service and is not declared as a distinct dependency.
Service Examples
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
Snowstorm API
Snowstorm supports selection of the language(s) in which terms will be returned. This is specified using HTTP request header Accept-Language. The values used with this include the identifiers of the language reference sets to be applied.
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system . It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the .
Support EHR Data Entry
An electronic health record (EHR) that represents clinical information using SNOMED CT must support efficient entry of data accurately coded as SNOMED CT concepts and/or expressions. Data entry approaches need to be tailored to fit the needs of different healthcare professionals in a variety of clinical situations. However, the end results of different data entry techniques must be record entries that are consistent and comparable. The following sections outline the ways in which terminology services can be used to support the design and application of effective data entry techniques.
This section provides a general introduction to the terminology service requirements related to EHR data entry. It outlines the rationale for the following sections on data entry design and practical data entry.
Readers of this section of the guide are advised to read the following sections of the
- describes effective ways to optimize SNOMED CT searches.
Descriptions in all languages that are present in the selected edition
The data return for each description includes all data present in the description release file and acceptability data derived from language reference sets. The following items have specific roles in filtering descriptions and presenting the terms they contain:
The active value (true or false) can be used to exclude inactive descriptions.
The typeId value can be used to filter descriptions of specific types.
The additional a text token type provides a human readable representation.
The lang value contains the language code and this can be used to filter descriptions.
The acceptabilityMap contains text tokens for the acceptability of the description in one or more language reference sets.
The caseSignificance value contains a text token indicate whether all or part of a term is case-sensitive. This can be used to enable the case of a term to be adjusted to fit the context of use except in when this would be incorrect or liable to alter the meaning.
For example, the Snowstorm service that retrieves an identified concept also returns the fully specified name and preferred term for that concept in one language.
Similarly, the FHIR service returns a single display term and may optionally also return other associated terms as designations.
Services that get relationships may also return terms associated with the concepts identified by those relationships.
Get all terms for a concept
Get the terms from all descriptions associated with a concept
REQUIRED
Edition and version
Concept identifier
Include inactive descriptions (optional)
Descriptions not found: Return appropriate error message
Descriptions found: Return data associated with each of the descriptions found
This data must include the id, term, active status, description type, language code and case sensitivity
It should also include the acceptability of the term in one or more language reference sets
Get filtered terms for a concept
Get terms from descriptions associated with a particular concept filtered by one or more of the following
Status of the description (active: 1=true, 0=false)
Term (term: matching a phrase or pattern)
Description type (typeId: fully specified name, synonym, textual definition)
Language (languageCode)
Acceptability in a specified language reference set (refset.acceptabilityId: preferred, acceptable)
CONDITIONAL
Edition and version
Concept identifier
Filters
Active
TypeId
Language code
Language refset identifier
Language refset acceptability
Descriptions not found: Return appropriate error message
Descriptions found: Return data associated with the descriptions found
This data must include the id, term and case sensitivity
It must also include the term, active status, description type, language code
Get filtered terms for a concept
Use the API call above to get all terms for a concept and then filter using the returned data.
Same as above
Get all synonyms of a concept
for example
Returns all the preferred term of a specified concept and with their caseSignificanceId values.
Get all terms for a concept
for example
Returns all descriptions of all concepts together with all the data for each of those descriptions in the concept file.
Set language configuration
for example
After this setting is made all references to views including the prefix snap_ and the suffixes _fsn, _pref, _syn, _synall will use the language reference set for GB English (rather than the default language US English).
Other languages supported by the the installed Edition can also be specified in a similar way.
GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%28%3C125605004%3A+363698007%3D%5E723264001%29+and+%2871620000%29
GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=(<125605004: 363698007=^723264001) and (1551001)
GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%28%3C125605004%3A+363698007%3D%5E723264001%29+and+%281551001%29
GET [fhir]/ValueSet/$validate-code?system=http://snomed.info/sct&code=71620000&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<125605004: 363698007=^723264001
GET [fhir]/ValueSet/$validate-code?system=http%3A%2F%2Fsnomed.info%2Fsct&amp;code=71620000&url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C125605004%3A%0A363698007%3D%5E723264001
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/(<125605004: 363698007=^723264001) and (263172003 or 71620000 or 1551001 or 37449000)
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%28%3C125605004%3A%0A363698007%3D%5E723264001%29+and+%28263172003+or+71620000+or+1551001+or+37449000%29
SELECT term,caseSignificanceId FROM snap_synall WHERE conceptId=[conceptId]
SELECT term,caseSignificanceId FROM snap_synall WHERE conceptId=6025007
SELECT * FROM snap_description WHERE conceptId=[conceptId]
SELECT * FROM snap_description WHERE conceptId=6025007
CALL setLanguage([configId],[languageCode]);
CALL setLanguage(0,'en-GB');
GET [snowstorm]/[branchPath]/concepts/[conceptId]
GET [snowstorm]/MAIN/2020-01-31/concepts/6025007
GET [snowstorm]/MAIN%2F2020-01-31/concepts/6025007
GET [snowstorm]/[branchPath]/concepts/[conceptId]/descriptions
GET [snowstorm]/MAIN/2020-01-31/concepts/6025007/descriptions
GET [snowstorm]/MAIN%2F2020-01-31/concepts/6025007/descriptions
GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct&code=[conceptId]
GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct&code=6025007
SELECT term,caseSignificanceId FROM snap_fsn WHERE conceptId=[conceptId]
SELECT term,caseSignificanceId FROM snap_fsn WHERE conceptId=6025007
SELECT term,caseSignificanceId FROM snap_pref WHERE conceptId=[conceptId]
SELECT term,caseSignificanceId FROM snap_pref WHERE conceptId=6025007
The data should be represented in a way that supports the data structure of the specified componentType. For example, the data could be represented as the string serialization of a JSON object.
In the case of a relationship, this is the sourceId.
In the case of an OWL axiom, this is the referencedComponentId.
EHR Data Entry Overview - describes a range of techniques that facilitate the effective recording of SNOMED CT concepts or expressions in health records.
Entry of data into an Electronic Health Record (EHR) requires access to services that enable the user to rapidly locate and select the concepts and terms that need to recorded. There are a wide range of different EHR data entry scenarios determined by the type of healthcare encounter and the reason for that encounter. A typical data entry scenario involves recording data in different data entry contexts. The data entry contexts are typically distinguished by section headings (e.g. "Surgical History"), individual data item labels (e.g. "Initial Diagnosis") and in some case by specific questions with a limited range of answers (e.g. "Family history of heart disease?" with values "Yes", "No" or "Unknown").
Data entry design needs to take account of data entry context for two reasons.
The range of concepts that can rationally be entered is determined by the data entry context.
The table below illustrates this point with examples of three data entry contexts. In each of these contexts, there are constraints on the range of SNOMED CT concepts that it is rational to enter.
The interpretation of concepts or other data entered may be affected by the data entry context.
The table below provides examples of ways in which the data entry context can affect the interpretation of recorded data. To ensure appropriate interpretation, relevant information about the data entry context must be stored with or linked to the data entered.
Initial Diagnosis on an Encounter or Admission Form
A healthcare professional assesses an unconscious person in the emergency room and concludes that the patient is suffering from effects of alcohol. To enter this initial diagnosis they type "alcohol".
An unconstrained search for "alcohol" will find a concept with the term | Alcohol| and may show that at the top of a search list. The problem is that this term is a synonym for the 53041004 | Alcohol (substance)| . While a substance may be relevant to the patient's condition a substance is not a valid diagnosis.
Using the concept 80146002 | appendectomy| with an indication that this was reported by the patient as having been done in the past.
Field
Content
Constraints on Values
A concept recorded in this data entry context could either be:
A subtype of ; or,
A subtype of with an indication that this is past history.
Interpretation of Recorded Data
The "Past History" data entry context needs to be captured so that the record can be appropriately interpreted. It must be possible to distinguish a past history record of a procedure from a contemporaneous record of the same procedure.
Symptom Checklist with Yes or No Options
A question about whether a patient has a sore throat would be linked to the concept 162397003 | sore throat| .
If the patient answers "no" then no entry is added to the record (see notes on alternatives in next column).
Field
Content
Constraints on Values
Each question should be bound to a concept that represents the relevant symptom. These concepts should be subtypes of .
The simplest way to represent the "yes" and "no" answers to a question like this is to record the relevant finding concept if the answer is "yes" and not to create a record if the answer is "no". However, where the answer "no" has clinical significance, alternative approaches discussed in the next column may be preferable.
Interpretation of Recorded Data
The simple approach suggested in the previous column does not explicitly record negative answers. However, in many cases, a negative response has its own significance and does need to be recorded.
For example, knowing that the patient responded "no" to the question "have you had any pain in the chest?".
Similarly, there may be questions that have 3 alternative answers (e.g. "yes", "no", "don't know"). In these cases, an approach is needed to distinguish between the available responses.
This section identifies terminology services required to support the design of data entry forms and templates that incorporate terminology bindings. The objective of these templates is to facilitate the entry of appropriate concepts (or expressions) into electronic health records.
As noted in the previous section, there are a variety of different EHR data entry contexts and each context logically constrains the range of concepts that can be used. This logical constraint can be formally specified using a value set binding represented as an expression constraint. Similarly, the data entry context may affect the meaning of data entered and this can be formally specified using a meaning binding represented by an expression or expression constraint.
A well designed template can simplify data entry and improve data quality by limiting the range of concepts available to those appropriate to a particular data entry context. The table below provides examples of some practical uses of templates with terminology bindings.
Data entry templates can also be used to combine and structure related data items, or to enable addition of refinements a selected concept. Different requirements can be met by a common template structure with different terminology bindings. In other cases, a more complex template may be required containing a collection of data items with different value set bindings. Similarly, a meaning binding may be applied to an individual template or to a collection of templates that share a similar interpretation (e.g. past medical history entries). Terminology bound templates that are designed to meet the needs of different data entry contexts can be combined into a more complex template that supports a complete data entry scenario.
Practical Uses of Terminology Binding in a Data Entry Template
The following table shows a summary of the terminology services required to enable terminology bindings to be created and edited when developing user interface templates for health record data entry.
Practical Use
Examples
To specify a concept or expression to that is added to the record entry when a particular data entry option is selected
To specify that the concept should be added to record entry when an item in a check list of medical conditions is marked as true.
To constrain the range of concepts that can be entered into a specific data entry field
To limit the range of concepts that can be entered in "surgical procedure" field to:
Subtypes of ; or
Members of a locally defined reference set containing surgical procedures carried out in particular department.
To support the structured entry of specific refinements relevant to a selected concept
To specify a template that includes questions about general findings followed by prompts for the site of the finding and/or other features.
The template also specifies how the refinement should be represented. Options include:
A record containing several named data items { symptom: location: } ; or
Services Required for EHR User Interface Template Editing
Practical Requirement
Status
Required Terminology Services
Dependencies
Select the SNOMED CT edition and version to be used.
REQUIRED
N/A
This section identifies the terminology services required to support practical entry of EHR data containing SNOMED CT concepts and expressions. It assumes that templates with appropriate terminology bindings have been created and applied using data entry design techniques identified in the section on EHR Data Entry Design.
The following table shows a summary of the terminology services required to support the most common types of EHR Data Entry. These service requirements are also sufficient to entry of postcoordinated expressions provided that these expressions are created using a specific predefined template.
Practical Requirement
Status
Required Services
Dependencies
Select the SNOMED CT edition and version to be used for data entry.
REQUIRED
N/A
Enable a concept, and where appropriate an associated term, to be recorded in response to the selection of a particular user interface option.
Data entry methods that generate adhoc postcoordinated expressions, without a specific predefined template, have additional requirements for access to the concept definitions and the concept model rules. For example, a user interface control could be designed to respond to the selection of a SNOMED CT concept by displaying options that allow a user to select one or more attributes applicable to the concept's domain. The user could then be prompted for values for each selected attribute allowing them to refine the meaning of the selected concept. Another technique involves natural language processing (NLP) identifying the primary focus concept and any relevant refinements stated in a passage of text.
Additional terminology service requirements for these techniques are summarized in the following table, and documented in the postcoordination guide.
Practical Requirement
Status (for adhoc postcoordination)
Required Services
Dependencies
Enable access to the definition of a selected concept.
Subsequent investigations may refute the initial diagnosis, so it should not be assumed the patient had the condition.
However, it may still be relevant:
• As rationale for initial treatment and investigation
• For audit, administration, and research purposes
The definitions of concepts that are subtypes of formally represent the past history context by including the attribute = . If subtypes of are to be used to record surgical history, these record entries must include an explicit indication of the past history context.
In either case, it may also be useful to indicate the source of the information (e.g. reported by the patient, derived from the original record) and actual or approximate date of the procedure.
Options for representing answers such as "yes", "no" and "don't know" include:
A postcoordinated expression using the SNOMED CT situation with explicit context model with the symptom represented as the and the answers represented as values of the attribute (e.g "yes" = , "no" = , and "don't know" = .
EHR Data Entry Design
EHR Data Entry
Terminology Services Required for EHR Data Entry
Additional Terminology Services Required for Ad hoc Postcoordinated Data Entry
To specify the concepts to be displayed in a short drop-down list from which an item may be selected.
A simplified representation of the situation model in which the associated finding is used for "yes" and the finding context is used for "no" and "don't know". For example, "Yes" = 162397003 | sore throat| , "no" = 410516002 known absent and "don't know" = 261665006 unknown.
To support the entry of any refinement permitted by the concept model (or a constrained version of the concept model)
To specify a template that allows a clinical finding to be refined using any attributes that are valid in the clinical finding concept model.
The refined concept would be represented as an expression.
Create or edit a user interface template or control that records specific concepts in EHR depending on user selections
Create or edit a user interface template including expression constraints that limit permitted values that can be entered through a specific data entry control
Create or edit a user interface template or control that records a specific expression in an EHR depending on user selections (in cases where no specific concept matches the required meaning)
Display appropriate terms in search results, user interface lists, checkboxes, radio buttons and any other user interface controls in which options are represented by concept identifiers.
A concept definition is a set of one or more axioms that partially or sufficiently specify the meaning of a SNOMED CT concept.
Concept Definition Validation Requirements
Concept definitions must conform to the SNOMED CT Concept Model as specified by the machine readable concept model. A concept with a definition that does not conform to the concept model cannot be accurately classified.
Service Requirements for Concept Definition Validation
Terminology services supporting SNOMED CT authoring must validate concept definitions based on concept model rules.
Services only for terminology use do not need to meet this requirement.
An expression is a structured combination of one or more concept identifiers that represents an idea.
Example
Example (with terms)
Expressions should conform to the SNOMED CT Concept Model and be classifiable by a .
Transforming Invalid Expressions to Valid Expressions
Move refining attributes into valid groups.
Nest refinements where required.
Move context attributes into a context wrapper.
Example Transformation (Laterality applied to body structure): Invalid:
Valid:
Service Requirements for Expression Validation
Services supporting use of should support expression validation.
Services Required
Service Name and Status
Input
Response
Validate concept definition:
Response: JSON object with concept, descriptions, axioms, relationships.
Validate concept definitions (multiple):
No direct SNOMED CT expression validation services.
No direct support for expression validation, but can validate using concept model rules and expression constraints.
Language/dialect should be specified if service returns terms.
Get and Test Reference Set Membership
Reference set files provide a standard format for maintaining and distributing a set of references to SNOMED CT components.
A reference set can be used to represent a subset of components (concepts, descriptions or relationships).
A reference set may also associate referenced components with additional information such as:
Validate concept definition(s)
ONLY REQUIRED FOR AUTHORING
Edition and Version
Identifier(s) of concept(s) to be validated
Indication of validation results for one or more concepts including
Nature of error
If appropriate a reference to a failed concept model rule
POST [snowstorm]/browser/{branch}/validate/concept
POST [snowstorm]/browser/{branch}/validate/concepts
Ordered lists of components
Sets of associations between components
Mapping between SNOMED CT concepts and other systems codes, classifications, or knowledge resources.
A concept or description is a member of a reference set if that reference set contains an active row with a referencedComponentId matching the id of that concept or description.
Two services are specified in this section. One of these returns the list of members of a specified reference set. The other tests whether a candidate concept or description is a member of a specified reference set.
The services listed in the table below can be used to determine whether a concept or description is a member of any identified reference set. These services are primarily applicable to simple reference sets that represent subsets of concepts or descriptions (). Members of other types of reference set contain additional data and services that provide access to this additional data are described in Get Data from a Reference Set .
Service Name and Status
Input
Output
Get all members of a specified reference set
A reference set specified by its refsetId
A list of concept or description ids
Option to include additional information about each concept or description
Test if a concept or description is a member of specified reference set
A reference set specified by its refsetId A candidate concept.id or description.id
If the candidate concept or description is a member of the reference set: TRUE
Returns a JSON representation of data about all the active members of the reference set.
It also returns the total number of members in the reference set.
As some reference sets contain a large numbers of members, this service is paged. Requests parameters include:
limit to restrict the number of reference set members returned (default 50).
offset to specify the starting point in the results (in multiples of the limit).
Test if a concept or description is a member of specified reference set
for example this call returns true
Encoded URL
while the next call returns false
Encoded URL
Returns a JSON representation of data including a count of matching member rows followed by data from the matching member rows. The result of the test can be determined by checking the total property of the returned object. Non-zero implies the candidate concept or description is a member of the reference set, zero implies it is not.
The two example calls both test membership of the . The first one returns with a total value of 1 confirming that is a member of this reference set. The second example returns with a total value of 0 as is not a member of this reference set.
Service Name
API Call 5
Result
Get all members of a specified reference set
An alternative solution is to use the expression constraint language, as shown here:
for example
Returns a JSON representation of data about each of the reference set member.
The data returned for each concept includes:
code: the conceptId of the reference set member
display: the preferred term for the reference set member
Also returns the total number of reference set members
Test if a concept is a member of specified reference set
FHIR does not provide a specific operation for this service, but the supports testing for reference set membership, and can thus be used to enable this service through the ValueSet/$expand operation.
for example
Encoded URL
*Note that the ECL memberOf function needs to be url encoded. The URL encoding for ^ is %5E
If multiple predicate concepts should be tested in the same requests this can be done using the following expression constraint:
Returns a JSON representation of data about each of the predicate concepts that are members of the reference set.
The data returned for each concept includes:
code: the conceptId of the reference set member
display: the preferred term for the reference set member
Also returns the total number of concepts satisfying the expression constraint.
Service Name
SQL Query 6
Result
Get all members of a specified reference set
for example
Returns the ids of all the concepts or descriptions that are the members of the reference se
Test if a concept or description is a member of specified reference set
for example
Returns:
0 : if the candidate component is not in the reference set.
1 : If the candidate component is a member of the reference set
Some types or reference set can include the same component more than once, so any value greater than zero indicate the component is a member of the references set.
Notes
The reference set specification should indicate which component types are permitted to be members. The members of some reference sets are concepts while the members of other reference sets are concepts. It is also possible, for some reference sets to contain both concepts and descriptions as members. Services that only return the referencedComponentId do not need to be aware of the types of component in the reference set. However, if a service returns terms or other additional data, the service must take account of the component type.
The value TRUE may be represented in a variety of ways. For example: as a Boolean value, as a non-zero count of matching members or by a data object representation of the candidate component. Similarly the value FALSE may be represented by a Boolean, by a zero count, or by an empty or null returned object.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
The number of results returned defaults to 50 but can be set using a limit parameter in the call. Additionally the starting offset within a large set of results can be specified by an additional parameter.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR ® is a registered trademarks of ( ).
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system . It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the . For instructions on how to build the example database refer to .
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
Snowstorm API
FHIR API
MySQL Example Database
This example returns all active members of the . This is large reference set with nearly 20,000 active members so although this call returns the count of members it only returns data on a limited number of members .
As some reference sets have very large numbers of children, this service is paged. Requests parameters include:
count to restrict the number of members returned.
offset to specify the start in the results (in multiples of the limit).
Note: If none of the predicate concepts are which are tested for membership are included in the reference set, the service will return 0 results.
GET [snowstorm]/[branch]/members?active=true&referenceSet=[refsetId]
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=723264001
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=723264001
GET [snowstorm]/[branch]/members?active=true&referencedComponentId=[candidateId]&referenceSet=[refsetId]
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referencedComponentId=53120007&referenceSet=723264001
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;referencedComponentId=53120007&referenceSet=723264001
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referencedComponentId=80891009&referenceSet=723264001
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;referencedComponentId=80891009&referenceSet=723264001
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E721144007&count=10
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E%5BrefsetId%5D&count=10
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Drefset%2F721144007&count=10
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=refset/[refsetId]&count=10
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/^[refsetId] AND [predicateConceptId]
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/^721144007 AND 734009000
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E721144007+AND+734009000
^[refsetId] AND ([predicateConceptId_1] OR [predicateConceptId_2].... OR [predicateConceptId_n])
SELECT referencedComponentId FROM snap_refset_simple
WHERE active=1 AND refsetId=[refsetId]
SELECT referencedComponentId FROM snap_refset_simple
WHERE active=1 AND refsetId=723264001
SELECT count(referencedComponentId)
FROM snap_refset_simple
WHERE active=1 AND refsetId=[refsetId] AND referencedComponentId=[candidateComponentId]
SELECT referencedComponentId FROM snap_refset_simple
WHERE active=1 AND refsetId=723264001
The SNOMED CT concept model is the set of rules that determines the permitted sets of relationships between particular types of concepts.
Notes
The concept model specifies the attributes that can be applied to concepts in particular domains and the ranges of permitted values for each attribute. There are additional rules on the cardinality and grouping of particular types of relationships.
Concept model rules are represented in a machine readable form by the members of the following four reference set types:
MRCM Domain Reference Set
Each row in this reference set defines a concept model domain. Each domain is a set of concepts which the concept model permits to be defined or refined, using a particular set of attributes and ranges.
MRCM Attribute Domain Reference Set
Each row in this reference set specifies an concept model attribute that can be used to represent a characteristic of the meaning of a concept or the nature of a refinement.
MRCM Attribute Range Reference Set
Each row in this reference set defines a concept model range that defines a set of values that the concept model permits to be applied to a specific attribute.
MRCM Module Scope Reference Set
For full details of these reference set and the ways in which the rules are represented in these reference sets, refer to the SNOMED CT Machine Readable Concept Model (MRCM) specification and guide.
Access to concept model rules is required to support a range of different practical uses including those identified in the 'Interdependencies' section on this page. The general techniques for accessing the data are the same as those for other references sets. However, interpretation of the data requires access to related data in each of the MRCM reference set types. To illustrate this the requirements are listed in the table below and service examples are presented in a logical interrelated order.
Service Name and Status
Input
Output
Other Services
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see ).
Service Name
API Call 2
Result
Service Name
API Call 3
Result
Service Name
SQL Query
Result
Notes
Language and/or dialect should be specified if the service returns terms associated with referenced concepts.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of ().
The members of this reference set specify the set of MRCM reference sets that should be applied to concepts a specified SNOMED CT module.
Get the set of attribute rules applicable to an identified concept
SNOMED CT Edition and Version The conceptId for which the attribute rules are to be identified.
An indication of whether domains applicable to proximal primitive definitions are to be included. Content type option - one of the following concept identifiers:
- 723593002
All new precoordinated SNOMED CT content
Get the range of values applicable to a specified attribute
SNOMED CT Edition and Version The attributeId for which values are to be identified. Content type options (see previous service) The id of the concept to which the attribute is being applied (or the moduleId of the module to which concept belongs) are also required unless provided by internal services.
Each rule should include the content of all the additional data columns in the MRCM Attribute Range reference set.
Get the set of attributes applicable to a concept in a specified domain or set of domains
For example
Encoded URL
Returns a JSON representation of data related to each for the attributes applicable to specified concept.
The data returned is filtered so it only includes data relevant to in the specified contentType.
The data returned includes information from all the columns in the Attribute Domain reference set.
It also includes terms associated with the attribute.
The contentTypeId and ruleStrengthId are represented by human readable tokenized strings rather than the conceptId.
Get the range of values applicable to a specified attribute
Snowstorm does not provide a specific service for returning the attribute range constraint applicable to a concept model attribute. However, it does support access to the relevant data in two ways. Firstly the general service for access to refset members as (see ) can be as illustrated here. Additionally, the Snowstorm service shown in the next row provides a way to carry out a search that is constrained to the permitted set of values for an attribute.
For example
Encoded URL
Returns a JSON representation of data related to the specified attribute range.
The range data is returned in the following properties of the additionalFields object:
rangeConstraint
attributeRule
Find values that are within the range or a specified attribute
For example
Encoded URL
Returns a JSON representation of the search results constrained by the rangeConstraint.
The data returned is in the same form as documented in the section.
Get the domain or set of domains that include a specified concept
Example 1. Get the domains that include the concept
Example 2. Get the domains that include the concept
Example 3. Get the proximal primitive domains that include the concept
This procedure returns two values.
domainId - the most specific domain that includes the specified concept.
domainList - a comma separated list of all the domains that include the specified concept.
Example 1 returns the following set of domains:
Get the set of attributes applicable to a concept in a specified domain or set of domains
Example 1. Get the attributes applicable to the concept when using postcoordination
Example 2. Get the attributes and attribute constraints applicable to the concept when using postcoordination.
The getMrcmAttributeRanges procedure generates rows in the config_mrcmrulesets table. It returns a rulesetKey which can be used to query the generated rows. These rows contain not only the attributes but also range constraints.
Both examples get the attributes applicable to the same concept but the results returned by the select queries vary in content.
Example 1 returns the attributeId and preferred terms for each attribute applicable to the specified concept in the context specified by the proximal primitive and content type settings.
Example 2 returns all valid combinations of attributes and attribute range constraints applicable to the specified concept specified in the context specified by the proximal primitive and content type settings.
Get the range of values applicable to a specified attribute
As noted above, the getMrcmAttributeRanges procedure returns the attribute ranges of all attributes applicable to a concept. However, it is also possible to return the attribute range for specific attribute.
Example. Get all the attribute range constraints applicable to the concept when using postcoordination
Returns the rangeConstraint for the attribute and the the contentTypeId and ruleStrengthId. In some cases more than one row may be returned where there are rules with different strengths or applicable to different subsumed contentTypes.
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system . It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the SNOMED CT - SQL Practical Guide. For instructions on how to build the example database refer to Appendix A: Building the SNOMED CT Example Database.
Get the refsetId of specific type of MRCM reference set applicable to concepts in an identified module
SNOMED CT Edition and Version
The conceptId representing the moduleId
The MRCM reference set type (mrcmDomain, mrcmAttributeDomain or mrcmAttributeRange)
The identifier of the specific MRCM reference set applicable to concept in the specified module.
Client applications do not require access to this data. However, it is required as an internal service to enable other MRCM services.
Get the domain or set of domains that include a specified concept
SNOMED CT Edition and Version
The conceptId for which the domains are to be identified.
An indication of whether domains applicable to proximal primitive definitions are to be included.
The conceptId can be used to get the required moduleId and then, using the service above, the appropriate MRCM Domain reference set can be identified.
The general process for identifying the domains that include a specified concept is as follows:
Identify the top-level domain that subsumes the concept.
The identifiers of the domains to which the identified concept belongs.
Client applications do not require access to this data. However, it is required as an internal service to enable the service service following MRCM services.
Get the set of reference sets applicable to concepts in an identified module
This service is supported internally and used by the services below. The relevant data is also directly accessible at the API using the general service used to access refset members as described in Get Data from a Reference Set.
JSON representation of three refset members each of which refers to one of the MRCM reference sets for concepts in the specified module.
The MRCM reference set references is represented by the additionalFields. mrcmRuleRefsetId property.
Get the domain or set of domains that include a specified concept
This service is supported internally and used by the services below. However, it is not directly accessible at the API.
Get concept model rules
N/A
No FHIR terminology services are available to provide detailed information about SNOMED CT concept model rules.
Get the set of reference sets applicable to concepts in an identified module
SELECT mrcmRuleRefsetId,refsetType FROM snap_refset_mrcmmodulescope m JOIN config_refsets r ON r.refsetId=m.mrcmRuleRefsetId WHERE active=1 AND refsetId=723563008 AND referenceComponentId=[moduleId];
SELECT mrcmRuleRefsetId,refsetType FROM snap_refset_mrcmmodulescope m JOIN config_refsets r ON r.refsetId=m.mrcmRuleRefsetId WHERE active=1 AND m.refsetId=723563008 AND referencedComponentId=900000000000207008
The other MRCM services described below use this function to determine which reference set to use to access domain, attribute and range constraint information.
Notes
An attribute is assigned a value (attribute value pair) when used in the definition of a concept or in a postcoordinated expression.
The attributes that can be used in definitions or refinements are represented by a concepts that are subtypes of the concept 410662002 | Concept model attribute (attribute)| .
The SNOMED CT concept model specifies:
The concept model domains which each specific attribute can be applied; and
The concept model range of values that can be applied to each specific attribute.
Requirements and Options
Client applications do not require access to this data. However, it is required as an internal service to enable other MRCM services.
Identify each of the domains that is a child or descendant of that top level domain.
The concept is included the top-level domain that subsumes the concept and any of its child and descendant domains that which have expression constraints to which it conforms.
The expression constraint tested depends proximal primitive indicator value
False: Conformance with the domainConstraint is required.
True: Conformance with the proximalPrimitiveConstraint is required.
CALL getMrcmDomains([conceptId],[proxPrim],@domainId, @domainList);
-- Following line shows the results
SELECT @domainId,@domainList;
CALL getMrcmDomains(71341001,0,@domainId, @domainList);
-- Following line shows the results
SELECT @domainId, @domainList;
CALL getMrcmDomains(241075002,0,@domainId, @domainList);
-- Following line shows the results
SELECT @domainId, @domainList;
CALL getMrcmDomains(241075002,1,@domainId, @domainList);
-- Following line shows the results
SELECT @domainId, @domainList;
CALL getMrcmAttributeRanges([conceptId],[proxPrim],[contentTypeKey],@ruleSetKey);
-- Following statement shows the attribute ids and terms
SELECT DISTINCT `attributeId`,`term`
FROM `config_mrcmrulesets` `c`
JOIN `snap_pref` `p` ON `c`.`attributeId`=`p`.`conceptId`
WHERE `rulesetKey`=@rulesetKey;
CALL getMrcmAttributeRanges(71341001,0,'pos',@ruleSetKey);
-- Following statement shows the attribute ids and terms
SELECT DISTINCT `attributeId`,`term`
FROM `config_mrcmrulesets` `c`
JOIN `snap_pref` `p` ON `c`.`attributeId`=`p`.`conceptId`
WHERE `rulesetKey`=@rulesetKey;
CALL getMrcmAttributeRanges(71341001,0,'pos',@ruleSetKey);
-- Following statement shows the attribute ids and terms
SELECT `attributeId`,`grouped`, `attributeCardinality`,
`attributeInGroupCardinality`, `attributeContentTypeId`,
`attributeRuleStrengthId`, `rangeConstraint`,
`rangeContentTypeId`, `rangeRuleStrengthId`
FROM `config_mrcmrulesets` WHERE `rulesetKey`=@rulesetKey;CALL getMrcmDomains(241075002,0,@domainId, @domainList);
-- Following line shows the results
SELECT @domainId, @domainList;
SET @attributeId=[attributeId];
SET @contentTypeIdList=[contentTypeIdList];
SET @moduleId=[moduleId];
SELECT `rangeConstraint`, `contentTypeId`, `ruleStrengthId`
FROM `snap_refset_mrcmattributerange`
WHERE `refsetId`= getMrcmRefsetId(@moduleId,"R");
AND `r`.`active`=1
AND FIND_IN_SET(`r`.`contentTypeId`,@contentTypeIdList)>0;
SET @attributeId=260870009;
SET @contentTypeIdList="723596005,723594008";
SET @moduleId=900000000000207008;
SELECT `rangeConstraint`, `contentTypeId`, `ruleStrengthId`
FROM `snap_refset_mrcmattributerange`
WHERE `refsetId`= getMrcmRefsetId(@moduleId,"R") AND `referencedComponentId`=@attributeId AND `active`=1 AND FIND_IN_SET(`contentTypeId`,@contentTypeIdList)>0;
The required internal services above are used to identify the domains that include the concept.
The selected set of attribute domain rules. Conformance with the rangeConstraint expression is determined by applying the expression constraint to a specific value. The rangeConstraint can also be used filter the range of permitted refinements to the value of that attribute in postcoordinated expression.
The procedure adds also adds a row to the config_resultsets table for each of the domains. This makes it easier for the services below to access to look up the attribute and range constraints for the set of domains applicable to a specified concept.
