ValueSet

Introduction

Snow Owl TS supports interactions and operations related to value sets, as described in the FHIR R5 terminology service specification. For certain toolings implicit value sets are also expandable; these are described below in detail.

Tooling support

SNOMED CT (implicit)

Value set URIs following SNOMED International's URI format are evaluated based on the associated SNOMED CT code system's content. The following URIs can be set as the url parameter of the request:

  • http://snomed.info/sct/900000000000207008?fhir_vs - all concepts of the International Edition (may include a version suffix as well).

The implicit value set URI for SNOMED CT code systems should always include a module identifier to avoid confusion.

  • http://snomed.info/sct/900000000000207008?fhir_vs=isa/409822003 - all concepts of the International Edition that are descendants of 409822003|Domain bacteria|

  • http://snomed.info/sct/900000000000207008?fhir_vs=refset - all reference set identifier concepts in the International Edition

  • http://snomed.info/sct/900000000000207008?fhir_vs=refset/733073007 - all concepts of the International Edition that are members of the reference set 733073007|OWL axiom reference set|

Persisted value sets

Regular value sets are only supported in the paid edition of Snow Owl.

Interactions

read (instance)

GET requests that include the value set identifier as the final path segment(s) return the resource state:

GET /snowowl/fhir/ValueSet/xJn9vXKMrkU9F

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

{
  "resourceType": "ValueSet",
  "id": "xJn9vXKMrkU9F",
  "meta": {
    "lastUpdated": "2023-11-30T10:22:59.716Z"
  },
  "text": {
    "status": "empty",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "https://b2ihealthcare.com/valuesets/xJn9vXKMrkU9F",
  "name": "xJn9vXKMrkU9F",
  "title": "Example Value Set",
  "status": "draft",
  "compose": {
    "include": [
      {
        "system": "http://snomed.info/sct/900000000000207008",
        "version": "2023-10-01",
        "filter": [
          {
            "property": "expression",
            "op": "=",
            "value": "<<448771007|Canis lupus subspecies familiaris (organism)|"
          }
        ]
      }
    ]
  }
}

The returned response uses a filter mentioned in Filters that is supported by SNOMED CT – this enables including or excluding concepts using an ECL expression.

Similarly to CodeSystem read interactions, query parameters _format, _summary, _elements and _pretty are also applicable, see Common request parameters for a detailed description of these options.

update (instance)

PUT requests that include a resource identifier will update an existing value set or create a new instance:

PUT /snowowl/fhir/ValueSet/xJn9vXKMrkU9F

[Request headers]
X-Author: user@host.domain
Content-Type: application/fhir+json

[Request body]
{
  "resourceType": "ValueSet",
  "id": "xJn9vXKMrkU9F",
  "text": {
    "status": "empty",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "https://b2ihealthcare.com/valuesets/xJn9vXKMrkU9F",
  "name": "xJn9vXKMrkU9F",
  "title": "Example Value Set",
  "status": "draft",
  "compose": {
    "include": [
      {
        "system": "http://snomed.info/sct/900000000000207008",
        "version": "2023-10-01",
        "filter": [
          {
            "property": "expression",
            "op": "=",
            "value": "<<448771007|Canis lupus subspecies familiaris (organism)|"
          }
        ]
      },
      // Added inclusion
      {
        "system": "http://snomed.info/sct/900000000000207008",
        "version": "2023-10-01",
        "filter": [
          {
            "property": "expression",
            "op": "=",
            "value": "<<448169003|Felis catus (organism)|"
          }
        ]
      }
    ]
  }
}

The response code is 201 Created if the resource did not exist previously, and the URL is included in the Location response header. Existing value sets (like in the example above) 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)

Value sets are currently limited to a single code system and version (domain) they can refer to when including or excluding concepts.

delete (instance)

A DELETE request removes an existing value set:

DELETE /snowowl/fhir/ValueSet/xJn9vXKMrkU9F

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

[Response]
204 No Content

Successful removal of a resource results in a 204 No Content response.

Value sets that have been published can not be removed without adding the force=true query parameter to signal a forced deletion (this option is only available to administrators however). The example value set was never published and so can be deleted without this option.

create (type)

In create interactions a POST request is sent to the path corresponding to the resource type. Any identifier included in the request body is ignored and a new, random one is generated from scratch.

POST /snowowl/fhir/ValueSet

[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": "ValueSet",
  // "id": "..." is not used by the server
  "text": {
    "status": "empty",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "url": "https://b2ihealthcare.com/valuesets/basic-dose-forms",
  "title": "Basic dose forms",
  "version": "v1",
  "status": "active",
  "compose": {
    "include": [ {
      "system": "http://snomed.info/sct/900000000000207008",
      "version": "2021-01-31",
      "filter": [ {
          "property": "expression",
          "op": "=",
          "value": "<736478001|Basic dose form (basic dose form)|"
      } ]
    } ]
  }
}

[Response]
201 Created

[Response headers]
Location: http://<host>/snowowl/fhir/ValueSet/vmfRt532iS

The response code is 201 Created if the interaction is successful. The request URL that can be used in eg. follow-up read interactions is included in the response header named Location.

search (type)

GET requests with a request path that points to the resource type returns all value sets that satisfy the specified search criteria, in the form of query parameters. The following example uses the count summary mode to determine the number of draft value sets in the system, without returning any of the matches:

GET /snowowl/fhir/ValueSet?status=draft&_summary=count

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

{
  "resourceType": "Bundle",
  "id": "valuesets",
  "meta": {
    "lastUpdated": "2023-11-30T14:29:15.724489Z"
  },
  "type": "searchset",
  "total": 188
}

Just as with code system resources, POST requests are unsupported in Snow Owl and will be met with a 405 Method Not Allowed response.

The following search parameters are supported:

  • _id -> matches value sets by logical identifier

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

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

  • url -> matches value sets by their assigned url value

  • version -> matches value sets by their version value

  • status -> matches value sets by resource status (eg. draft, active, etc.)

Operations

$expand

Snow Owl supports the following input parameters for value set expansion:

  • url -> the URI of the value set to expand (can be an implicit or an explicit one)

  • valueSetVersion -> the version of the value set for use for the expansion

  • activeOnly -> to return only active codes in the response

  • filter -> to filter the results lexically

  • includeDesignations -> whether to include all designations or not in the returned response

  • displayLanguage -> to select the language for the returned display values

  • count -> to select the number of codes to be returned in the expansion (10 by default)

  • after -> state tracking parameter for concept set paging

The value set with expanded concepts is returned in entirety for this request. It includes a link that can be followed to retrieve the next page of expanded concepts:

GET /snowowl/fhir/ValueSet/$expand?url=https://b2ihealthcare.com/valuesets/basic-dose-forms&count=3

[Query parameters (repeated for clarity)]
url: https://b2ihealthcare.com/valuesets/basic-dose-forms
count: 3

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

{
  "resourceType": "ValueSet",
  "id": "vmfRt532iS",
  "meta": {
    "lastUpdated": "2023-11-30T10:22:59.716Z"
  },
  "url": "https://b2ihealthcare.com/valuesets/basic-dose-forms",
  "name": "vmfRt532iS",
  "title": "Basic dose forms",
  "status": "active",
  "compose": {
    "include": [
      {
        "system": "http://snomed.info/sct/900000000000207008",
        "version": "2021-01-31",
        "filter": [
          {
            "property": "expression",
            "op": "=",
            "value": "<736478001|Basic dose form (basic dose form)|"
          }
        ]
      }
    ]
  },
  // This element does not appear when the VS is requested in a read interaction
  "expansion": {
    "identifier": "vmfRt532iS",
    // Link to the next page in the expansion (includes the "_after" parameter)
    "next": "https://uat.snowray.app/snowowl/fhir/ValueSet/$expand?url=https://b2ihealthcare.com/valuesets/basic-dose-forms&displayLanguage=en-US;q=0.8,en-GB;q=0.6,en;q=0.4&count=3&after=AoEqMTIzMDIxNzAwNw==",
    "timestamp": "2023-11-30T13:07:32.254Z",
    "total": 71,
    // The number of results on a single page was limited to 3 by parameter "_count"
    "contains": [
      {
        "system": "codesystems/SNOMEDCT/2021-01-31",
        "code": "1230183009",
        "display": "Dispersion (basic dose form)"
      },
      {
        "system": "codesystems/SNOMEDCT/2021-01-31",
        "code": "1230206006",
        "display": "Compressed lozenge (basic dose form)"
      },
      {
        "system": "codesystems/SNOMEDCT/2021-01-31",
        "code": "1230217007",
        "display": "Molded lozenge (basic dose form)"
      }
    ]
  }
}

Supplying a value set as part of the request (via the input parameter valueSet) is not supported – nor can additional resources be supplied for expansion via the unofficial

$validate-code

The operation is supported both on the instance level (in this case the value set is located by resource ID) as well as the type level (a canonical URL must be supplied in the url input parameter to identify the value set to use).

Codes can only be validated against persisted value sets, not implicit ones.

Encountering any of the following conditions will fail the code validation check:

  • The specified value set does not exist

  • The value set does not contain the specified code in its expansion

  • The code does not exist in the code system specified in the request (the corresponding parameter, system is mandatory in Snow Owl)

  • The specified code system version differs from the version referenced by the value set

The following example checks whether 429885007|Bar| satisfies the aforementioned conditions in the value set containing all basic dose forms we created earlier:

GET /snowowl/fhir/ValueSet/$expand?url=https://b2ihealthcare.com/valuesets/basic-dose-forms&system=http://snomed.info/sct/900000000000207008&code=429885007

[Query parameters (repeated for clarity)]
url: https://b2ihealthcare.com/valuesets/basic-dose-forms
system: http://snomed.info/sct/900000000000207008
code: 429885007

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

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "message",
      "valueString": "OK"
    },
    {
      "name": "display",
      "valueString": "Bar"
    }
  ]
}

Last updated