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 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 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.

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 date.

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 .

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 the table below.

Services Required

Service Name and Status	Input	Output
Get available editions REQUIRED	None	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	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 development branches DEVELOPMENT	Edition identifier	Data associated with available versions of the specified edition: The name of the edition Data related to the development branch An identifier that can be used to select that development branch using Optionally: Information about ownership, status and access rights to the development branch
Specify a versioned 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

Accessing a Selected Edition Version or Branch

For performance reasons, scalable terminology services should be 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:

• 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 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).

Snowstorm API

Service Name	API Call	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 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 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.

In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.

FHIR API

Service Name	API Call	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. The URL is then used in other commands to specify the code system to be accessed.

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).

MySQL Example

Service Name	SQL Query	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.

For more information about the SNOMED CT example database see the SNOMED CT - SQL Practical Guide.

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.

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.