Code System

Ontoserver supports the $find-matches, $lookup and $subsumes operations for both explicit and implicit code systems.

Find Matches Operation (FHIR Maturity Level: 0)

Given a set of code-value properties, return one or more possible matching codes.

This is an immature part of the FHIR Specification, and only initial support is provided, and both the exact and compositional parameters will have no impact on the output. The implementation effectively behaves aligned with exact=true and compositional=false, and as such is aimed at machine/automated use rather than human/interactive use.

Lookup Operation

A lookup on a code within a given code system can be done using a GET or POST request such as:

http://ontoserver.base.url/fhir/CodeSystem/$lookup

where the code and system to lookup must be provided in the parameters of a GET request, or the body of a POST request.

The $lookup operation is supported according to its definition in the FHIR Specification, and supports the code, system, version and coding and property (including lang.X values) parameters. The date parameter is not currently supported.

Successful lookups on SNOMED codes will include designations for fully specified names and synonyms, as well as properties for any parents or children, and inactive status for inactive codes.

Subsumes Operation

Subsumes tests whether a given concept subsumes another concept. The subsumes operation can be invoked using a GET or POST request, at either the instance or type level, such as:

http://ontoserver.base.url/fhir/CodeSystem/[id]/$subsumes (instance level)

http://ontoserver.base.url/fhir/CodeSystem/$subsumes (type level)

where the codeA and codeB to compare must be provided in the parameters of a GET request, or the body of a POST request, or the codingA and codingB parameters in the body of a POST request. The code system for the codes in a type-level request is identified by the system parameter, and optionally the version parameter.

The $subsumes operation is supported according to its definition in the FHIR Specification, and supports the codeA, codeB, system, version, codingA, and codingB parameters.

Validate Code

The validate-code operation checks whether a given code is valid for the given CodeSystem. This is done by sending a GET or POST request to:

http://ontoserver.base.url/fhir/CodeSystem/[id]/$validate-code (instance level)

http://ontoserver.base.url/fhir/CodeSystem/$validate-code (type level)

The CodeSystem for a type-level request is specified using the url parameter. Supplying an in-line CodeSystem via the codeSystem parameter within a Parameters object supplied to a POST-style type-level request is not supported.

The code (with an optional version) is specified as a parameter to a GET request, or in the body of a POST request (POST requests may alternatively provide a coding parameter. If a display parameter is provided, the operation will also verify whether the display is correct for the specified concept.

More details on the validate-code operation can be found in the FHIR value set specification.

Loading SNOMED CT and LOINC

As well as loading SNOMED CT and LOINC instances via Syndication using the /api/indexCodeSystem API, SNOMED CT and LOINC can also be loaded by directly POSTing the following to the /fhir/CodeSystem/$x-upload-external API: * For SNOMED CT - A single RF2 release ZIP file, OR; - Multiple RF2 release ZIP files as multipart/form-data. * For LOINC - A single LOINC release ZIP file.

In any case, this operation takes two query parameters:

  • system

  • version

The supported values for system are http://snomed.info/sct and http://loinc.org, and the corresponding version parameter must be a full SNOMED CT Version URI for SNOMED CT, or the LOINC x.yy version (for example 2.68).

The body of the POST request must have a Content-Type of application/zip and contain either the corresponding LOINC release files or SNOMED CT SNAPSHOT/FULL release files OR, the body of the POST request must have a Content-Type of multipart/form-data and contain the parameters and multiple RF2 ZIP files that will be treated as a whole.

Loading OWL, CLAML, HGNC, and other terminologies

A set of open-source transforms from OWL, CLAML, HGNC, and a range of other formats to a FHIR CodeSystem that can be loaded into Ontserver are available:

Explicit Code Systems

Explicit Code Systems support SCRUD (Search, Create, Read, Update and Delete) operations as per the FHIR Specification rules for REST and CodeSystems.

Search for explicit code systems is limited to the following parameters:

  • the name, _id, description and publisher parameters (these 3 additionally support the :exact, :contains and :missing modifiers)

  • the url and system parameters, including the :missing, :above and :below modifiers, and

  • the identifier, version, status and _tag parameters, including code, |code, system| and system|code formats, and the :missing modifier

  • the _lastUpdated parameter, including the lt, gt, ge, le and eq prefixes, and the :missing modifier. This parameter can be provided multiple times for AND semantics, to support use cases such as searching between 2 times

  • the extension x-syndication-status parameter with values true and false

Of these, name, _id, description, publisher, url, system, version, status and x-syndication-status can be used to sort search results. _lastUpdated may also be used to sort results, but not as a search parameter.

Implicit SNOMED CT Code Systems

Any SNOMED CT ontologies included in the Ontoserver instance are available as implicit CodeSystem resources, using a url of the format:

http://snomed.info/sct[/edition[/version]] where edition refers to the SNOMED CT module (e.g. SNOMED CT-AU) and version refers to the module’s version. More details can be found in the SNOMED CT URI Standard.

For example, the 20171031 version of SNOMED CT-AU has the url:

http://snomed.info/sct/32506021000036107/version/20171031

If a version is not supplied, Ontoserver will attempt to find the most recent version using the yyyymmdd version format.

If an edition is not supplied, Ontoserver will attempt to use the most recent version of the edition configured as the default edition. If it cannot find the default edition, and there is only one other edition present, it will use the most recent version of that.

Implicit LOINC Code Systems

Any LOINC distributions loaded into the Ontoserver instance are available as implicit CodeSystem resources, using a url of the format:

http://loinc.org[/version]] where version refers to the distribution’s version.

For example, the 2.64 version of LOINC has the url:

http://loinc.org/2.64

If a version is not supplied, Ontoserver will attempt to find the most recent version using the x.yy version format.