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.

As SNOMED CT code systems contain a considerable amount of concepts, resource responses for this tooling do not include a concept array and content is always set to not-present to highlight this fact:

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/731000124108"/>
  ...
  <name value="SNOMEDCT-US"/>
  <title value="SNOMED CT US Extension"/>
  <status value="active"/>
  <publisher value="NIH - National Library of Medicine"/>
  ...  
  <content value="not-present"/>
  <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:

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

[Query parameters (repeated for clarity)]
system: 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>
</Parameters>

Filters

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

  • code: expression operator: = value: <ECL expression>

    • matches concepts using the Expression Constraint Language

  • code: expressions operator: = value: <true|false>

    • specifies whether Post-Coordinated Expressions should be included in the filtered result set or not (even though the filter is recognized, Snow Owl currently does not store PCEs)

  • code: concept operator: is-a value: <conceptId>

    • matches the descendants of the specified parent concept

  • code: concept operator: in value: <refsetId>

    • matches concepts that are members of the specified reference set

Properties

All SNOMED CT relationship types are supported and can be returned along with concept data if requested. An example can be seen below:

  • code: 288556008 (the attribute concept's ID) type: code URI: http://snomed.info/id/288556008 description: Before

In addition to these (and the common properties that are applicable to all code systems), Snow Owl can also return the following set of SNOMED CT-specific concept properties:

  • code: inactive type: boolean URI: http://snomed.info/field/Concept.inactive

    • The concept's active RF2 property (inverted)

  • code: moduleId type: code URI: http://snomed.info/field/Concept.moduleId

    • The concept's moduleId RF2 property

  • code: effectiveTime type: string URI: http://snomed.info/field/Concept.effectiveTime

    • The concept's effectiveTime RF2 property (in yyyyMMdd format)

  • code: sufficientlyDefined type: boolean URI: http://snomed.info/field/Concept.sufficientlyDefined

    • A boolean value derived from the concept's definitionStatusId (set to true if the original value is 900000000000073002|Defined|, false otherwise)

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: 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 with content set to not-present in the response. ICD-10 concepts can still participate in lookup, validation or subsumption testing operations.

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.

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)

Standard GET requests that include the identifier as the final path segment(s) return the code system's current (or versioned) state:

GET /snowowl/fhir/CodeSystem/SNOMEDCT-UK-CL/2023-08-02

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

{
  "resourceType": "CodeSystem",
  "id": "SNOMEDCT-UK-CL/2023-08-02",
  "meta": {
    "lastUpdated": "2023-10-17T15:44:27.568Z"
  },
  "language": "en",
  "text": {
    "status": "empty",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "http://snomed.info/sct/999000011000000103",
  ...  
  "name": "SNOMEDCT-UK-CL/2023-08-02",
  "title": "SNOMED CT UK Clinical Extension",
  "status": "active",
  "date": "2023-08-02T00:00:00Z", // Versioned resources include the "date" property
  "publisher": "NHS England",
  "contact": [ {
    "telecom": [ {
      "system": "url",
      "value": "https://www.england.nhs.uk/"
    } ]
  } ],
  "description": "SNOMED CT UK Clinical Extension",
  ...
}

update (instance)

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

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",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "https://b2ihealthcare.com/codesystems/example-lcs-1",
  "name": "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.

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 non-standard request headers can be used to control certain aspects of the commit process:

  • X-Effective-Date -> the effective date to use if a version identifier is present in the resource without a corresponding date element

  • X-Author -> sets the user identifier that the commit should be attributed to (defaults to the authenticated user)

  • X-Owner -> 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)

  • X-Owner-Profile -> sets the human-readable name of the owner of the resource, for presentation purposes in external systems

  • X-Bundle-Id -> specifies the parent bundle's resource identifier (defaults to the root bundle if not set)

delete (instance)

A DELETE request removes an existing code system:

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.

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:

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",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "https://b2ihealthcare.com/codesystems/example-lcs-1",
  "name": "example-lcs-1",
  "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

The response code is 201 Created if the interaction is successful. As mentioned above, the resource URL that can be used in eg. follow-up read interactions is included in the Location response header.

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:

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
}

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.

The following search parameters are supported:

  • _id -> matches code systems by logical identifier

  • name -> matches code systems by name (in Snow Owl this is set to the logical identifier)

  • title -> matches code systems by title (Snow Owl uses exact, phrase and prefix matching during its lexical search activities)

  • url -> matches code systems by their assigned url value

  • version -> matches code systems by their version value

  • status -> matches code systems by resource status (eg. draft, active, etc.)

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:

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 URL)
    },
    {
      "name": "display",
      "valueString": "Procedure by method" // The concept's display name
    },
    {
      "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):

GET /snowowl/fhir/CodeSystem/SNOMEDCT/2021-07-31/$validate-code?code=128927009

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

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

$subsumes

Both GET as well as POST HTTP methods are supported.

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

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

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

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

Last updated