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.

The services required to identify the members of a reference set are described in Section 4.6 Get and Test Reference Set Membership. This section describes general requirements for services that are able to access additional data stored in reference sets.

The following services, described in earlier sections, require access to a single data value from each reference set row:

The following services described in the next few sections, require access to one or more data values from each reference set row:

Other reference set types that are not specifically documented in this section of the guide also contain additional data to which a client application may require access. Furthermore when new reference sets are introduced, there will be requirements to access additional data items in those reference sets. The service described in this section provides a general solution by providing access to all additional data associated with a reference set member in any type of reference set.

Requirements and Options

The required services are listed in  Table 4.10-1.

Table 4.10-1: Services Required

Service Name and StatusInputOutput

Get data from a reference set for a specific referenced component

REQUIRED

  • Edition and version

  • refsetId for the reference set from which data is to be extracted.

    • Optional alternatives: a set of refsetIds or an expression constraint for a group of related reference sets.
  • Optional: referencedComponentId

  • Optional parameters to select items within a particular type of reference set for example:

    • mapTarget (in a mapping reference set)
    • targetComponentId (in an association or ordered association reference set)

Data from specified rows in the identified reference set(s).

  • Note that the available data depends on the reference set type

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

Service Name

API Call2

Result

Get data from a reference set for a specific referenced component 

GET [snowstorm]/[branchPath]/members?active=true&referenceSet=[refsetId-or-ecl][&refsetComponentId=[componentId][&other-refsetType-specific-parameters]

Example 1 

GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=900000000000523009|POSSIBLY EQUIVALENT TO association reference set|&referencedComponentId=203004

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=900000000000523009%7CPOSSIBLY+EQUIVALENT+TO+association+reference+set%7C&referencedComponentId=203004


Example 2

GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=<900000000000522004|Historical association reference set|

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C
Example 3

GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=<900000000000522004|Historical association reference set|&targetComponent=140004

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;amp;referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C&amp;targetComponent=140004

Returns a JSON representation of data from members of the specified reference set that match the specified criteria.

The data returned for each matching reference set row includes:

  • Data from the common columns present in all reference sets.
  • The referencedComponentId
    • If the referencedComponentId refers to a concept, details of the concept including its fully specified name and preferred term are also included.
  • An additionalFields object containing specific data fields associated with the particular reference set type.

Also returns the total number of reference set row that match the constraint.

As some requests for reference set members return a large numbers of row, 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).

Example 1 shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.

Example 2 provides an example in which rows from all the historical association reference sets are returned.

Example 3 demonstrates that it is also possible to specify a targetComponentId value when searching for members of reference sets that contains this data item. Similar options are also supported for searches using some other data items specific to certain types of reference set (e.g. mapTarget, owlExpression.conceptId).


Table 4.10-3: FHIR API

Service Name

API Call3

Result
Get data from a reference set for a specific referenced component

The FHIR TS API supports the retrieval of targets for specific SNOMED CT reference sets. Please refer to this document for detailed guidance: https://www.hl7.org/fhir/snomedct.html. Thus, the ConceptMap/$translate operation enables the retrieval of targets for a specific referenced component. 

GET [fhir]/ConceptMap/$translate?code=[componentId]
&system=http://snomed.info/sct
&source=http://snomed.info/sct?fhir_vs
&target=http://snomed.info/sct?fhir_vs
&url=[version]?fhir_cm=[refesetId]

for example

GET [fhir]/ConceptMap/$translate?code=203004
&system=http://snomed.info/sct
&source=http://snomed.info/sct?fhir_vs
&target=http://snomed.info/sct?fhir_vs
&url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_cm=900000000000523009

Returns a JSON representation of data about each of the target components.

The data returned for each concept includes:

  • boolean: True if the concept could be translated successfully. The value can only be true if at least one returned match
  • match: Each match represents data for the map or associated target. Note that there may be multiple matches, where each element represents a mapTarget. For each mapTarget, following data is provided
  • system: the codesystem of the mapTarget
  • code: The identifier of the mapTarget

Example 1 shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.

Table 4.10-4: MySQL Example Database

Service Name

SQL Query 4

Result

Get data from a reference set for a specific referenced component 

SELECT * FROM snap_refset_[refsetType] WHERE refsetId=[refsetId]
	[AND other-refset-type-specific-criteria];

Example 1

SELECT * FROM snap_refset_association 
	WHERE refsetId=900000000000523009
	AND active=1 AND referencedComponentId=203004;

Example 2
SELECT * FROM snap_refset_association 
	WHERE refsetId IN (900000000000523009)
	AND active=1 AND referencedComponentId=203004
UNION
SELECT * FROM snap_refset_attributevalue 
	WHERE refsetId IN (900000000000489007)
	AND active=1 AND referencedComponentId=203004;

Example 3

SELECT * FROM snap_refset_association 
WHERE refsetId IN (900000000000523009,900000000000489007)
	AND active=1 AND targetComponentId=140004;
SELECT * FROM snap_refset_association WHERE refsetId IN (900000000000523009, 900000000000524003, 900000000000525002, 900000000000526001, 900000000000527005, 900000000000528000, 900000000000529008, 900000000000530003, 900000000000531004)
	AND active=1 AND targetComponentId=140004;

Returns a rows of data from the relevant reference set determined by the specified criteria.

The data returned for each matching reference set row includes:

  • Data in the common columns present in all reference sets.
  • Additional data columns associated with the particular reference set type.

Also returns the total number of reference set row that match the constraint.

Example 1 shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.

Example 2 provides an example in which rows from two an historical association reference sets and the concept inactivation attribute value reference set are returned for a specified referencedComponentId 5

Example 3 demonstrates that it is also possible to specify a targetComponentId value when searching for members of reference sets that contains this data item. Similar options are also supported for searches using some other data items specific to certain types of reference set (e.g. mapTarget).

Footnotes
Language and/or dialect should be specified if the service returns terms associated with referenced concepts.
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.
To keep the union query in SQL Example 2, as simple as possible, the column names have not been specified for the attribute value part of the query. As a result the valueId from that row is in the column labelled targetComponentId.


Feedback
  • No labels