Get and Test Reference Set Membership
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 Validate and Apply Expression Constraints.
The services listed in the table below 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 (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 Get Data from a Reference Set .
Services Required
Get all members of a specified reference set
A reference set specified by its refsetId
A list of concept or description ids
Option to include additional information about each concept or description
Test if a concept or description is a member of specified reference set
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
Otherwise: FALSE
Interdependencies
Required By
Other Services
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).
Snowstorm API
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=723264001Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=723264001Returns 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 .
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=723264001Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referencedComponentId=53120007&referenceSet=723264001while the next call returns false
GET [snowstorm]/MAIN/2020-01-31/members?active=true&referencedComponentId=80891009&referenceSet=723264001Encoded URL
GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referencedComponentId=80891009&referenceSet=723264001Returns 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.
FHIR API
Get all members of a specified reference set
GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E721144007&count=10GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E%5BrefsetId%5D&count=10An 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%3Drefset%2F721144007&count=10for example
GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=refset/[refsetId]&count=10Returns 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 734009000Encoded 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.
MySQL Example Database
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=723264001Returns the ids of all the concepts or descriptions that are the members of the reference se
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 referencedComponentId FROM snap_refset_simple
WHERE active=1 AND refsetId=723264001Returns:
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.
Notes
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.
Last updated