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:
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:
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 (inyyyyMMdd
format)
code:
sufficientlyDefined
type:boolean
URI:http://snomed.info/field/Concept.sufficientlyDefined
A boolean value derived from the concept's
definitionStatusId
(set totrue
if the original value is900000000000073002|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:
Common parameters like _format
, _summary
, _elements
and _pretty
are also applicable. These are described on the previous page: Common request parameters
update (instance)
PUT requests that include a resource identifier update an existing (local) code system or create a new instance:
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 correspondingdate
elementX-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 systemsX-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:
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:
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:
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 identifiername
-> 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 assignedurl
valueversion
-> matches code systems by theirversion
valuestatus
-> 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:
$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):
$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):
The response is positive (and encouraging). Changing the role of the two codes gives us a subsumed-by
result instead.
Last updated