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 organization1. 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 (see alpha and beta release package). Therefore, services designed to support terminology development and maintenance also need to enable selection of specific terminology development versions or branches.
Release Types
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 date2.
Comparing Versions
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 versions3.
Requirements and Options
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 Table 4.1-1.
Table 4.1-1: Services Required
Service Name and Status | Input | Output |
|---|---|---|
Get available editions REQUIRED |
|
|
Get available versions REQUIRED |
This service must support the use of one or more of the following edition identifiers:
|
|
Get available development branches DEVELOPMENT |
|
|
Specify a versioned edition 4 REQUIRED |
This service must support one or more of the following versioned edition identifiers:
| 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 services. It simply identifies the terminology substrate to which those requests apply and does not produce specific output. There are two exceptions to this:
|
Specify an extended versioned edition 4 OPTIONAL |
This creates an informally defined edition consisting of the edition formally specified by the edition moduleId and the contents of one or more compatible extension modules. An extension module is compatible with an edition if: a) Its module dependencies are satisfied by the identified edition; and Extension modules that contain clinical terminology content should only be included as part of a formally defined SNOMED CT edition. | |
Specify development branch DEVELOPMENT |
|
Accessing a Selected Edition Version or Branch
For performance reasons, scalable terminology services should be stateless5 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.
Interdependencies
Required By
- Other Terminology Services
- All
- Use Cases
- All
A terminology server that only provides access to a single snapshot view of pre-specified version and edition of SNOMED CT may not explicitly support this as a service. However, in this case the process of loading data into the service implicitly involves selection of a particular release edition and version.
Depends On
- The terminology server instance from which services are being requested must include data for the versioned editions requested by the client application.
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).
Table 4.1-2: Snowstorm API
| Service Name | API Call 6 | Result |
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 edition7. 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 |
Specify a specific versioned edition |
GET [snowstorm]/codesystems/[branchPath] for example GET [snowstorm]/codesystems/MAIN/2020-01-31 Encoded URL GET [snowstorm]/codesystems/MAIN%2F2020-01-31 | 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 5.2.2 Enabling Access to Extended Editions). 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. |
Table 4.1-3: FHIR API
| Service Name | API Call8 | Result |
Get available code systems |
GET [fhir]/CodeSystem?_elements=name,url | Returns a JSON representation of the name and URL of each supported code system.
|
Table 4.1-4: MySQL Example
| Service Name | SQL Query9 | Result |
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. | - |
| 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 | CALL setSnapshotTime([configId],[snapshotTime]); for example CALL setSnapshotTime(1,'20190731'); CALL setSnapshotTime(2,'20150131'); | 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. |
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 (see Set Snapshot Time).
Queries run on a specific snapshot view return the data as it was at the configured date.
Note
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.
Footnotes
SNOMED International Members may maintain National Editions and these may contain additional concepts specific to a particular Member territory and/or descriptions representing international edition concepts in national languages or dialects. Clinical specialty groups, system vendors or healthcare provider organizations editions may maintain extensions that can be combined with the International Edition and/or a National Edition. These extended editions may be limited to additional reference sets or may also include additional content. For more information about SNOMED CT editions and extensions see Appendix B: Editions, Versions and Extensions.
For more information about release types see 3.2 Release Types in the SNOMED CT Release File Specifications.
If a terminology does not support services that compare the state of components in different versions, history related services would require the client application to request the data from both versions and undertake the comparison itself.
A terminology server may support selection of a versioned edition or an edition. In the latter case, the terminology service must also provide services that allow effective time to be specified to ensure the appropriate version of a component is returned.
For a general explanation of the performance and integrity advantages of stateless services see the Wikipedia article on "Service statelessness principle".
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
In some cases, a Snowstorm path may refer to an extended versioned edition containing additional extension modules that are not part of the formally defined edition (see 5.2.2 Enabling Access to Extended Editions).
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).
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.
Feedback
Overview
Content Tools
Apps