Terminology Services Guide

Search

SNOMED CT Document Library

    Loading...
  

Overview

Each concept is associated with descriptions. Each description is an association between a human-readable phrase (term) and a particular SNOMED CT concept. 

 There are different types of descriptions and there may be descriptions of each of the following types in several languages:

A synonym is a word or phrase that expresses the meaning of a SNOMED CT concept in a specified language.

 

    • Synonyms are terms that represent the meaning of the concept in a way that is familiar and readily understandable. However, when taken out of context a synonym may not be unambiguous and in some cases the same term may be associated with more than one concept.
    • Each concept has at least one synonym and a concepts may have several synonyms. One of the synonym descriptions in each language is marked as the preferred term for the associated concept and others may be marked as acceptable for use.  The preferred term is the term deemed to be the most clinically appropriate way of expressing a concept in specified language context.

A fully specified name is a description that represents the meaning of a concept in a way that is unambiguous and independent of the context in which it is used.

 

    • Fully specified names are essential for disambiguation of the meaning of a concept. These term used in the fully specified name includes a hierarchy tag that specifies the branch of the SNOMED CT hierarchy the concept is in. The hierarchy tag is enclosed in brackets at the end of the term.
    • There is only one fully specified name in each language. In some languages there may not be a fully specified name, in which case the English fully specified name may be used where necessary for disambiguation.

A textual definition is a narrative text explanation of the meaning of a concept that may exceed the maximum permitted length for a fully specified name.

 

    • Textual definitions are only included for some concepts where longer terms are deemed to be necessary or useful to add clarity to the meaning of the concept.

Requirements and Options

Terminology services must enable access to the term in each active description associated with an identified concept. They should also be able to selectively filter the descriptions for which terms are returned based on the following criteria:

  • Active status (description.active)
    • Inactive descriptions associated with a concept should not be returned unless explicitly requested.
  • Description type (description.typeId)
    • Fully specified name
    • Synonyms (including the preferred term)
    • Textual definitions (and other types where these are used)
  • Acceptability in a specified Language Reference Set
    • Preferred: To access the fully specified name or preferred term
    • Acceptable: To access synonyms

The required services are listed in  Table 4.3-1.

The services described in  4.2 Get a Concept, Description or Relationship require access to data about individual components based on their unique identifiers. Therefore, a service that gets a description is only required to return the data in the identified description. However, some implementations of those services may also meet some of the requirements for getting terms associated with a concept.

  • Services that get concepts may also return some or all of the terms associated with the selected concept.
    • For example, the Snowstorm service that retrieves an identified concept also returns the fully specified name and preferred term for that concept in one language.
    • Similarly, the FHIR service returns a single display term and may optionally also return other associated terms as designations.
  • Services that get relationships may also return terms associated with the concepts identified by those relationships.

Table 4.3-1: Services Required

Service Name and StatusInputOutput

Get fully specified name of a concept

  • Get the fully specified name of a concept in US English (or in a specified language reference set).

REQUIRED

This requirement is identified as a special case as it is a common requirement. However, it can be met indirectly by either:

  • Get concept by identifier if that service returns the fully specified name in addition to data from the concept file.
  • Get filtered terms for a concept with appropriate filter settings.
  • Edition and version
  • Concept identifier
  • Language refset set identifier (optional)
  • Description not found: Return appropriate error message
  • Description found: Return data associated with the description:

Get preferred term of a concept

  • Get the preferred term of a concept in US English (or in a specified language reference set).

REQUIRED

This requirement is identified as a special case as it is a common requirement. However, it can be met indirectly by either:

  • Get concept by identifier if that service returns the preferred term in addition to data from the concept file.
  • Get filtered terms for a concept with appropriate filter settings.
  • Edition and version
  • Concept identifier
  • Language refset set identifier (optional)
  • Description not found: Return appropriate error message
  • Description found: Return data associated with the description:

Get all terms for a concept

  • Get the terms from all descriptions associated with a concept

REQUIRED

  • Edition and version

  • Concept identifier

  • Include inactive descriptions (optional)
  • Descriptions not found: Return appropriate error message
  • Descriptions found: Return data associated with each of the descriptions found
    • This data must include the id, term, active status, description type, language code and case sensitivity
    • It should also include the acceptability of the term in one or more language reference sets

Get filtered terms for a concept

  • Get terms from descriptions associated with a particular concept filtered by one or more of the following
    • Status of the description (active: 1=true, 0=false)
    • Term (term: matching a phrase or pattern)
    • Description type (typeId: fully specified name, synonym, textual definition)
    • Language (languageCode)
    • Acceptability in a specified language reference set (refset.acceptabilityId: preferred, acceptable)

CONDITIONAL

If data necessary to support filtering is provided by "get all descriptions" service, filtering can be done by the client application. In this case, a specific filtered service may not be required.

  • Edition and version

  • Concept identifier

  • Filters
    • Active
    • TypeId
    • Language code
    • Language refset identifier
    • Language refset acceptability
  • Descriptions not found: Return appropriate error message
  • Descriptions found: Return data associated with the descriptions found
    • This data must include the id, term and case sensitivity
    • It must also include the term, active status, description type, language code

Interdependencies

Required By

Depends On

  • This service requires access to description acceptability data in a language reference set. This could be regarded as a dependency on 4.10 Get Data from a Reference Set. However, access to language reference set data is an essential part of the process of displaying appropriate terms for a concept. Therefore access to the language reference set is included as an integral part of this service and is not declared as a distinct dependency.

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

Service Name

API Call1

Result
Get fully specified name of a concept 

GET [snowstorm]/[branchPath]/concepts/[conceptId]

for example 

GET [snowstorm]/MAIN/2020-01-31/concepts/6025007

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/concepts/6025007

Returns a JSON representation of data about the selected concept. This include both the fully specified name and the preferred term.

This is the same Snowstorm API call used in 4.2 Get a Concept, Description or Relationship to get concept by identifier. If the fully specified name and/or preferred term there is no need for a specific service to get these terms.

Get preferred term of a concept

Get all terms for a concept

GET [snowstorm]/[branchPath]/concepts/[conceptId]/descriptions

for example 

GET [snowstorm]/MAIN/2020-01-31/concepts/6025007/descriptions

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/concepts/6025007/descriptions

Returns a JSON representation of data about all descriptions in the selected edition and version that are associated with the concept specified.

The descriptions returned include:

  • Active and inactive descriptions
  • All types of descriptions
  • Descriptions in all languages that are present in the selected edition

The data return for each description includes all data present in the description release file and acceptability data derived from language reference sets. The following items have specific roles in filtering descriptions and presenting the terms they contain:

  • The active value (true or false) can be used to exclude inactive descriptions.
  • The typeId value can be used to filter descriptions of specific types.
    • The additional a text token type provides a human readable representation.
  • The lang value contains the language code and this can be used to filter descriptions.
  • The acceptabilityMap contains text tokens for the acceptability of the description in one or more language reference sets.
  • The caseSignificance value contains a text token indicate whether all or part of a term is case-sensitive. This can be used to enable the case of a term to be adjusted to fit the context of use except in when this would be incorrect or liable to alter the meaning.
Get filtered terms for a conceptUse the API call above to get all terms for a concept and then filter using the returned data.

Snowstorm supports selection of the language(s) in which terms will be returned. This is specified using HTTP request header Accept-Language. The values used with this include the identifiers of the language reference sets to be applied.

For example

{
"Accept": "application/json",
"Accept-Language": "en-X-900000000000509007,en-X-900000000000508004,en"
}


Table 4.3-3: FHIR API

Service Name

API Call2

Result

Get all descriptions for a concept

GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct&code=[conceptId]

for example 

GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct&code=6025007

Returns a JSON representation of data about the selected concept. This include both the fully specified name and all synonyms of the concept3.

This is the same FHIR API call used in 4.2 Get a Concept, Description or Relationship to get concept by identifier. If the fully specified name and/or preferred term there is no need for a specific service to get these terms.


Table 4.3-4: MySQL Example Database

Service Name

SQL Query 4

Result

Get fully specified name of a concept

SELECT term,caseSignificanceId FROM snap_fsn WHERE conceptId=[conceptId]

for example

SELECT term,caseSignificanceId FROM snap_fsn WHERE conceptId=6025007

Returns the fully specified name of a specified concept and its caseSignificanceId.

Get preferred term of a concept
SELECT term,caseSignificanceId FROM snap_pref WHERE conceptId=[conceptId]

for example

SELECT term,caseSignificanceId FROM snap_pref WHERE conceptId=6025007
Returns the preferred term of a specified concept and its caseSignificanceId.
Get all synonyms of a concept
SELECT term,caseSignificanceId FROM snap_synall WHERE conceptId=[conceptId]

for example

SELECT term,caseSignificanceId FROM snap_synall WHERE conceptId=6025007

Returns all the preferred term of a specified concept and with their caseSignificanceId values.

The view snap_synall includes both preferred and acceptable synonyms. So it includes the the preferred term. The view snap_syn can be used in the same way and this excludes the preferred term.

Get all terms for a concept
SELECT * FROM snap_description WHERE conceptId=[conceptId]

for example

SELECT * FROM snap_description WHERE conceptId=6025007
Returns all descriptions of all concepts together with all the data for each of those descriptions in the concept file.

Set language configuration

The queries above for fully specified name, preferred terms and synonyms rely on a language configuration to determine which descriptions are used. By default the US English the setting is applied. However, this can be changed using the setLanguage procedure call shown here. 

CALL setLanguage([configId],[languageCode]);

for example

CALL setLanguage(0,'en-GB');

After this setting is made all references to views including the prefix snap_ and the suffixes _fsn, _pref, _syn, _synall will use the language reference set for GB English (rather than the default language US English).

Other languages supported by the the installed Edition can also be specified in a similar way.

Footnotes
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).
Currently the Snowstorm implementation of the FHIR API lookup for a concept does not return language reference set data on the acceptability of different descriptions.
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