CTS2/doc/SVS Retrieve Value Set

From HL7Wiki
Jump to navigation Jump to search

Request

Request Elements

The SVS specification identifies the following resources:

  • Value Set Definition
    • Extensional Definition
    • Intensional Definition
  • Expanded Value Set
    • Expanded Value Set itself - no reference to definition that produced it. Carries its own unique OID and Version
    • Reference to Value Set Definition - OID and Version references value set itself.

The CTS2 specification approaches this in a slightly different fashion:

  • Value Set - metadata about the publisher, purpose, etc of the value set.
  • Value Set Definition - the definition of a value set at a given point in time. Equivalent to "version" in the SVS model. Does not differentiate between "intensional" and "extensional" definitions - can carry any combination of lists of values and/or rules for creating values.
  • Resolved Value Set - the result of the application of a specific value set definition to a specific version (or versions) of a code system.

A key difference between the SVS and CTS2 models is that, while both SVS and CTS2 allow Expanded (Resolved) value sets to be referenced independently, CTS2


Element Description Optionality CTS2 Element Notes
id the Value Set OID that identifies the Expanded Value Set within the Repository Mandatory valueSetName The OID serves as the unique name of the value set within the context of the service.
version identifies a specific version of the Expanded Value Set. If no version is specified, the Value Set Consumer is requesting the most recent version of the Value Set Optional (when absent) When absent, CTS2 will return the "current" definition of the Value Set. Note that the label "current" is deliberate, as it may be the case that the "latest" version is still under development or has not yet become active.
valuesetDefinitionId When present, the specific definition is used.
lang Optional the requested language locale for the displayName of the Value Set Concepts. readContext.referenceLanguage
The CTS2 specification doesn't provide a "return all languages" features. If referenceLanguage is not supplied, the CTS2 specification states that the service will determine the most appropriate language based on the environment and context.


When receiving a Retrieve Value Set Request, a Value Set Repository shall generate a Retrieve Value Set Response containing the Expanded Value Set that corresponds to the request parameters, or an error code if the Value Set could not be retrieved. If no version is specified in the Request, then the most recent version shall be returned.

The Value Set Repository shall support both the SOAP and HTTP bindings for this transaction. If the Value Set Consumer sends the request using the SOAP binding, the Value Set Repository shall respond using the SOAP binding. If the Value Set Consumer sends the request using the HTTP binding, the Value Set Repository shall respond using the HTTP binding.

HTTP Signatures

SVS

GET //RetrieveValueSet?id={id}[&version={ver}][&referencelanguage={lang}]

CTS2

Both of the forms below return the IterableResolvedValueSet structure.


The first form below returns the "current" definition of the value set

GET <service base>/valueset/{id}/resolution[?referencelanguage={lang}]


The second form returns the resolution of the supplied version.

GET //valueset/{id}/definition/{version}/resolution[?referencelanguage={lang}]

Notes:

  1. The first URL form above ("resolution" directly againast a value set) is not currently part in the official CTS2 WADL. It has been submitted as an issue to the CTS2 RTF
  2. While the CTS2 PIM defines the function "ResolveAsCompleteSet", there is currently no REST signature that says "I want everything". The best a client can do at the moment is supply a very large number in as the "maxToReturn" parameter. This has been submitted as an issue to the RTF, with the proposed solution being an "iterator=False" parameter which will return the whole thing.

Response

Element Description Optionality CTS2 Element CTS2 Optionality Notes
id the Value Set OID that identifies the Value Set within the Value Set Repository. This OID shall be the same as the Value Set OID in the received Retrieve Value Set Request Message. Mandatory resolutionOf.valueset.uri The URI contains the id in the format "urn:oid:{id}"
displayName "can be used for display purposes" Mandatory resolutionof.valueset.name
version shall be present if the Expanded Value Set has a version, that identifies the specific version of the Value Set returned Optional, but mandatory in the case of Expanded Value Set resolutionof.name resolutionof.uri shall be set to "urn:oid:{id}:{version}" Note that this is not a sanctioned oid (!)
cacheExpirationHint indicating that the Value Set Consumer is not expected to change before this date and time. If the request and the response use the HTTP binding, this information shall be also present in the HTTP Expire header of the response. For details, please see Sec. 14.21 of IETF RFC2616. Optional (none) Caching is outside of the scope of the CTS2 specification. The Cache-Control section of the HTTP header carries multiple parameters for addressing this in a dynamic environment. The CTS2 ValueSetDefinition.officialReleaseDate and ValueSetDefinition.officialActivationDate attributes can be used in a planning environment to determine when local stores and images may need to be reloaded.
ConceptList the Concepts of the Expanded Value Set. If there are multiple translations of the Value Set, each translation is returned as a separate ConceptList, where only the displayName of each Concept, and the language locale represented by xml:lang are different. Mandatory (multiple) IterableResolvedValueSet.member
CTS2 does not have a way to return multiple languages in one query.

ConceptList

Element Description Optionality CTS2 Element CTS2 Optionality Notes
code uniquely identifies a class or concept within the context of a code system Mandatory entry.name
displayName the name of the concept Mandatory entry.designation
codeSystem the terminology the concept comes from Optional entry.namespace entry.namespace is the local name of the code system. The URI can be determined by referencing the resolutionInfo.resolvedUsingCodeSystem[entry.namespace].uri in the message header. The entry with the matching name will have a URI (that can be parsed to acquire the OID).
This MUST be present in the CTS2 model
codeSystemVersion the version of the terminology the concept comes from Optional resolutionInfo.resolvedUsingCodeSystem[entry.namespace].version The CTS2 specification does not allow a single value set resolution to be resolved against more than one code system version -- all codes in the same code system must come from the same version. For this reason, version has been moved to the resolution header.
This attribute MUST be present in the CTS2 model

Behavior

  1. If lang is specified, one list is returned. If not, the repository returns "all known translations" in the form of multiple concept lists.
  2. NAV error code returned if id is unknown
  3. VERUNK error code if version is unknown

Note that the specification prescribes 404 HTTP response codes with specific detail specified for the content

SOAP Binding

HTTP Binding

SVS Request

CTS2 Request

SVS Response

Encoding: text/xml


Navigation – Common Terminology Services (CTS2)

   Home
About CTS2
   Purpose
   CTS2 History
   Business Case
How it works
   Federation
   Functionality
Implementing CTS2
   Architecture
   Development
Resources
   Purpose
   FAQ
   Business Case
   Glossary of Terms
Specification
   REST
   SOAP
   HL7 SFM
Development
   CTS2 Development Framework
   Implementations
  Github Page
Community
   Who is Using CTS2?
   Get Help
   Links