CTS2/doc/SVS Retrieve Value Set

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

HTTP Binding

SVS Response

Encoding: text/xml