> For the complete documentation index, see [llms.txt](https://docs.b2ihealthcare.com/snow-owl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.b2ihealthcare.com/snow-owl/rest-apis/fhir/codesystems.md).

# CodeSystem

## Tooling support

Snow Owl TS differentiates between certain "families" (toolings) of code system resources. Each tooling uses an internal representation for its terminology components that can be searched and edited more effectively. These components are converted to a FHIR-compatible form when a `read` or `search` interaction happens, and back when new a `CodeSystem` resource is created via the FHIR API (or an existing resource receives an update).

### SNOMED CT

SNOMED CT and its extensions are effectively read-only from the FHIR API's point of view – they can not be created via a `create` interaction, nor can content be loaded or updated from an RF2 archive. Only Snow Owl's native API has provisions for doing so.

SNOMED CT code system URLs follow the conventions described in the [SNOMED CT URI Standard](https://docs.snomed.org/snomed-ct-specifications/snomed-ct-uri-standard).

As SNOMED CT code systems contain a considerable amount of concepts, resource responses for this tooling do not include a `concept` array:

```http
GET /snowowl/fhir/CodeSystem/SNOMEDCT-US?_pretty=true

[Response headers]
Content-Type: application/fhir+xml

<CodeSystem xmlns="http://hl7.org/fhir">
  <id value="SNOMEDCT-US"/>
  <meta>
    <lastUpdated value="2023-10-18T01:52:16.04Z"/>
  </meta>
  <language value="en"/>
  ...
  <url value="http://snomed.info/sct"/>
  <version value="http://snomed.info/sct/731000124108"/>
  <valueSet value="http://snomed.info/sct/731000124108?fhir_vs"/>
  ...
  <name value="SNOMEDCT-US"/>
  <title value="SNOMED CT US Extension"/>
  <status value="active"/>
  <publisher value="NIH - National Library of Medicine"/>
  ...  
  <content value="complete"/>
  <count value="513765"/>
  ...
```

All SNOMED CT resources behave like editions, which means `lookup` operations succeed for any concept that can be found within eg. the International Edition's content, or in any other extension the resource depends on:

```http
GET /snowowl/fhir/CodeSystem/$lookup?system=http://snomed.info/sct&version=http://snomed.info/sct/731000124108&code=138875005&_pretty=true

[Query parameters (repeated for clarity)]
system: http://snomed.info/sct
version: http://snomed.info/sct/731000124108
code: 138875005
_pretty: true

[Response headers]
Content-Type: application/fhir+xml

<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="name"/>
    <valueString value="SNOMEDCT-US"/>
  </parameter>
  <parameter>
    <name value="display"/>
    <valueString value="SNOMED CT Concept"/>
  </parameter>
  <parameter>
    <name value="version"/>
    <valueString value="http://snomed.info/sct/731000124108"/>
  </parameter>  
</Parameters>
```

#### Filters

The following filters are supported in value set compose statements, should they reference a SNOMED CT code system:

<table><thead><tr><th width="124">Code</th><th width="81.3333740234375" align="center">Operator</th><th width="157">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>expression</code></td><td align="center"><code>=</code></td><td>ECL expression</td><td>Matches concepts using the Expression Constraint Language</td></tr><tr><td><code>expressions</code></td><td align="center"><code>=</code></td><td><code>true</code> or <code>false</code></td><td>Specifies whether Post-Coordinated Expressions should be included in the filtered result set</td></tr><tr><td><code>concept</code></td><td align="center"><code>is-a</code></td><td>SCTID (any concept)</td><td>Matches the descendants of the specified parent concept</td></tr><tr><td><code>concept</code></td><td align="center"><code>in</code></td><td>SCTID (reference set identifier)</td><td>Matches concepts that are members of the specified reference set</td></tr></tbody></table>

{% hint style="warning" %}
While Snow Owl accepts `expressions` as a filter, it currently does does not store PCEs so the value of this filter does not change returned results.
{% endhint %}

#### Properties

All SNOMED CT relationship types are supported and can be returned along with concept data if requested. In addition to these (and the common properties that are applicable to all code systems), Snow Owl can also return a set of SNOMED CT-specific concept properties.

A single example for a type concept property and all SNOMED CT-specific properties are listed in the table below:

<table><thead><tr><th width="193.666748046875">Code</th><th width="100" align="center">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>288556008</code></td><td align="center"><code>code</code></td><td>The SCTID of destination concepts on relationships with a <code>typeId</code> value of <code>288556008|Before|</code></td></tr><tr><td><code>inactive</code></td><td align="center"><code>boolean</code></td><td>Inactive status based on the concept's <code>active</code> RF2 property (its inverse is returned)</td></tr><tr><td><code>moduleId</code></td><td align="center"><code>code</code></td><td>The concept's <code>moduleId</code> RF2 property</td></tr><tr><td><code>effectiveTime</code></td><td align="center"><code>string</code></td><td>The concept's <code>effectiveTime</code> RF2 property<br>(in <code>yyyyMMdd</code> format)</td></tr><tr><td><code>sufficientlyDefined</code></td><td align="center"><code>boolean</code></td><td>A boolean value derived from the concept's <code>definitionStatusId</code> RF2 property(set to <code>true</code> if the original value is <code>900000000000073002</code>)</td></tr></tbody></table>

Use the following values if you need to refer to these properties by URI instead of code:

<table><thead><tr><th width="197.333251953125">Code</th><th>Property URI</th></tr></thead><tbody><tr><td><code>288556008</code></td><td><code>http://snomed.info/id/288556008</code></td></tr><tr><td><code>inactive</code></td><td><code>http://snomed.info/field/Concept.inactive</code></td></tr><tr><td><code>moduleId</code></td><td><code>http://snomed.info/field/Concept.moduleId</code></td></tr><tr><td><code>effectiveTime</code></td><td><code>http://snomed.info/field/Concept.effectiveTime</code></td></tr><tr><td><code>sufficientlyDefined</code></td><td><code>http://snomed.info/field/Concept.sufficientlyDefined</code></td></tr></tbody></table>

### ICD-10 ![](https://1894725842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUjFUePuVzxE3xh52ynpe%2Fuploads%2FS7UONfwYsC7dXDjZYfhW%2Fpaid_badge.svg?alt=media\&token=1f66c56a-71a1-4fed-a20a-96bb67e55772)

ICD-10 and its national variants can be imported from XML release files using the ClaML format in the paid edition of Snow Owl, however this functionality is not exposed via FHIR requests; neither can such a code system be created using a `create` interaction.

ICD-10 URLs are typically following the naming convention described in HL7's [FHIR specification](https://hl7.org/fhir/R4B/icd.html): `http://hl7.org/fhir/sid/icd-10-[x]`, where the `-[x]` suffix is only included if it is a national variant. One exception is the German Modification where the publisher uses a different value.

Similarly to SNOMED CT resources, the `concept` array remains unpopulated in the response. ICD-10 concepts can still participate in lookup, validation or subsumption testing operations.

### LOINC ![](https://1894725842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUjFUePuVzxE3xh52ynpe%2Fuploads%2FS7UONfwYsC7dXDjZYfhW%2Fpaid_badge.svg?alt=media\&token=1f66c56a-71a1-4fed-a20a-96bb67e55772)

In the paid edition the official release archive can be used to populate the code system's contents. It is available over the FHIR API in a read-only fashion as the previous two toolings.

### Local Code Systems (LCS) ![](https://1894725842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUjFUePuVzxE3xh52ynpe%2Fuploads%2FS7UONfwYsC7dXDjZYfhW%2Fpaid_badge.svg?alt=media\&token=1f66c56a-71a1-4fed-a20a-96bb67e55772)

In Snow Owl's paid edition FHIR code system resources submitted as part of a `create` or `update` interaction (if no resource existed with the same ID earlier) become members of the LCS tooling. Custom properties may be defined when submitting the creation request and added to concepts of the code system.

The code system URL can be set upon creation and is checked for uniqueness.

The `concept` array is fully populated in LCS responses and `content` is set to `complete`.

#### Properties

User-defined properties listed in the top-level `property` elements of the resource get included in the LCS schema. The cardinality is set to `[0..*]`, which means concepts can have any number of properties associated with the same type code.

## Interactions

### read (instance)

GET requests that include the code system identifier as the final path segment return the current (non-versioned) resource state:

```http
GET /snowowl/fhir/CodeSystem/SNOMEDCT-UK-CL

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "CodeSystem",
  "id" : "SNOMEDCT-UK",
  "meta" : {
    "lastUpdated" : "2026-06-25T16:30:11.668Z"
  },
  "language" : "en",
  "text" : {
    "status" : "empty"
  },
  "url" : "http://snomed.info/sct",
  "version" : "http://snomed.info/sct/83821000000107",
  "title" : "SNOMED CT UK Monolith Edition",
  "status" : "active",
  "publisher" : "NHS England",
  "contact" : [{
    "telecom" : [{
      "system" : "url",
      "value" : "https://www.england.nhs.uk/"
    }]
  }],
  "description" : "SNOMED CT UK Monolith Edition",
  "caseSensitive" : true,
  "valueSet" : "http://snomed.info/sct/83821000000107?fhir_vs",
  "content" : "complete",
  "count" : 1148100,
  ...
}
```

Common parameters like `_format`, `_summary`, `_elements` and `_pretty` are also applicable. These are described on the previous page: [FHIR API](/snow-owl/rest-apis/fhir.md#common-request-parameters)

### vread (instance)

To retrieve a single historical version of the resource, use the following GET request:

<pre class="language-http"><code class="lang-http">GET /snowowl/fhir/CodeSystem/SNOMEDCT-UK-CL/_history/2026-04-08

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "CodeSystem",
  "id" : "SNOMEDCT-UK",
  "meta" : {
    "lastUpdated" : "2026-05-05T01:45:03.280Z"
  },
  "language" : "en",
  "text" : {
    "status" : "empty"
  },
<strong>  "url" : "http://snomed.info/sct", // [1]
</strong><strong>  "version" : "http://snomed.info/sct/83821000000107/version/20260408", // [2]
</strong>  "title" : "SNOMED CT UK Monolith Edition",
  "status" : "active",
<strong>  "date" : "2026-04-08T00:00:00Z", // [3]
</strong>  "publisher" : "NHS England",
  "contact" : [{
    "telecom" : [{
      "system" : "url",
      "value" : "https://www.england.nhs.uk/"
    }]
  }],
  "description" : "SNOMED CT UK Monolith Edition",
  "copyright" : "© 2026 International Health Terminology Standards Development Organisation 2002-2026. All rights reserved. SNOMED CT® was originally created by the College of American Pathologists. 'SNOMED' and 'SNOMED CT' are registered trademarks of International Health Terminology Standards Development Organisation, trading as SNOMED International. SNOMED CT has been created by combining SNOMED RT and a computer based nomenclature and classification known as Clinical Terms Version 3, formerly known as Read Codes Version 3, which was created on behalf of the UK Department of Health and is Crown copyright. This document forms part of the International Edition release of SNOMED CT® distributed by SNOMED International, which is subject to the SNOMED CT® Affiliate License, details of which may be found at https://www.snomed.org/snomed-ct/get-snomed.",
  "effectivePeriod" : {
<strong>    "start" : "2026-04-08T00:00:00Z" // [4]
</strong>  },
  "caseSensitive" : true,
  "valueSet" : "http://snomed.info/sct/83821000000107/version/20260408?fhir_vs",
  "content" : "complete",
<strong>  "count" : 1148100, // [5]
</strong>  ...
}
</code></pre>

Notable differences between a versioned and the current representation are marked with a comment in the code block above:

1. If a FHIR URL override value was set in resource settings at the time the version was created, it will be reflected in the response
2. Similarly, if the resource was configured to use its native `url` value as the FHIR version at the time it was created, it will also be reflected in the response
3. The effective time appears as the value of `date`
4. The effective time also appears as the value of `effectivePeriod.start`
5. Other properties like concept count or actual terminology content will reflect the state of the resource at version creation time

The version path parameter accepts the following values:

| Value                              | Behavior                                    |
| ---------------------------------- | ------------------------------------------- |
| `HEAD`                             | Returns the current resource representation |
| `LATEST`                           | Returns the most recent historical revision |
| Any other valid version identifier | Returns the specified historical revision   |

`HEAD` is implemented as a fallback to the regular resource read operation, while `LATEST` selects the latest historical version based on version timestamps.

### history (instance)

GET requests that include a resource identifier with a `_history` path segment added to the end return a FHIR `Bundle` of type `history`, containing historical revisions of the specified resource:

```http
GET /snowowl/fhir/CodeSystem/SNOMEDCT/_history?_summary=text

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "Bundle",
  "id" : "3o3jUNgQOxV8zkJ80mmwVl",
  "meta" : {
    "lastUpdated" : "2026-09-16T15:16:51.124Z",
    "tag" : [{
      "system" : "http://hl7.org/fhir/v3/ObservationValue",
      "code" : "SUBSETTED",
      "display" : "As requested, resource is not fully detailed."
    }]
  },
  "type" : "history",
  "total" : 96,
  "entry" : [{
    "fullUrl" : "https://{host}/snowowl/fhir/CodeSystem/SNOMEDCT/_history/2026-05-01",
    "resource" : {
      "resourceType" : "CodeSystem",
      "id" : "SNOMEDCT",
      "meta" : {
        "lastUpdated" : "2026-05-04T23:54:02.608Z"
      },
      "text" : {
        "status" : "empty"
      },
      "status" : "active",
      "content" : "complete",
      "count" : 531997
    }
  },
  {
    "fullUrl" : "https://{host}/snowowl/fhir/CodeSystem/SNOMEDCT/_history/2026-04-01",
    "resource" : {
      "resourceType" : "CodeSystem",
      "id" : "SNOMEDCT",
      "meta" : {
        "lastUpdated" : "2026-05-04T23:53:54.812Z"
      },
      "text" : {
        "status" : "empty"
      },
      "status" : "active",
      "content" : "complete",
      "count" : 530648
    }
  },
  {
  ...
  }]
}
```

{% hint style="warning" %}
Only versioned revisions are returned, not individual edits. The `HEAD` revision is also omitted from the history bundle.
{% endhint %}

Supported search parameters are:

<table><thead><tr><th width="168">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>_count</code></td><td>Limits the number of returned history entries (50 by default)</td></tr><tr><td><code>_since</code></td><td>Returns revisions created on or after the supplied ISO-8601 instant</td></tr><tr><td><code>_at</code></td><td><p>Returns revisions created on or before the supplied ISO-8601 instant</p><p></p><p>Note that while the <a href="https://www.hl7.org/fhir/search.html#date">specification</a> allows a wider set of comparisons for <code>date(time)</code> inputs, Snow Owl currently only supports <code>instant</code> values without a comparison operator prefix.</p></td></tr></tbody></table>

Allowed values for the `_sort` parameter:

<table><thead><tr><th width="170.33331298828125">Value</th><th>Behavior</th></tr></thead><tbody><tr><td><code>-_lastUpdated</code></td><td>Newest revisions first (default)</td></tr><tr><td><code>_lastUpdated</code></td><td>Oldest revisions first</td></tr><tr><td><code>none</code></td><td>Does not effectively override the default sort</td></tr><tr><td>Any other value</td><td><code>400 Bad Request</code> is returned</td></tr></tbody></table>

### update (instance)

PUT requests that include a resource identifier update an existing (local) code system or create a new instance:

```http
PUT /snowowl/fhir/CodeSystem/example-lcs-1

[Request headers]
X-Effective-Date: 2023-11-29
X-Author: user@host.domain
X-Owner: owner@host.domain
X-Owner-Profile-Name: Resource Owner
X-Bundle-Id: parent-bundle-id
Content-Type: application/fhir+json

[Request body]
{
  "resourceType": "CodeSystem",
  "id": "example-lcs-1",
  "text": {
    "status": "empty"
  },
  "url": "https://b2ihealthcare.com/codesystems/example-lcs-1",
  "version": "v1",
  "title": "Example LCS",
  "status": "draft",
  "content": "complete",
  "count": 2,
  "concept": [
    {
      "code": "C00",
      "display": "Parent concept"
    },
    {
      "code": "C00-1",
      "display": "Child concept",
      "property": [ {
          "code": "parent",
          "valueCode": "C00"
      } ]
    }
  ]
}
```

The response code is `201 Created` if the resource did not exist previously, and the URL is included in the `Location` response header. Existing code systems are updated and a `200 OK` response is returned instead.

The actual content of `Location` will differ depending on whether a versioned resource is sent in as the input or a draft one. The former will generate a `vread` interaction with the version value included, while the latter will be a URL that can be used to issue a `read` interaction on the most recent content.

If an error occurs during the update, a `400 Bad Request` response with an `OperationOutcome` resource as the response body is emitted instead.

The following request headers can be used to control certain aspects of the commit process:

<table><thead><tr><th width="168">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>X-Effective-Date</code></td><td>The effective date to use if a version identifier is present in the resource without a corresponding <code>date</code> element (defaults to the current date if neither the resource nor this header specifies a value)</td></tr><tr><td><code>X-Author</code></td><td>Sets the user identifier that the commit should be attributed to (defaults to the authenticated user)</td></tr><tr><td><code>X-Owner</code></td><td>Sets the owner of the resource, for access control purposes in external systems (defaults to the author or the authenticated user if the former is not set)</td></tr><tr><td><code>X-Owner-Profile</code></td><td>Sets the human-readable name of the owner of the resource, for presentation purposes in external systems (optional)</td></tr><tr><td><code>X-Bundle-Id</code></td><td>Specifies the parent bundle's resource identifier (defaults to the root bundle if not set)</td></tr></tbody></table>

{% hint style="info" icon="burst-new" %}
Snow Owl now preserves the `name` property supplied in imported `CodeSystem` resources. Previously generated or derived names are no longer used when a resource name is provided by the import payload.
{% endhint %}

### delete (instance)

A DELETE request removes an existing code system:

```http
DELETE /snowowl/fhir/CodeSystem/example-lcs-1?force=true

[Request headers]
X-Author: user@host.domain

[Response]
204 No Content
```

Successful removal of a code system resource results in a `204 No Content` response. Code systems that have been published can not be removed without adding the `force=true` query parameter to signal a forced deletion – this option in turn is only available to administrators.

{% hint style="info" icon="burst-new" %}
The `X-Author` request header is optional, the default value corresponds to the authenticated user.
{% endhint %}

### create (type)

POST requests are very similar to the instance-level `update` interactions with the following important difference: the identifier included in the request body is ignored and a new, random one is generated from scratch. The request path should also omit the path segments corresponding to the resource identifier:

<pre class="language-http"><code class="lang-http">POST /snowowl/fhir/CodeSystem

[Request headers]
X-Effective-Date: 2023-11-29
X-Author: user@host.domain
X-Owner: owner@host.domain
X-Owner-Profile-Name: Resource Owner
X-Bundle-Id: parent-bundle-id
Content-Type: application/fhir+json

[Request body]
{
  "resourceType": "CodeSystem",
  // "id": "..." is not used by the server
  "text": {
    "status": "empty"
  },
<strong>  "url": "https://b2ihealthcare.com/codesystems/example-lcs-1",
</strong>  "name": "ExampleLcsOne",
  "version": "v1",
  "title": "Example LCS",
  "status": "active",
  "content": "complete",
  "count": 2,
  "concept": [
    {
      "code": "C00",
      "display": "Parent concept"
    },
    {
      "code": "C00-1",
      "display": "Child concept",
      "property": [ {
          "code": "parent",
          "valueCode": "C00"
      } ]
    }
  ]
}

[Response]
201 Created

[Response headers]
Location: http://{host}/snowowl/fhir/CodeSystem/ExWn1g2gdIIQ/_history/v1
</code></pre>

{% hint style="warning" %}
FHIR URLs in Snow Owl must be unique. If a resource is submitted to the `create` interaction where the URL matches the value in an already persisted resource, an `update` will take place instead.
{% endhint %}

The response code is `201 Created` if the interaction is successful and a new resource has been created, `200 OK` if an update was performed.

As mentioned above, the request URL that can be used in e.g. follow-up `read` or `vread` interactions is included in the `Location` response header; the latter is provided if the input resource also contained version information.

### search (type)

GET requests targeting the endpoint corresponding to the resource type return all code systems that satisfy the specified search criteria, in the form of query parameters. The following example uses the `count` summary mode to determine the total number of code systems registered in the system, without returning any of the matches:

```http
GET /snowowl/fhir/CodeSystem?_summary=count

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType": "Bundle",
  "id": "codesystems",
  "meta": {
    "lastUpdated": "2023-11-29T16:15:36.187124Z"
  },
  "type": "searchset",
  "total": 1685
}
```

{% hint style="danger" %}
The specification allows `search` interactions to be initiated via a POST request to `/fhir/CodeSystem/_search` using `name=value` parameter pairs encoded with MIME type  `x-www-form-urlencoded`, however this is unsupported in Snow Owl and results in a `405 Method Not Allowed` response.
{% endhint %}

The following search parameters are supported:

<table><thead><tr><th width="92">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>_id</code> </td><td>Matches code systems by logical identifier</td></tr><tr><td><code>name</code> </td><td>Matches code systems by name (in Snow Owl this is set to the logical identifier)</td></tr><tr><td><code>title</code></td><td>Matches code systems by title (Snow Owl uses exact, phrase and prefix matching during its lexical search activities)</td></tr><tr><td><code>url</code></td><td>Matches code systems by their assigned <code>url</code> value</td></tr><tr><td><code>version</code> </td><td>Matches code systems by their <code>version</code> value</td></tr><tr><td><code>status</code> </td><td>Matches code systems by resource status (e.g. draft, active, etc.)</td></tr></tbody></table>

## Operations

### $lookup

Both GET as well as POST HTTP methods are supported. Concepts are queried based on `code`,  `version`, `system` or `Coding`. Designations are included as part of the response as well as supported concept properties when requested. Date parameters are not supported.

The following example request retrieves details about the SNOMED CT concept `128927009|Procedure by method|`, including properties "inactive" and "Method" (a SNOMED CT attribute), using the latest version of the code system:

```http
GET /snowowl/fhir/CodeSystem/$lookup?system=http://snomed.info/sct&code=128927009&property=inactive&property=http://snomed.info/id/260686004

[Query parameters (repeated for clarity)]
system: http://snomed.info/sct
code: 128927009
property: inactive
property: http://snomed.info/id/260686004

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "name",
      "valueString": "SNOMEDCT" // The code system name (resolved from the resource)
    },
    {
      "name": "display",
      "valueString": "Procedure by method" // The concept's display name
    },
    {
      "name": "version",
      // The resolved code system version
      "valueString": "http://snomed.info/sct/900000000000207008"
    },    
    {
      "name": "property",
      "part": [
        {
          "name": "code",
          "valueCode": "inactive"
        },
        {
          "name": "value",
          "valueBoolean": false // The value for the concept property "inactive"
        },
        {
          "name": "description",
          "valueString": "inactive"
        }
      ]
    },
    {
      "name": "property",
      "part": [
        {
          "name": "code",
          "valueCode": "260686004" // The SCTID of the attribute "Method"
        },
        {
          "name": "value",
          "valueCode": "129264002" // The SCTID of the destination concept, "Action"
        }
      ]
    }
  ]
}
```

### $validate-code

Both GET as well as POST HTTP methods are supported.

The example request below validates that `128927009|Procedure by method|` is present in SNOMED CT, selecting the resource to use for validation using a versioned identifier (an instance-level invocation):

```http
GET /snowowl/fhir/CodeSystem/$validate-code?code=128927009&system=http://snomed.info/sct&version=http://snomed.info/sct/900000000000207008

[Query parameters (repeated for clarity)]
code: 128927009
system: http://snomed.info/sct
version: http://snomed.info/sct/900000000000207008

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "Parameters",
  "parameter" : [{
    "name" : "system",
    "valueUri" : "http://snomed.info/sct"
  },
  {
    "name" : "version",
    "valueString" : "http://snomed.info/sct/900000000000207008"
  },
  {
    "name" : "code",
    "valueCode" : "128927009"
  },
  {
    "name" : "display",
    "valueString" : "Procedure by method"
  },
  {
    "name" : "result",
    "valueBoolean" : true
  }]
}
```

### $subsumes

Both GET as well as POST HTTP methods are supported.&#x20;

Subsumption testing is supported for all terminologies, including SNOMED CT. The example uses the un-versioned SNOMED CT code system (via the URL in the `system` query parameter) to determine whether `409822003|Domain Bacteria|` is an ancestor of `112283007|Escherichia coli|` (type-level invocation):

```http
GET /snowowl/fhir/CodeSystem/$subsumes?codeA=409822003&codeB=112283007&system=http://snomed.info/sct&version=http://snomed.info/sct/900000000000207008

[Query parameters (repeated for clarity)]
codeA: 409822003
codeB: 112283007
system: http://snomed.info/sct
version: http://snomed.info/sct/900000000000207008

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "outcome",
      "valueCode": "subsumes"
    }
  ]
}
```

The response is positive (and encouraging). Changing the role of the two codes gives us a `subsumed-by` result instead.

### $set-include-in-capabilities (instance)

The operation is used to add or remove a code system (or version) to/from the `TerminologyCapabilities.codeSystem` list shown in [Metadata](/snow-owl/rest-apis/fhir/metadata.md).

Use this operation when:

* You want Snow Owl to advertise an existing code system not yet appearing in the terminology list
* You want to expose another version under an existing code system entry

#### "In" parameters

<table><thead><tr><th width="180.3333740234375">Name</th><th width="96.333251953125">Cardinality</th><th width="109.9998779296875">Type</th><th>Documentation</th></tr></thead><tbody><tr><td>includeInCapabilities</td><td>1..1</td><td><a href="https://www.hl7.org/fhir/datatypes.html#boolean">boolean</a></td><td>Controls membership in <code>TerminologyCapabilities.codeSystem</code></td></tr></tbody></table>

#### "Out" parameters

<table><thead><tr><th width="179.6666259765625">Name</th><th width="96.333251953125">Cardinality</th><th width="109.9998779296875">Type</th><th>Documentation</th></tr></thead><tbody><tr><td>result</td><td>1..1</td><td><a href="https://www.hl7.org/fhir/datatypes.html#boolean">boolean</a></td><td>Indicates whether terminology capability resource content changed as a result of the operation (failures are typically reported as <code>OperationOutcome</code> resources, in more detail)</td></tr></tbody></table>

Both GET and POST methods are accepted. In the former case the input value can be supplied as a query parameter:

```http
GET /snowowl/fhir/CodeSystem/my-lcs/$set-include-in-capabilities?includeInCapabilities=true

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "Parameters",
  "parameter" : [{
    "name" : "result",
    "valueBoolean" : true
  }]
}
```

Once registered, subsequent responses should include the selected code system in `TerminologyCapabilities`:

```http
GET /snowowl/fhir/metadata?mode=terminology

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "TerminologyCapabilities",
  ...
  "codeSystem" : [{
    "uri" : "https://b2ihealthcare.com/codesystems/my-lcs",
    "version" : [{
      "code" : "v1",
      "isDefault" : true,
      "compositional" : true
    }],
    "subsumption" : true
  }],
  ...
}
```

### $set-as-default (instance)

When multiple independent code system resources share the same FHIR URL (such as in the case of SNOMED CT or LOINC), individual Editions/Extensions will be presented as versions of the same entry in `TerminologyCapabilities.codeSystem`. This operation is used to control where requests are routed to when they only mention the common URL, and has no effect on the outcome when clients specify an appropriate "version" parameter for their request.

{% hint style="info" %}
In the absence of explicit "set as default" flags the latest version of SNOMED CT's International release is considered to be the subject.
{% endhint %}

#### "In" parameters

None required.

#### "Out" parameters

<table><thead><tr><th width="77.6666259765625">Name</th><th width="96.333251953125">Cardinality</th><th width="87.333251953125">Type</th><th>Documentation</th></tr></thead><tbody><tr><td>result</td><td>1..1</td><td><a href="https://www.hl7.org/fhir/datatypes.html#boolean">boolean</a></td><td>Indicates whether terminology capability resource content changed as a result of the operation (failures are typically reported as <code>OperationOutcome</code> resources, in more detail)</td></tr></tbody></table>

As an example, to use the Swedish extension for operations where only `system` is set, issue the following request:

```http
GET /snowowl/fhir/CodeSystem/SNOMEDCT-SE/$set-as-default

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "Parameters",
  "parameter" : [{
    "name" : "result",
    "valueBoolean" : true
  }]
}
```

A call to [#usdlookup](#usdlookup "mention") should now resolve Swedish concepts by default:

```http
GET /snowowl/fhir/CodeSystem/$lookup?system=http://snomed.info/sct&code=1001000052107

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "Parameters",
  "parameter" : [{
    "name" : "name",
    "valueString" : "SNOMEDCT-SE"
  },
  {
    "name" : "display",
    "valueString" : "Simultaneous pulmonary congestion and cardiomegaly"
  },
  {
    "name" : "version",
    "valueString" : "http://snomed.info/sct/45991000052106"
  }]
}
```