Terminology Services Guide

Search

SNOMED CT Document Library

    Loading...
  

Overview

Reference set files provide a standard format for maintaining and distributing a set of references to SNOMED CT components.

Notes

  • A reference set can be used to represent a subset of components (concepts, descriptions or relationships).

  • A reference set may also associate referenced components with additional information such as:
    • Ordered lists of components
    • Sets of associations between components
    • Mapping between SNOMED CT concepts and other systems codes, classifications, or knowledge resources.

Requirements and Options

A concept or description is a member of a reference set if that reference set contains an active row with a referencedComponentId matching the id of that concept or description.

Two services are specified in this section. One of these returns the list of members of a specified reference set. The other tests whether a candidate concept or description is a member of a specified reference set.

The union, intersection or complement of two or more reference sets can be determined using the SNOMED CT Expression Constraint Language (ECL). Terminology service requirements for accessing expression constraints are described in 4.7 Validate and Apply Expression Constraints.

The services listed in  Table 4.6-1 can be used to determine whether a concept or description is a member of any identified reference set. These services are primarily applicable to simple reference sets that represent subsets of concepts or descriptions (5.2.1.1 Simple Reference Set).  Members of other  types of reference set contain additional data and services that provide access to this additional data are described in  4.10 Get Data from a Reference Set . 

Table 4.6-1: Services Required

Service Name and StatusInputOutput

Get all members of a specified reference set

REQUIRED

  • A reference set specified by its refsetId
  • A list of concept or description ids 1
  • Option to include additional information about each concept or description

Test if a concept or description is a member of specified reference set

REQUIRED

  • A reference set specified by its refsetId

  • A candidate concept.id or description.id
  • If the candidate concept or description is a member of the reference set: TRUE 2
  • Otherwise: FALSE

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.6-2: Snowstorm API

Service Name

API Call3

Result
Get all members of a specified reference set

GET [snowstorm]/[branch]/members?active=true&referenceSet=[refsetId]

for example 

GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=723264001

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=723264001

Returns a JSON representation of data about all the active members of the reference set.

It also returns the total number of members in the reference set.

As some reference sets contain a large numbers of members, this service is paged. Requests parameters include:

  • limit to restrict the number of reference set members returned (default 50).
  • offset to specify the starting point in the results (in multiples of the limit).

This example returns all active members of the 723264001 | Lateralizable body structure reference set| . This is large reference set with nearly 20,000 active members so although this call returns the count of members it only returns data on a limited number of members 4 .

Test if a concept or description is a member of specified reference set 

GET [snowstorm]/[branch]/members?active=true&referencedComponentId=[candidateId]&referenceSet=[refsetId]

for example this call returns true 

GET [snowstorm]/MAIN/2020-01-31/members?active=true&referencedComponentId=53120007&referenceSet=723264001

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referencedComponentId=53120007&referenceSet=723264001

while the next call returns false

GET [snowstorm]/MAIN/2020-01-31/members?active=true&referencedComponentId=80891009&referenceSet=723264001

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referencedComponentId=80891009&referenceSet=723264001

Returns a JSON representation of data including a count of matching member rows followed by data from the matching member rows. The result of the test can be determined by checking the total property of the returned object. Non-zero implies the candidate concept or description is a member of the reference set, zero implies it is not.

The two example calls both test membership of the 723264001 | Lateralizable body structure reference set| . The first one returns with a total value of 1 confirming that 53120007 | Upper limb structure| is a member of this reference set. The second example returns with a total value of 0 as 80891009 | Heart structure| is not a member of this reference set.


Table 4.6-3: FHIR API

Service Name

API Call5

Result
Get all members of a specified reference set

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=refset/[refsetId]&count=10

for example 

GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Drefset%2F721144007&count=10
An alternative solution is to use the expression constraint language, as shown here: 
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E%5BrefsetId%5D&count=10
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E721144007&count=10

Returns a JSON representation of data about each of the reference set member.

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 reference sets have very large numbers of children, 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).

Test if a concept is a member of specified reference set

FHIR does not provide a specific operation for this service, but the SNOMED CT Expression Constraint Language supports testing for reference set membership, and can thus be used to enable this service through the ValueSet/$expand operation. 

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/^[refsetId] AND [predicateConceptId]
for example 
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/^721144007 AND 734009000

Encoded URL

GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E721144007+AND+734009000

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

If multiple predicate concepts should be tested in the same requests this can be done using the following expression constraint:

^[refsetId] AND ([predicateConceptId_1] OR [predicateConceptId_2].... OR [predicateConceptId_n])

Returns a JSON representation of data about each of the predicate concepts that are members of the reference set.

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 predicate concepts are which are tested for membership are included in the reference set, the service will return 0 results.

Table 4.6-4: MySQL Example Database

Service Name

SQL Query 6

Result

Get all members of a specified reference set

SELECT referencedComponentId FROM snap_refset_simple
	WHERE active=1 AND refsetId=[refsetId];

for example

SELECT referencedComponentId FROM snap_refset_simple
	WHERE active=1 AND refsetId=723264001;

Returns the ids of all the concepts or descriptions that are the members of the reference set.


Test if a concept or description is a member of specified reference set
SELECT count(referencedComponentId) 
	FROM snap_refset_simple 
	WHERE active=1 AND refsetId=[refsetId] 
	AND referencedComponentId=[candidateComponentId];

for example

SELECT count(referencedComponentId) 
	FROM snap_refset_simple 
	WHERE active=1 AND refsetId=723264001 
	AND referencedComponentId=53120007;

Returns:

  • 0 : if the candidate component is not in the reference set.
  • 1 : If the candidate component is a member of the reference set
    • Some types or reference set can include the same component more than once, so any value greater than zero indicate the component is a member of the references set.

Footnotes
The reference set specification should indicate which component types are permitted to be members. The members of some reference sets are concepts while the members of other reference sets are concepts. It is also possible, for some reference sets to contain both concepts and descriptions as members. Services that only return the referencedComponentId do not need to be aware of the types of component in the reference set. However, if a service returns terms or other additional data, the service must take account of the component type.
The value TRUE may be represented in a variety of ways. For example: as a Boolean value, as a non-zero count of matching members or by a data object representation of the candidate component. Similarly the value FALSE may be represented by a Boolean, by a zero count, or by an empty or null returned object.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
The number of results returned defaults to 50 but can be set using a limit parameter in the call. Additionally the starting offset within a large set of results can be specified by an additional parameter.
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.

Feedback
  • No labels