Terminology Server Invocation in AQL (SEC proposal)

Background

The AQL MATCHES statement may perform a request to a terminology server for performing some operation over a value set or code system (here used as a synonym of terminology). Several operations may be possible, being the most common ones: the expansion of a ValueSet (or Reference Set), checking that a concept belongs to a value set or code system, testing if one concept subsumes another one, or the translation of concepts across different terminologies.

After the discussions available in Terminology in AQL , on the SEC meeting held on the March the 26th 2020 it was agreed to draft a specification for the invocation of external terminology servers from AQL statements. A keyword section in AQL was the preferred choice as explained below.

The use of one single URI to specify all the information needed for performing an external terminology server request was also considered. However, this option was finally disregarded for the following reasons. Firstly, it is important to facilitate differentiating a pure terminology concept specified as a URI (e.g. http://snomed.info/id/[concept-id])  from a request to a terminology server for performing certain operation(e.g. https://fhir.loinc.org/ValueSet/$expand?url=http://loinc.org/vs/LL1162-8). Secondly, another reason is that the unique URI approach would force to consider how to fit in the URI structure all the parameters that may be necessary for any terminology server.

A less cumbersome approach has been agreed by using  a keyword (TERMINOLOGY) in the AQL syntax. The TERMINOLOGY keyword indicates that the three sections inside its parenthesis correspond to the operation, the driver or adapter for the external terminology server (e.g. HL7 FHIR TS, Ocean CTS, DTS2), and the driver identifiers. These identifiers should provide the necessary information for invoking external terminology servers to perform an operation. In addition, the AQL TERMINOLOGY statement should also provide the necessary information for allowing the processing system to parse back the response from the terminology server.

The MATCHES syntax should allow to directly use the TERMINOLOGY statement for indicating that the set will be resolved by the internal representation. This is already allowed by some implementers.

In addition, the TERMINOLOGY statement may be embedded between curly braces (“{}”) after the MATCHES section. This allows for merging some explicit codes with the TERMINOLOGY instruction. The AQL interpreter will be responsible to generate a valid list of codes during semantic analysis. An AQL query mixing both terminology server requests and concepts specified as URIs would look like the following example.

In the following, a complete description of the operations in the TERMINOLOGY statement are provided.

Driver section

Provides an identifier of the terminology server Application Programming Interface (API). The driver provides the information to send requests related to the ValueSet and operation parameters to the terminology service. In addition, it allows the system to understand how to parse responses back from the terminology service.

In the table below there is an interim list of drivers proposed in the discussion and the comments from HL7 with the recommendation for a URI to identify a specific FHIR version.

(see comment from Grahame Grieve: http://www.healthintersections.com.au/?p=3029)

Note: the physical address can be configured in the application. The URI value set is not necessarily the server URL.

Parameters URI

In FHIR TS, the params_uri section will be formed by the URI path and query sections in compliance with RFC3986. Most common operations include value set URI identifies the value set on which to perform the operation. A value set may be a full code system such as the full set of codes in SNOMED-CT or LOINC. Valid URIs are those defined by RFC 3986. The value set URI may include the version and edition sections for the value set or code system (Australian, US, etc.). When the release and version identifiers are not provided, it is up to the external terminology server to decide which default version will be used.

Operation section

The operation section specifies the action to perform over the specified value set or code system. It is not restricted to any particular structure provided that different terminology servers may use different ways of specifying the operation and its parameters. Query implementers should be careful so the specified operation can be properly dereferenced by the implementation of the driver:

• Expand a value set: retrieve all the codes contained in a value set as an explicit set.

• Validate a code in a value set: check if a given code belongs to a value set. Recall that the value set may comprise all the codes in a code system (terminology).

• Look-up a code: retrieve all the information concerning one particular code. Examples are retrieving the preferred form to display, synonyms, etc.

• Translate a code: translate (find an equivalent) code from one Value Set to another one based on a predefined mapping available in the external terminology service. Translation precision may not be limited to full equivalence and different kinds of mappings may be possible (wider meaning, equivalent, narrower meaning, etc).

• Subsumption testing: determine if a particular terminology concept is a subtype (is-a) of another one. For example, test in SNOMED-CT if Myasthenia Gravis | 91637004 is a subtype of autoimmune disease | 85828009 (i.e. test if 85828009 subsumes 91637004).

Open Questions

*Should the grammar restrict the ValueSet section to URI or allow any String so OIDs can fit in the ValueSet specification?-> it has been agreed to maintain the specification as open as possible. The ValueSet will be specified in the parameter section. In the AQL grammar it will be free text. However, in most cases (e.g. FHIR) it will need to be provided or preprocessed so it contains valid URI parameters.

*specification of Concept Maps for translations → there are two ways of specifing translations in FHIR: a)[base]/ConceptMap/$translate; and, b) [base]/ConceptMap/[id]/$translate. Option (a) may not be supported, so the proper way to specify ConceptMap translations is to provide the concept map identification as an URL in the parameter section.

Examples

Examples for Validation and Example

Executable FHIR examples for the ontoserver test instance are available at: https://documenter.getpostman.com/view/784165/ontoserver-51-example-fhir-terminology-requests/RW1hhG1S?version=latest

EXAMPLE 1

FHIR:

{{url}}/ValueSet/$validate-code?system=http://loinc.org&code=45276-3&url=http:/loinc.org/vsac/BloodCulture&display=Bacteria identified in Blood by Anaerobe culture 25 degree C incubation

openEHR:

TERMINOLOGY('validate', ‘http://hl7.org/fhir/4.0',’system=http://loinc.org&code=45276-3&url=http:/loinc.org/vsac/BloodCulture&display=Bacteria identified in Blood by Anaerobe culture 25 degree C incubation'):BOOLEAN

EXAMPLE 2

FHIR:

{{url}}/ValueSet/$validate-code?system=http://snomed.info/sct&code=30346009&url=http://vsac.highmed.org/vsac/episodes&display=Evaluation and management of established outpatient in office or other outpatient facility

openEHR: 

TERMINOLOGY( ‘validate', 'http://hl7.org/fhir/4.0', 'system=http://snomed.info/sct&code=30346009&url=http://vsac.highmed.org/vsac/episodes&display=Evaluation'):BOOLEAN

EXAMPLE 3

FHIR:

{{url}}/ValueSet/$validate-code?system=http://snomed.info/sct&code=122298005&url=http://snomed.info/sct?fhir_vs&display=Astrovirus RNA assay

openEHR: 

TERMINOLOGY('validate', ‘http://hl7.org/fhir/4.0', 'system=http://snomed.info/sct&code=122298005&url=http://snomed.info/sct?fhir_vs&display=Astrovirus RNA assay'):BOOLEAN

EXAMPLE 4

FHIR:

{{url}}/ValueSet/$validate-code?system=http://icd10.who.org&url=http://vsac.nlm.nih.gov/malignantneoplasms&code=C15.8&display=foo

openEHR: 

TERMINOLOGY(‘validate', ‘http://hl7.org/fhir/4.0', ‘system=http://icd10.who.org&url=http://vsac.nlm.nih.gov/malignantneoplasms&code=C15.8&display=foo’):BOOLEAN

EXAMPLE 5

FHIR:

{{url}}/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=isa/50697003

openEHR: 

TERMINOLOGY(‘expand', 'http://hl7.org/fhir/4.0', 'url=http://snomed.info/sct?fhir_vs=isa/50697003') : SET<DV_CODED_TEXT>

EXAMPLE 6

FHIR:

{{url}}/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/<<50697003

openEHR: 

TERMINOLOGY('expand', 'http://hl7.org/fhir/4.0', 'url=http://snomed.info/sct?fhir_vs=ecl/<<50697003') : SET<DV_CODED_TEXT>

EXAMPLE 7

FHIR:

{{url}}/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20170731?fhir_vs=refset/142321000036106

 openEHR: 

TERMINOLOGY('expand', 'http://hl7.org/fhir/4.0', 'url=http://snomed.info/sct/900000000000207008/version/20170731?fhir_vs=refset/142321000036106') : SET<DV_CODED_TEXT>

Examples for Look-up

EXAMPLE 8

FHIR:

 {{url}}/CodeSystem/$lookup?system=http://snomed.info/sct&code=263495000&_format=json

openEHR: 

TERMINOLOGY('lookup', 'http://hl7.org/fhir/4.0', 'system=http://snomed.info/sct&code=263495000&_format=json') : DV_CODED_TEXT

EXAMPLE 9 (with property)

FHIR:

{{url}}/CodeSystem/$lookup?system=http://snomed.info/sct&code=45313011000036107&property=inactive&version=http://snomed.info/sct/32506021000036107/version/20160630

openEHR: 

TERMINOLOGY('lookup', 'http://hl7.org/fhir/4.0', 'system=http://snomed.info/sct&code=45313011000036107&property=inactive&version=http://snomed.info/sct/32506021000036107/version/20160630') : DV_CODED_TEXT

EXAMPLE 10

FHIR:

{{url}}/ValueSet/$validate-code?system=http://snomed.info/sct&code=122298005&url=http://snomed.info/sct?fhir_vs&display=foo

openEHR: 

TERMINOLOGY('validate', 'http://hl7.org/fhir/4.0', 'system=http://snomed.info/sct&code=122298005&url=http://snomed.info/sct?fhir_vs&display=foo') : BOOLEAN

EXAMPLE 11 (validate is-in SNOMED refset)

FHIR:

{{url}}/ValueSet/$validate-code?system=http://snomed.info/sct&code=122298005&url=http://snomed.info/sct?fhir_vs=refset/32570361000036108

openEHR:

TERMINOLOGY('validate', 'http://hl7.org/fhir/4.0', 'system=http://snomed.info/sct&code=122298005&url=http://snomed.info/sct?fhir_vs=refset/32570361000036108') : BOOLEAN

Examples for subsumption

EXAMPLE 12

FHIR:

{{url}}/CodeSystem/$subsumes?system=http://snomed.info/sct&codeA=235856003&codeB=3738000

openEHR: 

TERMINOLOGY('subsumes', 'http://hl7.org/fhir/4.0', 'system=http://snomed.info/sct&codeA=235856003&codeB=3738000) : BOOLEAN