# Select Edition and Version

## Overview <a href="#id-4.1selecteditionandversion-overview" id="id-4.1selecteditionandversion-overview"></a>

### Editions <a href="#id-4.1selecteditionandversion-editions" id="id-4.1selecteditionandversion-editions"></a>

Several different SNOMED CT editions are available. All editions include the content of the SNOMED CT International Edition but some also include extensions[^1] 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 <a href="#id-4.1selecteditionandversion-versions" id="id-4.1selecteditionandversion-versions"></a>

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[^2] 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 <a href="#id-4.1selecteditionandversion-releasetypes" id="id-4.1selecteditionandversion-releasetypes"></a>

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 <a href="#id-4.1selecteditionandversion-comparingversions" id="id-4.1selecteditionandversion-comparingversions"></a>

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](#user-content-fn-3)[^3].

## Requirements and Options <a href="#id-4.1selecteditionandversion-requirementsandoptions" id="id-4.1selecteditionandversion-requirementsandoptions"></a>

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

<table data-full-width="true"><thead><tr><th width="201.171875">Service Name and Status</th><th width="193.703125">Input</th><th>Output</th></tr></thead><tbody><tr><td><p><strong>Get available editions</strong></p><p><strong>REQUIRED</strong><br></p></td><td><ul><li>None</li></ul></td><td><ul><li><p>Data associated with available SNOMED CT <a href="https://confluence.ihtsdotools.org/display/DOCGLOSS/edition">editions</a>:</p><ul><li>The name of the edition</li><li><p>An identifier that can be used to select that edition</p><ul><li>See note on input to the "Get available versions" service</li></ul></li><li><p>Optionally other data including:</p><ul><li>Information about the organization responsible for maintenance and distribution</li><li>Information about available versions of this edition (as specified for the "Get available versions" service)</li></ul></li></ul></li></ul></td></tr><tr><td><p><strong>Get available versions</strong></p><p><strong>REQUIRED</strong><br></p></td><td><ul><li>Edition identifier<br></li></ul><p><a data-footnote-ref href="#user-content-fn-4"><strong>Notes</strong></a></p></td><td><ul><li><p>Data associated with available versions of the specified edition:</p><ul><li>The name of the edition</li><li>The version date</li><li><p>An identifier that can be used to select that <em>versioned edition</em> (or <em>extended versioned edition</em>):</p><ul><li>See note on input to the "Specify a versioned edition" service</li></ul></li><li>Identifiers of the versioned modules included in that version of the edition.</li><li><p>Optionally:<br></p><ul><li>Information about the organization responsible for maintenance and distribution</li></ul></li></ul></li></ul></td></tr><tr><td><p><strong>Get available development branches</strong></p><p><strong>DEVELOPMENT</strong><br></p></td><td><ul><li>Edition identifier<br></li></ul></td><td><ul><li><p>Data associated with available versions of the specified edition:</p><ul><li>The name of the edition</li><li>Data related to the development branch</li><li>An identifier that can be used to select that development branch using</li><li><p>Optionally:<br></p><ul><li>Information about ownership, status and access rights to the development branch</li></ul></li></ul></li></ul></td></tr><tr><td><p><strong>Specify a versioned</strong> <a data-footnote-ref href="#user-content-fn-5"><strong>edition</strong></a></p><p><strong>REQUIRED</strong></p></td><td><ul><li>Versioned edition identifier</li></ul><p><a data-footnote-ref href="#user-content-fn-6"><strong>Notes</strong></a></p></td><td><p>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.</p><p>There are two exceptions to this:</p><ul><li>Versioned edition selection services without a request for another service should provide data about the <em>versioned edition</em> (or <em>extended versioned edition</em>), in a similar as specified for the "Get available versions" service.</li><li>If the specified version is not accessible, the output should be an appropriate error message.</li></ul></td></tr><tr><td><p><strong>Specify an extended versioned edition</strong></p><p><strong>OPTIONAL</strong></p></td><td><ul><li>Versioned edition identifier</li><li>moduleId(s) and version dates of each of the modules to be included in the extended versioned edition.</li></ul><p><a data-footnote-ref href="#user-content-fn-7"><strong>Notes</strong></a></p></td><td>Same as above</td></tr><tr><td><p><strong>Specify development branch</strong></p><p><strong>DEVELOPMENT</strong></p></td><td><ul><li>Development branch identifier.</li></ul></td><td>Same as above</td></tr></tbody></table>

## **Accessing a Selected Edition Version or Branch** <a href="#id-4.1selecteditionandversion-accessingaselectededitionversionorbranch" id="id-4.1selecteditionandversion-accessingaselectededitionversionorbranch"></a>

For performance reasons, scalable terminology services should be stateless[^8] 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 <a href="#id-4.1selecteditionandversion-interdependencies" id="id-4.1selecteditionandversion-interdependencies"></a>

**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 <a href="#id-4.1selecteditionandversion-serviceexamples" id="id-4.1selecteditionandversion-serviceexamples"></a>

{% hint style="success" %}
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](https://www.ietf.org/rfc/rfc1738.txt)).
{% endhint %}

### Snowstorm API

<table data-full-width="true"><thead><tr><th width="207.91796875">Service Name</th><th>API Call</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get available editions</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/codesystems
</code></pre></td><td><p>Returns JSON representation of all SNOMED CT Editions that are available in the server.</p><p>The data for each edition includes a <em>shortname</em> property used to refer that edition in subsequent API calls.</p><p>For the International Edition the shortname is "<strong>SNOMEDCT</strong>".</p></td></tr><tr><td><strong>Get available versions of an edition</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/codesystems/[shortname]/versions
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [snowstorm]/codesystems/SNOMEDCT/versions
</code></pre></td><td><p>Returns JSON representation of each version of the edition specified by <em>shortname</em> that are available in the server.</p><p>The data for each edition version includes a <em>branchPath</em> property used to refer that edition in subsequent API calls. For the 2020-01-31 release of the International Edition the <em>branchPath</em> is "MAIN/2020-01-31". The data returned also includes details of the modules in included in each<a data-footnote-ref href="#user-content-fn-9"> versioned edition.</a></p><p>Note that URL encoding rules requires the / (slash) character to be replaced with %2F. Thus in subsequent API calls the <em>branchPath</em> is represented as <strong>MAIN%2F2020-01-31</strong></p></td></tr><tr><td><strong>Specify a specific versioned edition</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/codesystems/[branchPath]
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [snowstorm]/codesystems/MAIN/2020-01-31
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/codesystems/MAIN%2F2020-01-31
</code></pre></td><td><p>Returns information about the identified versioned edition specified by the <em>branchPath</em>. This includes information about all the modules included in the edition.</p><p>In practice the <em>branchPath</em> may refer to an extended versioned edition containing additional modules that are not part of the formally defined edition (see <a href="../5-service-implementation-considerations/5.2-enabling-access-to-editions-and-versions">Enabling Access to Extended Editions</a>). In this case, these modules will also be listed.</p><p>Other Snowstorm API calls use the same <em>branchPath</em> mechanism to refer to specific versioned editions or development branches.</p></td></tr></tbody></table>

{% hint style="info" %}
In the Snowstorm service requests \[snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
{% endhint %}

### FHIR API

<table data-full-width="true"><thead><tr><th width="230.5859375">Service Name</th><th width="259.765625">API Call</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get available code systems</strong></td><td><pre data-overflow="wrap"><code>GET [fhir]/CodeSystem?_elements=name,url
</code></pre></td><td><p>Returns a JSON representation of the name and URL of each supported code system.</p><ul><li>The URL is then used in other commands to specify the code system to be accessed.</li></ul></td></tr></tbody></table>

{% hint style="info" %}
In the FHIR service requests \[fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR<sup>®</sup> is a registered trademarks of [HL7](http://www.hl7.org/) ([www.hl7.org](http://www.hl7.org)).
{% endhint %}

### MySQL Example

<table data-full-width="true"><thead><tr><th width="192.80859375">Service Name</th><th width="434.8828125">SQL Query</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get available editions</strong></td><td>Not supported. Available editions are determined by importing each edition into a separate schema.</td><td>-</td></tr><tr><td><strong>Specify an edition</strong></td><td>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 <a href="https://confluence.ihtsdotools.org/display/DOCGLOSS/full+release">full release</a> of that edition. Once this schema has been built, queries run on that schema provide access to data in that edition.</td><td>-</td></tr><tr><td><strong>Specify an extended edition</strong></td><td>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.</td><td>-</td></tr><tr><td><strong>Get available versions of an edition</strong></td><td><p>Not required.</p><p>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.</p></td><td>-</td></tr><tr><td><strong>Specify a specific versioned edition</strong><br></td><td>for example</td><td>After applying the two procedure calls shown, queries that refer to views with the prefix <strong>snap1_</strong> will be applied to the 2019-07-31 version and queries that refer to views with the prefix <strong>snap2_</strong> will be applied to the 2015-01-31 version.</td></tr><tr><td></td><td></td><td></td></tr><tr><td><code>CALL setSnapshotTime([configId],[snapshotTime]);</code></td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><code>CALL setSnapshotTime(1,'20190731');CALL setSnapshotTime(2,'20150131');</code></td><td></td><td></td></tr></tbody></table>

{% hint style="info" %}
For more information about the SNOMED CT example database see the[ SNOMED CT - SQL Practical Guide](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/LnTo62BQeQSW6tBNKv0T/).
{% endhint %}

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.

{% hint style="info" %}
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.
{% endhint %}

<a href="https://docs.google.com/forms/d/e/1FAIpQLScTmbZIf0UEQwYDkY27EEWBkaiYkHSbR0_9DmFrMLXoQLyL7Q/viewform?usp=pp_url&#x26;entry.1767247133=SNOMED+Terminology+Services+Guide&#x26;entry.670899847=Select%20Edition%20and%20Version" class="button primary">Provide Feedback</a>

[^1]: \
    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 conten

[^2]: Concepts, Descriptions and Relationships

[^3]: 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.

[^4]: **This service must support the use of one or more of the following edition identifiers:**

    * **The moduleId of the edition**
    * **The URI of the edition**
    * **A edition key returned by the the "Get available editions" service.**

[^5]: 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.

[^6]: **This service must support one or more of the following versioned edition identifiers:**

    * **The moduleId of the edition and the version date**
    * **The URI of the versioned edition**
    * **A key or identifier of the versioned edition returned by the the "Get available versions" service.**

[^7]: **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**\
    **b) It only includes reference sets and metadata concepts.**

    **Extension modules that contain clinical terminology content should only be included as part of a formally defined SNOMED CT edition.**

[^8]: For a general explanation of the performance and integrity advantages of stateless services see the [Wikipedia article on "Service statelessness principle"](https://en.wikipedia.org/wiki/Service_statelessness_principle).

[^9]: \
    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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.1-select-edition-and-version.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.