Ontoserver Postman

Value Set

Ontoserver supports the $expand and $validate-code operations for both explicit and implicit value sets.

Expand

A ValueSet resource can be expanded using a GET or POST request to a URL such as:

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

http://ontoserver.base.url/fhir/ValueSet/$expand (type-level)

The value set to be expanded in a type-level request is identified by the url parameter or the context if using a GET-style request. Potential values for these parameters are explained in detail in the following sections.

Alternatively, if a type-level request is sent using POST, the value set to be expanded can be specified either using the url or context parameter in a Parameters object of the POST body, or as a JSON/XML resource, in the valueSet parameter of a Parameters object (if valueSet is the only parameter being provided to the expand request, the JSON/XML resource may be passed as the POST body without a surrounding Parameters object).

A value set expansion can also be controlled using the following parameters:

Parameter Type Description
filter string A text filter that is applied to restrict the codes that are returned (this is useful in a UI context). Ontoserver implements a multi-prefix match scoring algorithm.
count integer Paging support - how many codes should be provided in a partial view. If count = 0, the client is asking how large the expansion is.
offset integer Paging support - where to start if a subset is desired (default = 0). This refers to items, not pages, i.e. offset = 2 means that the second matching record will be returned, not the second page.
activeOnly boolean Whether or not inactive concepts are included in the expansion (false by default)
includeDesignations boolean Whether or not concepts included in the expansion should also come with their designations (false by default)
includeDefinition boolean Whether or not to include the logical definition and metadata of the value set in the expansion (true by default)
context uri A reference to an element in a profile, whose terminology binding should be used for the expansion, e.g. http://hl7.org/fhir/StructureDefinition/DiagnosticReport#DiagnosticReport.category
displayLanguage code Specifies the language to be used for description in the expansions i.e. the language to be used for ValueSet.expansion.contains.display

“Pre-expanded” value sets

In some case, for example when there is no underlying CodeSystem available, it is possible to include content for the ValueSet.expansion element in the ValueSet resource and have this used instead of the terminology server explicitly computing the ValueSet expansion.

In this case the terminology server needs to ensure that the supplied expansion is compatible with any additional parameters passed to the ValueSet/$expand operation, as per the first step documented here: https://www.hl7.org/fhir/valueset.html#expansion. To do this is looks at the values provided in the ValueSet.expansion.parameter element and compares these to the parameters passed to the $expand operation.

Currently the following conditions must be met:

  • At least one parameter must be provided.
  • CodeSystem supplements may not have been used or requested.
  • The force-system-version parameter must not be provided.
  • If the version parameter is provided, it must match the version of the resolved CodeSyste if there is one available.
  • If the version parameter is not provided, the filter parameter must not be provided.
  • If the filter parameter is provided, it must match the filter parameter provided to the $expand operation.
  • If the activeOnly parameter is provided, it must match value of the activeOnly parameter provided to the $expand operation.
  • If the activeOnly parameter is not provided, the activeOnly parameter must not be provided to the $expand operation or must be false.
  • If the offset parameter is provided, it must be 0 and the value of the offset parameter provided to the $expand operation, if any, must be 0.

More details on the expand operation can be found in the FHIR value set specification.

Validate Code

The validate-code operation checks whether a given code is valid within a given ValueSet resource. This is done by sending a GET or POST request to:

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

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

The ValueSet for a type-level request is specified using the url parameter. In the case of a POST-style type-level request, the ValueSet may alternatively be provided as an XML/JSON resource in the valueSet parameter within a Parameters object.

The code (with a system and optionally a 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.

Explicit Value Sets

Explicit Value Sets in Ontoserver support SCRUD (Search, Create, Read, Update and Delete) operations as per the FHIR Specification rules for REST and ValueSets.

Search

Search for explicit value sets 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 parameter, including the :missing, :above and :below modifiers, and
  • the identifier, version, status, _tag, context and context-type 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
  • the context-type-value parameter

Composite search parameters are supported, so all parameters can be used multiple times, for AND semantics, or with comma-separated values for OR semantics.

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

Definition

Ontoserver supports $expand and $validate-code on explicit Value Sets that reference SNOMED CT, LOINC, or any FHIR CodeSystem that it stores. A Value Set can be defined using ValueSet.compose.include.filter (and ValueSet.compose.exclude.filter) constraints that reference the properties and filters defined by the FHIR Code System as per Properties and Filters.

Moreover, the built-in filters we support for any FHIR Code System that you upload (whether or not you declare them) are:

  • concept (with operators =, in, not-in, is-a, is-not-a, regex, generalizes, and descendent-of)
  • parent and child (=, in, not-in, and exists)
  • inactive and definition (= and exists)

Also, you can declare a CodeSystem filter with the same name as a property, and the server will evaluate those as well. The set of filter operators that will be accepted is dependent on the type of the property (e.g. is-a or generalizes are only available for code- or coding-typed properties)

Implicit Value Sets

Ontoserver supports three kinds of implicit value sets: implicit value sets for FHIR Code Systems, implicit value sets for the SNOMED CT Code System, and implicit value sets for the LOINC Code System.

Code System implicit value sets

Each explicit Code System resource may have a corresponding implicit value set, which includes all concepts in the code system.

The url for the Code System's implicit Value Set is defined in the Code System's valueSet property, if it is provided. If the valueSet property has no value, then no implicit Value Set is defined for that Code System.

SNOMED CT Implicit Value Sets

When populated with Systematized Nomenclature of Medicine - Clinical Terms (SNOMED CT) terminology, Ontoserver exposes a number of implicit value sets according to the FHIR specification. These include implicit value sets for reference sets, by subsumption, and using ECL.

A SNOMED CT value set is technically identified by a URL. This URL has two parts: a base part that identifies the SNOMED CT edition and version, and a query part that specifies the scope of the value set's content.

Base Part

The base part of the URL has 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.

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

If an edition is specified with no version, then the server will look for the latest version of the edition that is available. If no edition or version are specified then the server will look for the latest version of a preconfigured edition, which is specific to each FHIR server. The default edition in the National Terminology Server (NTS) is SNOMED CT-AU.

Query Part

The query part of the URL determines the type of value set.

The fixed URL for the implicit ValueSet of all SNOMED concepts is http://snomed.info/sct/fhir_vs. This may optionally include the edition and version (http://snomed.info/sct[/edition[/version]]?fhir_vs).

Ontoserver also supports implicit ValueSets based on reference sets, and based on subsumption.

Based on Reference Sets

The query part of the URL for value sets based on reference sets has the format,

?fhir_vs=refset/[sctid]

where sctId is the concept id of a reference set.

The list of reference sets available for an edition is also available as an implicit value set with URL,

http://snomed.info/sct[/edition[/version]]?fhir_vs=refset

Based on Subsumption

The query part of the URL for value sets based on subsumption has the format,

?fhir_vs=isa/[sctid]

where sctId is the concept id of any SNOMED CT concept in the specified edition.

LOINC Implicit Value Sets

When populated with LOINC terminology, Ontoserver exposes a number of implicit value sets according to the FHIR specification. These include implicit value sets for answer lists and multi-axial hierarchy entries.

The code system URL for LOINC is http://loinc.org.

The implicit ValueSet URL for all LOINC terms is http://loinc.org[/version/]?/vs where the optional version is a LOINC version. For example, http://loinc.org/vs or http://loinc.org/2.66/vs

The implicit ValueSet URL for a LOINC answer list is http://loinc.org[/version/]?/vs/[answer-list-code].

The implicit ValueSet URL for the LOINC multi-axial hierarchy given by a LOINC part code is http://loinc.org[/version/]?/vs/[part-code].