Scope

This page summarizes the implementation of an Expression Extension using the HL7 FHIR Terminology Services API.

This approach is in the process of being implemented and supported by the Snowstorm FHIR Terminology Services API.

Under development

This section is still under active development, and the API examples will change as reference implementations mature and this is discussed with the community of practice.

Solution Overview

To represent an expression repository using FHIR terminology services, the required solution will depend on what approach is taken to uniquely refer to the expressions:

The expressions themselves may be used as an identifier
- With this approach, a CodeSystem Supplement will be created and function as the expression repository
  - This supplements the applied SNOMED CT CodeSystem
A separate identifier is created for each expression
- With this approach, the following FHIR terminology resources are required
  - a CodeSystem Supplement to function as the expression repository
    - This supplements the applied SNOMED CT CodeSystem
  - a CodeSystem to hold the expression identifiers
  - a ConceptMap to hold the association between the expression identifiers and the expressions

FHIR TS with exprep

Services

With this implementation, the defined operations for CodeSystems and ConceptMaps can be utilized to support the services required for an expression repository. Please refer to the HL7 FHIR documentation for further details:

CodeSystem

ConceptMap
- $translate
- $closure

Create expression repository

Creating an expression repository using a FHIR Terminology Server involves the creation of the following structures:

A CodeSystem supplement (expRep): This functions as the actual expression repository and is used to hold the expressions
A CodeSystem (expId): This code system is used to hold the unique expression identifiers
A ConceptMap: This is used to map between the expressions in the expRep CodeSystem supplement and the expId CodeSystem. The ConceptMap enables the translation of expressions to (and from) shorter codes for systems with restricted code lengths

Click to show/hide overview of the workflow...

The workflow for populating an expression repository using a FHIR Terminology Server is illustrated in

Error rendering macro 'caption-reference'

Error occurred rendering template content

Figure 5.4.2-1: -

Service Description Input

Create Code System Supplement

POST /CodeSystem

Create the CodeSystem supplement.

This operation must specify a version URI that uses the snomed.info xsct URI with a specific module but no version.

This resource must supplement a specific version of a SNOMED CT edition.

The example supplements the International Edition of SNOMED CT (900000000000207008), version Jan 2023 (20230131).

{

    "resourceType": "CodeSystem",
    "url": "http://snomed.info/info",
    "version": "http://snomed.info/xsct/11000003104",
    "content": "supplement",
    "supplements" : "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/20230131"
}

Create SNOMED Exp IDs Code System

POST /CodeSystem

(Only needed if EHR cannot store expressions)

If needed, create a CodeSystem for expression identifiers.

{

    "resourceType": "CodeSystem",
    "url": "http://snomed.info/snomed/exp-id/1000003",
    "status": "active",
    "content": "complete"

}

Create Concept Map for Exp Ids

POST /ConceptMap

(Only needed if EHR cannot store expressions)

Create the ConceptMap to map expressions in the code system supplement to expression identifiers in the Exp. Ids code system. This will be populated manually.

{

    "resourceType": "ConceptMap",
    "url": "http://snomed.info/snomed/exp-id-map",
    "status": "active",
    "source": {
        "sourceUri": "http://snomed.info/xsct/1234007?fhir_vs"},
    "target": {
        "targetUri": "http://snomed.info/snomed/exp-id/1101234?fhir_vs"}

}

Get repository details

Service	Description	Input
GET /CodeSystem/{id}	Get the details of the Code System using the provided ID; it is the same operation for the supplement or the Exp. IDs code system.	Code System ID, provided in the response of the code system creation

Add expression

Service

Description

Input

PATCH /CodeSystem/{id}

Adds an expression in the Code System Supplement using a patch operation.

The display value can be generated from the expression, or the expression itself could be used in this field.

This operation should run validation on the expression being inserted into the supplement.

[
  { 
    "op": "add", 
    "path": "/concept", 
    "value": {
      "code": "359817006 |Closed fracture of hip (disorder)| : 
       272741003 |Laterality (attribute)| = 182353008 |Side (qualifier value)|",
      "display": "Right closed fracture of hip"
    } 
  }
]

(Source: https://fhirblog.com/2019/08/13/updating-a-resource-using-patch/)

Lookup expression

Service Description Input Output

GET /CodeSystem/{supplementId}/$lookup?code={CTU}

GET /CodeSystem//$lookup?system={versionUri}&code={CTU}

Lookup Expression in the supplement

versionUri
CTU: close-to-user expression

GET /ConceptMap/{snomed-exp-id-map}/$translate?system={versionUri}&code={CTU}

Example

GET /ConceptMap/snomed-exp-id-map/$translate?system=http://snomed.info/xsct/1234007 &code=87971000:272741003=7771000

Lookup Expression Identifier from Expression

versionUri
CTU: close-to-user expression

GET /ConceptMap/{snomed-exp-id-map}/$translate? reverse=true&system={versionUri}&code={expId}

Example

GET /ConceptMap/snomed-exp-id-map/$translate? reverse=true&system=http://snomed.info/snomed/exp-id/1101234&code=101101234165

Lookup Expression from Expression Identifier

versionUri
expId: expression identifier as defined pr. implementation

Search for expression

Use an implicit value set with ECL.

Get display term

A display term should be returned in the response of the lookup operation. The display term may be generated in a very simple way by just concatenating.

Create Classifiable Form

This should happen when the expression is inserted into the code system.

Create Necessary Normal Form

This should happen when the expression is inserted into the code system.

Subsumption

Service Description Input

Expression subsumption test

GET /CodeSystem/$subsumes

Test the subsumption between a pair of expressions or an expression and a code.

{

    "resourceType": "CodeSystem",
    "url": "http://snomed.info/snomed/exp-id/1234007",
    "status": "active",
    "content": "supplement",
    "supplements": "http://snomed.info/snomed/exp-id/900000000000207008",
    "valueSet": "http://snomed.info/snomed/exp-id/1234007?fhir_vs"

}

ECL

Service	Input	Output
GET /ValueSet/$expand?url={url}`?fhir_vs=ecl/{ecl}`	url: The URI of the expression repository ecl: A valid expression constraint defining the constraints of the query

Example

A hospital department would like to report on the number of closed reduction procedures performed. All codes representing this type of procedure must be fetched so that they can be matched against the EHR records.

Expand an intentional ValueSet using the expression library (and the Code System it supplements) with ECL "< 86052008 |Closed reduction of fracture (procedure)|"
- GET /ValueSet/$expand?url=http://snomed.info/xsct/1234007?fhir_vs=ecl/<86052008
Expand an intentional ValueSet using the expression library, the Code System it supplements and a derivative (module 98763002)
- GET /ValueSet/$expand?url=http://snomed.info/xsct/1234007;module/98763002?fhir_vs=ecl/<86052008

Search

Page tree

5.4.2 Expression Repository with HL7 FHIR