Terminology Services Guide

Search

SNOMED CT Document Library

    Loading...
  

Overview

An expression constraint is A computable rule that is used to define a set of clinical meanings.

Notes

The Expression Constraint Language - Specification and Guide defines the syntax used to represent expression constraints. It also defines the rules for applying constraints specified using expression constraint language (ECL) to SNOMED CT concepts and expressions. 

Requirements and Options

Effective use of SNOMED CT requires the ability to constrain searches for concepts in a variety of ways. Subtype constraints and reference set membership constraints are identified as specific service requirements in sections 4.5 Get and Test Concept Subtypes and Supertypes and 4.6 Get and Test Reference Set Membership. Expression constraints can represent combinations of those constraints. They can also include rules that apply to specific aspects of the definition of a concept. For example, limiting concepts to those that are associated with particular body structures.

Expression constraints can be applied for a range of different purposes. In some cases, these may require enumeration of the set of all the concepts that conform to the constraint, while in other cases it may be more appropriate to apply a specific test to an individual concept. The required services are listed in  Table 4.7-1.

Table 4.7-1: Services Required

Service Name and StatusInputOutput

Validate an expression constraint

RECOMMENDED1

  • Edition and version
  • Expression constraint
  • Error message if expression constraint contains syntax errors
  • Error message if any concept identifiers in the expression constraint are not present in the specified edition

Get all concepts that conform to an expression constraint

REQUIRED

  • Edition and version

  • Expression constraint

  • Optional: Language/dialect2

  • Set of conceptIds of all concepts that conform to the expression constraint
  • Optionally additional information such as the fully specified name or preferred term of each concept in the set.
    Error message if expression constraint contains syntax errors

Test if a specific concept conforms to an expression constraint

RECOMMENDED3

  • Edition and version
  • Expression constraint
  • Candidate concept identifier
  • A true or false result depending on whether the candidate concept conforms to the constraint

Interdependencies

Required By

Depends On

Service Examples

The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see IETF RFC1738).

Table 4.7-2: Snowstorm API

Service Name

API Call4

Result
Validate an expression constraint

Not supported as individual service. Limited validation is possible by applying an expression constraint (as shown in next row).

An error message is returned if the expression constraint contains a syntax error. The error message does not indicate the specific cause of the validation error.

No error message is shown if a concept identified in the expression constraint is not present in the selective edition or version 7.

Get all concepts that conform to an expression constraint

GET [snowstorm]/snomed-ct/[branchPath]/concepts?activeFilter=true&ecl=[expressionConstraint]

The two examples are shown first as the expression constraint complete with the terms for each of the concepts. This is followed by the API service calls in which the terms have been removed (as an optional simplification). The constraint has been URL encoded as required for the REST API.

Bone fractures with sites that are members of the lateralizable body structure reference set

GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&ecl=<125605004:363698007=^723264001

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&amp;ecl=%3C125605004%3A363698007%3D%5E723264001

Bone fractures with sites that are NOT members of the lateralizable body structure reference set

GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&ecl=<125605004:363698007!=^723264001

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/concepts?activeFilter=true&amp;ecl=%3C125605004%3A363698007%21%3D%5E723264001

Note that the ECL memberOf function needs to be url encoded. The URL encoding for ^ is %5E

Returns a JSON representation of data related to the concepts that conform to the expression constraint.

The data returned for each concept includes:

  • All concept release file data5
  • The preferred term and fully specified name.

Also returns the total number of concepts that match the constraint.

As some expression constraints are matched by large numbers of concept, this service is paged. Requests parameters include:

  • limit to restrict the number of concepts returned (default 50).
  • offset to specify the start in the results (in multiples of the limit).

With the data from the 2020-01-31 International release

  • The first example returns 1442 concepts.
  • The second example returns 737 concepts.

If the expression constraint contains a syntax error, the returned data is an error message.

Test if a specific concept conforms to an expression constraint

The service used for getting concepts that conform to an expression constraint can be adapted to test whether one or more specific concepts conform to the constraint by simply extending the constraint so it also constrains the results to only include the specified concept(s).

Test if fracture of mandible (jaw bone) is a bone fracture with a site that is a member of the lateralizable body structure reference set

GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=(<125605004: 363698007=^723264001) and (263172003)

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%28%3C125605004%3A+363698007%3D%5E723264001%29+and+%28263172003%29

Test if fracture of femur (thigh bone) is a bone fracture with a site that is a member of the lateralizable body structure reference set

GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=(<125605004: 363698007=^723264001) and (71620000)

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%28%3C125605004%3A+363698007%3D%5E723264001%29+and+%2871620000%29

Test if osteomyelitis of femur is a bone fracture with a site that is a member of the lateralizable body structure reference set

GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=(<125605004: 363698007=^723264001) and (1551001)

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%28%3C125605004%3A+363698007%3D%5E723264001%29+and+%281551001%29

Returns a JSON representation of data related to the concept if it conforms to the expression constraint as described above.

When testing a single candidate concept the value of the property total is sufficient to tell whether the candidate concept conforms to the constraint:

  1. Fracture of mandible total: 0

    • It is a subtype fracture of bone but the mandible is not lateralizable
  2. Fracture of femur total: 1
    • It is a subtype fracture of bone and the femur is lateralizable (there a left femur and a right femur)
  3. Osteomyelitis of femur total : 0
    • Femur is lateralizable and is the finding site but the osteomyelitis is not a subtype of fracture.
Test which of a specific set of concepts conform to an expression constraint

The technique used for testing whether a single concept conforms to an expression constraint can also be used to determine which members of a specified set of concepts conform to that constraint. In the case each of the member of the set of candidates is included in the constraint as shown below: 

GET [snowstorm]/MAIN/2020-01-31/concepts?ecl=(<125605004: 363698007=^723264001) and (263172003 or 71620000 or 15510011551001 or 37449000)

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/concepts?ecl=%28%3C125605004%3A+363698007%3D%5E723264001%29+and+%28263172003+or+71620000+or+15510011551001+or+37449000%29

Returns a JSON representation of data related to concepts in the set that conforms to the expression constraint.

The example shown returns an array containing data about the following concepts:


Table 4.7-3: FHIR API

Service Name

API Call5

Result
Validate an expression constraint

N/A

Not supported as individual service. Limited validation is possible by applying an expression constraint (as shown in next row).

Get all concepts that conform to an expression constraint

GET [fhir]/ValueSet/$expand?url=[versionURI]?fhir_vs=ecl/[expressionConstraint]
Example 1

Bone fractures with sites that are members of the lateralizable body structure reference set

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<125605004:
363698007=^723264001

Encoded URL

GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C125605004%3A%0A363698007%3D%5E723264001
Example 2

Bone fractures with sites that are NOT members of the lateralizable body structure reference set

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<125605004:
363698007!=^723264001

Encoded URL

GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C125605004%3A%0A363698007%21%3D%5E723264001

Returns a JSON representation of data about each of the concepts in the specified version that conform to the expression constraint.

The data returned for each concept includes:

  • code: the conceptId of the reference set member
  • display: the preferred term for the reference set member

Also returns the total number of reference set members

As some expression constraints are satisfied by many concepts, this service is paged. Requests parameters include:

  • count to restrict the number of members returned.
  • offset to specify the start in the results (in multiples of the limit).
  • Example 1 returns 1442 concepts.
  • Example 2 returns 737 concepts.


The /ValueSet/$validate-code operation can be used to test whether a concept is included in a specific value set, where the value set is identified as an implicit value set. 

GET [fhir]/ValueSet/$validate-code?system=http://snomed.info/sct&code=[conceptId]&url=[versionURI]?fhir_vs=ecl/[expressionConstraint]
Example 3

Test if fracture of mandible (jaw bone), 263172003|Fracture of mandible|, is a bone fracture with a site that is a member of the lateralizable body structure reference set.

The subset of concepts that are bone fractures with a site that is a member of the lateralizable body structure reference set can be determined by the following expression constraint:

The resulting FHIR request:

GET [fhir]/ValueSet/$validate-code?system=http://snomed.info/sct&code=1551001&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<125605004:
363698007=^723264001

Encoded URL

GET [fhir]/ValueSet/$validate-code?system=http%3A%2F%2Fsnomed.info%2Fsct&amp;amp;code=1551001&amp;url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C125605004%3A%0A363698007%3D%5E723264001
Example 4

Test if fracture of femur (thigh bone), 71620000 |Fracture of femur|, is a bone fracture with a site that is a member of the lateralizable body structure reference set

GET [fhir]/ValueSet/$validate-code?system=http://snomed.info/sct&code=71620000&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<125605004:
363698007=^723264001

Encoded URL

GET [fhir]/ValueSet/$validate-code?system=http%3A%2F%2Fsnomed.info%2Fsct&amp;amp;code=71620000&amp;url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%3C125605004%3A%0A363698007%3D%5E723264001

  • Returns a JSON representation of data about whether the concept is included in the set.
  • result: true, if the concept is included and false if the concept is not included
  • display: the display term for the concept
  • With the data from the 2020-01-31 International release


  • Example 3

    • result: false

  • Example 4
    • result: True
    • display: "Fracture of femur"
Test which of a specific set of concepts conform to an expression constraint

The /ValueSet/$validate-code operation only supports testing whether a single concept conforms to an expression constraint. Therefore, to determine which members of a specified set of concepts conform to an expression constraint, a dedication expression constraint needs to be designed to enable this test. In this case, each member of the set of candidates is included in the expression constraint as shown below:

([intensionalDefinition])AND([candidate1] OR [candidate2] OR [candidate3] OR ...[candidateN])

The following general request template will test which of the candidates matches the expression constraint represented in the [intensionalDefinition] 

GET [fhir]/ValueSet/$expand?system=http://snomed.info/sct&code=[conceptId]&url=[versionURI]?fhir_vs=ecl/[expressionConstraint]

Example 5
Test which of the following concepts is a bone fracture with a site that is a member of the lateralizable body structure reference set
  • 263172003 |Fracture of mandible|
  • 71620000 |Fracture of femur|
  • 1551001 |Osteomyelitis of femur|
  • 37449000 |Open fracture of ulna|

The resulting FHIR request:

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/(<125605004:
363698007=^723264001) and (263172003 or 71620000 or 1551001 or 37449000)

Encoded URL

GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%2F900000000000207008%2Fversion%2F20200131%3Ffhir_vs%3Decl%2F%28%3C125605004%3A%0A363698007%3D%5E723264001%29+and+%28263172003+or+71620000+or+1551001+or+37449000%29

Returns a JSON representation of data about each of the candidate concepts that conform to the expression constraint.

The data returned for each concept includes:

  • code: the conceptId of the reference set member
  • display: the preferred term for the reference set member

Also returns the total number of concepts satisfying the expression constraint.

Note: If none of the candidate concepts which are tested for membership are included in the reference set, the service will return 0 results.

The request in Example 5 shows that the following two concepts conform to the expression constraint:

  • 71620000 |Fracture of femur|
  • 37449000 |Open fracture of ulna|

Table 4.7-4: MySQL Example Database

Service Name

SQL Query6

Result
Validate an expression constraint

Not supported.


Get all concepts that conform to an expression constraint

call eclQuery([expressionConstraint])

Examples

Bone fractures with sites that are members of the lateralizable body structure reference set

call eclQuery("<125605004|Fracture of bone|:
363698007|Finding site| = ^723264001|Lateralizable body structure reference set|")
Bone fractures with sites that are members of the lateralizable body structure reference set
call eclQuery("<125605004|Fracture of bone|:
363698007|Finding site| = ^723264001|Lateralizable body structure reference set|")

Returns a row of data containing the conceptId and term for each concept that conforms to the constraint.

If the expression constraint is invalid, no rows are returned.


This and the following service examples can also use the following alternative procedure calls:

The procedure eclQueryCount() sets a count output parameter with the number of concepts that match the constraint.

call eclQueryCount([expressionConstraint],@count)

The procedure eclSelect() returns the concepts that match the constraint in a specified style. Styles include: exp (expression with preferred term), expfsn (expression with FSN), pref (id, preferred term), fsn (id,FSN), allsyn (id,synonym - one row per synonym).

call eclSelect([expressionConstraint],[style])

The procedure eclGetIds() outputs the concept identifiers to rows in the table config_resultsets with keyed by by a specified setId. This allows other queries or procedures to access the results.

call eclQueryGetIds([expressionConstraint],[setId])
Test if a specific concept conforms to an expression constraint
call eclQuery(([expressionConstraint]) and ([conceptId]))

for example

call eclQuery("(<125605004=^723264001) AND (71620000)")

If the concept conforms to the constraint, this returns a row of data containing that conceptId and its term. If it does not conform no rows are returned.

Test which of a set of specified concepts conform to an expression constraint
call eclQuery("(<125605004:363698007=^723264001) AND (71620000) or (15510011551001) or (37449000)")
Returns the conceptId and term for concepts in the set that conform to the expression constraint.

Footnotes
The validation service is recommended rather than required as minimal validation can be provided by attempting to apply the expression constraint. However, a validation service that reports specific errors, is required for use cases that involve creating or editing expression constraints (e.g 3.2.2 EHR Data Entry Design).
Language and/or dialect should be specified if the service returns terms associated with referenced concepts.
The test service is recommended rather than required because this can be delivered by the get service simply by adding an additional constraint as shown in the Snowstorm illustration.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of HL7 (www.hl7.org).
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system. It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the SNOMED CT - SQL Practical Guide. For instructions on how to build the example database refer to Appendix A: Building the SNOMED CT Example Database.
Snowstorm expression validation has been raised as an open issue see https://github.com/IHTSDO/snowstorm/issues/145#issue-676721969.

Bone fractures with sites that are NOT members of the lateralizable body structure reference set
Feedback
  • No labels