CTS2/doc/FAQ

How do I communicate the desired language to a CTS2 service?

The CTS2 1.0 specification states that the referencelanguage parameter carries the desired language. As an example, "http://{service}/entity/sctid:74400008?referencelanguage=es" would request the Spanish rendering of SNOMED CT Appendicitis. The spec states that it is up to the server to determine the language if referencelanguage is not specified. One obvious mechanism would be to use the Accept-Language section of the http header.

An issue has been submitted to the CTS2 Revision Task force that:

1. Asks that the specification clarify how referencelanguage and Accept-Language should be processed
2. Suggests a shortened parameter - lang as an alternative in the URI

As an example, the following URI:

http://informatics.mayo.edu/cts2/services/py4cts2/cts2/resolvedvalueset/sctid:447565001?maxToReturn=50&referencelanguage=es

should(but currently doesn't) return the value set resolution with the entry designations and other identifiers in Spanish. Similarily

http://informatics.mayo.edu/cts2/services/py4cts2/cts2/resolvedvalueset/sctid:447565001?maxToReturn=50

would return the same thing if:

Accept-Language: es

were included the HTTP header. If no language is specified, it is entirely up to the server which language(s) are returned, and it may use any sort of hints, preferences, etc. it so chooses.

What is the message header for?

The REST response header (RESTResource in http://www.omg.org/spec/CTS2/20120601/core/Core.xsd) is designed to provide a reproducible link to a Read or Query operation:

• resourceRoot - the relative path within the CTS2 service. This attributed identifies the specific resource and, if compliant with the CTS2 WADL will allow another service (REST, SOAP or other binding) to identify the appropriate service call.
• resourceURI - the complete URI that was invoked to retrieve the resource. This includes both the resourceRoot and the parameters. This should NOT include security related attributes such as user identifiers, bypass codes, etc.
• parameter - the arguments to the function, excluding the security codes. parameter should include both CTS2 parameters and service specific parameters.

As an example, the following URI:

http://informatics.mayo.edu/cts2/services/py4cts2/cts2/codesystem/SNOMED_CT_core/version/20120731/entity/74400008/subjectof?use=sctfsn&maxtoreturn=10&user=jim

would return:

<AssociationDirectory numEntries="2" complete="COMPLETE">
   <core:heading>
      <core:resourceRoot>codesystem/SNOMED_CT_core/version/20120731/entity/74400008/subjectof</core:resourceRoot>
      <core:resourceURI>http://informatics.mayo.edu/cts2/services/py4cts2/cts2/codesystem/SNOMED_CT_core/version/20120731/entity/74400008/subjectof?maxtoreturn=10&use=sctfsn</core:resourceURI>
      <core:parameter arg="maxtoreturn">
         <core:val>10</core:val>
      </core:parameter>
      <core:parameter arg="use">
        <core:val>sctfsn</core:val>
      </core:parameter>
      <core:accessDate>2013-01-24T17:40:30Z</core:accessDate>
   </core:heading>
     ...

What is the purpose of the about, documentURI, versionName and href fields

about

about is a URI that references the class, entity, individual, document, etc. that is being described. It not the URI of the CTS2 description itself. As an example, when a CTS2 entity describes "appendicitis", the about URI is http://snomed.info/id/74400008. Similarly, when a CTS2 CodeSystemCatalogEntry desscribes the LOINC coding system, the about URI is http://umls.nlm.nih.gov/SAB/LNC and the about uri of version 238 of LOINC is http://umls.nlm.nih.gov/SAB/LNC/version/LNC238 (note: These entries need to be verified)

Where do I put the change date for a specific version in a map version directory?

A map version can be associated with the following dates:

• officalReleaseDate - (optional) the date/time that the version of the map was released to the public
• officialEffectiveDate - (optional) the date/time that the version of the map becomes "active"
• containingChangeSet.closeDate - (optional) the date/time that the last change to the map version was committed

officialReleaseDate is the only one of these attributes that is available in a version directory itself.

It should be noted, however, that it is not necessary to create a new version of a map for every edit or edit session. The status of a map version can be set to "OPEN", meaning that it is still undergoing edits and that a service cannot count on its changes being stable. Once a set of changes is finalized, the particular version can be set to "FINAL" and the official date set.

How do I reflect the workflow status of a specific version in a directory?

There are two CTS2 attributes that represent the state of an artifact in the workflow:

status property - this attribute is used to record the status of an artifact in the development workflow. In XML, its structure is:

<core:status uri="{status concept uri}" href="{status definition reference}">{status text}</core:status>

1. • {status concept uri} - the official URI of the status, if known (contrived example: http://workflow.com/PENDING)
   • {status definition reference} - a link to a CTS2 definition of the status if known
   • {status text} - the actual text of the status.

As an example, one might post a status of :

<core:status uri="http://id.workflow.com/12345" href="http://service/cts2/entity/workflow:12345">PENDING<core:status>

Where the URI names the workflow status, the href defines it and "PENDING" presents an English representation of its intent. "PENDING" could be rendered in different languages depending on the server context.

versionTag property - this attribute is used to record the status of an artifact within the service environment. Its purpose is to assign tags to particular versions that allow them to be selected without the client software having to keep track of specific version URI's. A typical set of version tags might include "PRODUCTION", "DEVELOPMENT", "TEST", etc. The only pre-defined tag in the CTS2 spec is CURRENT (http://cts2.omg.org/spec/versiontag/CURRENT) - the default tag when no version tag is supplied. Examples:

<versionTag uri="http://cts2.omg.org/spec/versiontag/CURRENT">CURRENT</versionTag>

<versionTag uri="http://some.workflow.ontology/status#in_progress">IN PROGRESS</versionTag>

Where do I find the "official" URI for a given resource?

General information about URI's can be found here. Mayo Clinic is in the process of developing a identifier-to-URI mapping resource, as well as considering the possibility of a CTS2-based directory service where resources could be registered.

Why are there three different ways to read a code system entity?

What is the difference between entity/{entity id}, codesystem/{cs}/entity/{entity id}? and codesystem/{cs}/version/{v}/entity/{entity id}?

entity/{entity id}[?tag={tag}]

The REST signature, entity/{entity id} reflects the availableDescriptions method in the Entity Description Read Service. {entity id} can take the following forms:

• entity/{namespace}:{identifier} - where {namespace} is a namespace known to the service and {identifier} references a resource in the namespace. Examples could be "sctid:74400008", "icd9cm:A00.9", etc.
• entity/{identifier} - where the service serves a single namespace or is able to differentiate namespaces on its own
• entitybyuri?uri={uri} - where the full URI of the entity is supplied. Example: entitybyuri?uri=http://snomed.info/id/74400008, which retrieves information about SNOMED CT concept 74400008

availableDescriptions returns NamedEntityReference, which provides the following information:

• about - the entity URI
• name - a corresponding namespace and name for the entity, if known
• knownEntityDescription - a list of code systems known to the service that make assertions about this entity. Each knownEntityDescription entry contains a reference to the code system, a reference to a particular code system version (if known), the (or a) preferred designation for the entity within the code system and a href to the full description of the entity within the code system version. The service should return the CURRENT version of the code system unless another version tag is requested in the request header.

The current CTS2 specification doesn't provide any mechanism for software to determine which of the availableDescriptions is most desirable. An Issue has been filed with the CTS2 RTF requesting that there be a way to automatically redirect to a preferred description if so desired.

codesystem/{cs}/entity/{entity id}?tag={tag}

The second signature requests the description of the supplied entity according to the CURRENT version of the code if {tag} isn't supplied or the tagged version if it is. Although not 100% clear in the CTS2 specification, the intent of this form that the service will issue a temporary (307) status code and redirect to the third form listed below. This signature can take the forms:

• codesystem/{cs}/entity/{namespace}:{identifier} - where {namespace} is a namespace known to the service and {identifier} references a resource in the namespace. Examples could be "sctid:74400008", "icd9cm:A00.9", etc.
• entity/{identifier} - where the namespace isn't needed to differentiate the concept name within the context of the code system.
• entitybyuri?uri={uri} - where the full URI of the entity is supplied. Example: entitybyuri?uri=http://snomed.info/id/74400008, which retrieves information about SNOMED CT concept 74400008

codesystem/{cs}/version/{v}/entity/{entity id}

This signature takes the same forms as above and asks for everything that version {v} of codesystem {cs} says about the supplied entity.

How do I create out a ResolvedValueSet for exchange or uploading?

The sample ResolvedValueSet entry below shows the basic content:

<?xml version="1.0" encoding="UTF-8"?>
<ResolvedValueSet xmlns="http://schema.omg.org/spec/CTS2/1.0/ValueSetDefinition" 
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                  xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core"
                  xsi:schemaLocation="http://schema.omg.org/spec/CTS2/1.0/ValueSetDefinition 
                  http://www.omg.org/spec/cts2/201206/valuesetdefinition/ValueSetDefinitionServices.xsd">
    <!-- The resolutionInfo section provides:
        1) The URI and name of the value set and value set definition that was used. URI's can take the form:
            a) http://{dns base}/{path}/...   - whatever URI has been assigned by the organization to the URI. 
               this is the preferred form, and, ideally, he owner of {dns base} is equipped to respond to the
               URI saying, at the absolute minimum, "Yes, this resource belongs to us and it is valid"
            b) urn:oid:2.16.840. ...          - the value set OID.  Note that OID's are not usually assigned 
              to definitions - just the value sets themselves.  You *can*, however, assign the same OID to 
              both the value set and the definition in systems that do not deal with versions other than 
              "CURRENT"
            c) urn:uuid:BCA7-AAAA-...         - the value set UUID.  Same caveats as (b) above
            
           An appropriate name associated with the value set.  Strictly informative in this context.
           
        2) The URI and name of each code system that was used in the resolution of the value set.  
           Code System / Code System Version URI's and names follow the same rules as (1) above
        
        Note that it is also possible to supply an href on the value set, definition, or any code system or 
        code system version where you know that a service exists that can tell you something about it.  The
        receiving service may choose to ignore this or replace it.
    -->    
    <resolutionInfo>
        <resolutionOf>
            <core:valueSetDefinition uri="http://id.cymantx.org/valueset/usefuldogs/r1.1">Useful Dogs Version 1.1</core:valueSetDefinition>
            <core:valueSet uri="http://id.cymantx.org/valueset/usefuldogs">Useful Dogs Value Set</core:valueSet>
        </resolutionOf>
        <resolvedUsingCodeSystem>
            <core:version uri="http://snomed.info/sct/900000000000207008/version/20120731">SNOMED CT International Edition July 2012 Release</core:version>
            <core:codeSystem uri="http://snomed.info/sct/900000000000207008">SNOMED CT International Edition</core:codeSystem>
        </resolvedUsingCodeSystem>
    </resolutionInfo>
    <!-- A member list of the concept in the set.  Each entry provides:
         1) The URI of the concept. This can be a DNS entry or a uuid.  Note that neither OID's nor UUID's 
            support concatenation.
         2) An optional namespace/name tuple that carries a contextual namespace and a local identifier.  The 
            receiving service can choose to ignore this field or not/
         3) An optional designation in an appropriate language.  As with namespace/name it can be ignored by the 
            receiving service
    -->
    <member uri="http://snomed.info/id/41320000">
        <core:namespace>sctid</core:namespace>
        <core:name>41320000</core:name>
        <core:designation>Basset hound (organism)</core:designation>
    </member>
    <member uri="http://snomed.info/id/27444002">
        <core:namespace>sctid</core:namespace>
        <core:name>27444002</core:name>
        <core:designation>Belgian tervuren dog (organism)</core:designation>
    </member>
</ResolvedValueSet>

How do I represent a simple value set definition?

The first example below shows an "extensional" definition - a definition that enumerates the set members explicitly:

The non-boilerplate entries are:

• about - the URI of the definition. See above for detail on what it contains
• resourceSynopsis - a short description of the definition itself - version numbers, state, etc.
• definedValueSet - the URI and name of the set being defined
• entry - in this case, a single entry that is "unioned" into the set that consists of:
  • the uri of the referenced entity
  • an optional namespace and name - typically code system or namespace within code system
  • an optional designation - used to identify the resource

Note: The official OMG Specification currently requires a documentURI and sourceAndNotation as well. These fields have proven to frequently be of little use and will (hopefully) be removed by the June Revision Task Force (RTF). The changed schema location is below. Also note that the official OMG specification does not provide for a designation on the entity description. This oversight is being corrected as well.

<?xml version="1.0" encoding="UTF-8"?>
<ValueSetDefinition xmlns="http://schema.omg.org/spec/CTS2/1.0/ValueSetDefinition"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core"
    xsi:schemaLocation="http://schema.omg.org/spec/CTS2/1.0/ValueSetDefinition 
    http://informatics.mayo.edu/svn/trunk/cts2/spec/submission/OMGServerMap/valuesetdefinition/ValueSetDefinitionServices.xsd" 
    about="http://id.cymantx.org/valueset/usefuldogs/r1.1">
    <core:resourceSynopsis>
        <core:value>Useful Dogs Version 1.1</core:value>
    </core:resourceSynopsis>
    <definedValueSet uri="http://id.cymantx.org/valueset/usefuldogs">Useful Dogs Value Set</definedValueSet>
    <entry operator="UNION" entryOrder="1">
        <entityList>
            <referencedEntity uri="http://snomed.info/id/41320000">
                <core:namespace>sctid</core:namespace>
                <core:name>41320000</core:name>
                <core:designation>Basset hound (organism)</core:designation>
            </referencedEntity>
            <referencedEntity uri="http://snomed.info/id/27444002">
                <core:namespace>sctid</core:namespace>
                <core:name>27444002</core:name>
                <core:designation>Belgian tervuren dog (organism)</core:designation>
            </referencedEntity>
        </entityList>
    </entry>
</ValueSetDefinition>

How do I represent an "intensional" value set definition?

The example below defines a value set that contains all descendants of canis lupus as defined in SNOMED CT International:

<?xml version="1.0" encoding="UTF-8"?>
<ValueSetDefinition xmlns="http://schema.omg.org/spec/CTS2/1.0/ValueSetDefinition"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core"
    xsi:schemaLocation="http://schema.omg.org/spec/CTS2/1.0/ValueSetDefinition 
    http://informatics.mayo.edu/svn/trunk/cts2/spec/submission/OMGServerMap/valuesetdefinition/ValueSetDefinitionServices.xsd" 
    about="http://id.cymantx.org/valueset/snomedDogs/r1.0">
    <core:resourceSynopsis>
        <core:value>Domesticated Dogs in SNOMED r1.0</core:value>
    </core:resourceSynopsis>
    <definedValueSet uri="http://id.cymantx.org/valueset/usefuldogs">A list of all domestic dogs in SNOMED</definedValueSet>
    <entry operator="UNION" entryOrder="1">
       <associatedEntities direction="TARGET_TO_SOURCE" transitivity="TRANSITIVE_CLOSURE">
           <referencedEntity uri="http://snomed.info/id/448771007">
               <core:namespace>sctid</core:namespace>
               <core:name>448771007</core:name>
               <core:designation>Canis lupus familiaris</core:designation>
           </referencedEntity>
           <codeSystem uri="http://snomed.info/sct/900000000000207008">SNOMED CT International Edition</codeSystem>
           <predicate uri="http://snomed.info/id/116680003">
               <core:namespace>sctpn</core:namespace>
               <core:name>Is a (attribute)</core:name>
           </predicate>
       </associatedEntities>
    </entry>
</ValueSetDefinition>

What is the entityType field for in EntityDescriptionBase and how does it relate to Types of Entity Description?

Section 2.1 in the CTS2 Entity Description Services specification describes entityType as:

the set of type(s) which the entityReference is an instance of. Because this is a terminology service,
entityType must include one of owl:Class, owl:Individual, rdf:Property, or skos:Concept, although it  
may carry many other types as well.

(Note that there the excerpt above has two corrections - the first is that "Class", "Individual, "Property" and "Concept" are capitalized and that the second is that the third type should be rdf:Property, not "rdf:predicate")

Why is this field required?

One of the goals of CTS2 is to provide a bridge between "traditional" coding and classification schemes and the RDF and OWL structures used by the Semantic Web community. CTS2 is designed to represent the sorts of resources described as "Concept Schemes" in the SKOS specification and "Ontologies" in OWL 2 - "...formalized vocabularies of terms, often covering a specific domain and shared by a community of users. They specify the definitions of terms by describing their relationships with other terms in the ontology."

There is both a philosophical and a technical reason behind requiring a simple classification the "terms" or "concepts" being defined. The philosophical reason is that CTS2 is about terminological resources - not patient records, bills of sale, shoe store inventories, etc. From past experience we've learned that the relatively generic structure behind something like CTS2 can tempt people to try to put all sorts of information structures into the CTS2 information model - structures that have little or nothing to do with terms and their definitions. By requiring the core element, Entity, to be typed to something terminological, it makes folks stop and think whether they are, in fact, dealing with the definition of a "term" or something that might fit better in a traditional database.

The second reason is technical. CTS2 content needs to be representable in RDF, and part of doing this involves associating the resource with an rdf:Class using the rdf:type predicate. rdf:type is key to understanding the intent of the resource and to differentiating it from other CTS2 and non-CTS2 resources in the repository. To accomplish this, the specification requires at least one of the following:

• owl:Class
• owl:Individual
• rdf:Property
• skos:Concept

Collectively, these four base classes provide sufficient distinction to cover the generic types of terminological "entities" while, at the same time remaining sufficiently broad to not exclude anything that should be in the class.

Which type(s) should I use for a specific content?

The decision on which to use depends on the specificity of the source terminology:

1. Terminologies authored in OWL are easy, as they already have types assigned to the relevant resources. The service may need to infer superclasses for resources of type ObjectProperty, DataProperty or AnnotationProperty as well as NamedIndividual or AnonymousIndividual.
2. Terminologies that support formal transformations to OWL fit the same set of rules above - "terms" or "concepts" that "can be understood as sets of individuals" are represented as owl:Class, as "connecting pairs of individuals", "connecting individuals with literals" as rdf:Property and "representing actual objects in the domain" as owl:Individual
3. In all other situations, the type should include skos:Concept, although other types may be assigned as well. This situation works well, as the SKOS Specification is deliberately underspecified as to whether skos:Concept's are also owl:Classes, etc. Set the The Concept Cass section in the SKOS specification for more detail.

CTS2 OMG Specification

How can a service consumer retrieve only the "assets" (value sets, code systems (version), value sets (version), mappings..) filtered to a specific version and per requesting country?

The original SFM associated a JurisdictionalDomain with a Code System Supplement and a ValueSetContextBinding with a UsageContext. It also defined a containment relationship where every UsageContext belonged to a unique Jurisdictional domain. The OMG specification modeled a CodeSystemSupplement as a CodeSystem / CodeSystemVersion that included (CodeSystem) / imported (CodeSystemVersion) the Supplement's TargetCodeSystemId. According to the SFM, the JurisdictionalDomain "… identifies a country, region, organization or other domain that may define and manage its own code systems or concepts, including localization of a broader code system. " This fit well into the notion of SourceAndRole, where the Source of the importing code system would be a name (and, ideally URI) that identified a country, region or organization and the Role could be one of dc:Creator, dc:Owner, or dc:publisher depending on the role(s) that the jurisdictional domain actually played.

As the sourceAndRole attribute applies to CodeSystem, CodeSystemVersion, ValueSet, ValueSetDefinition, Map, MapVersion, ConceptDomain and ConceptDomainBinding, it should provide a generic mechanism for determining which resources are under the purview of a particular jurisdictional domain. Assuming, say, that the Jurisdictional Domain was The Nevada Regional Medical Center (nvrHl7, OID: 2.16.840.1.113883.4.561 ) this could be recorded in the source and role field as:

       <core:sourceAndRole>
           <core:source uri="urn:oid:2.16.840.1.113883.4.561">Nevada Regional Medical Center</core:source>
           <core:role uri="http://purl.org/dc/terms/1.1/creator">creator</core:role>
       </core:sourceAndRole>
       <core:sourceAndRole>
           <core:source uri="urn:oid:2.16.840.1.113883.4.561">Nevada Regional Medical Center</core:source>
           <core:role uri="http://purl.org/dc/terms/1.1/owner">owner</core:role>
       </core:sourceAndRole>
       <core:sourceAndRole>
           <core:source uri="urn:oid:2.16.840.1.113883.4.561">Nevada Regional Medical Center</core:source>
           <core:role uri="http://purl.org/dc/terms/1.1/publisher">publisher</core:role>
       </core:sourceAndRole>

The Filter part of the specification states that you can create a filter based on a ATTRIBUTE, where the reference target is the "URIAndEntityName" of the resource. Unfortunately, this is a tad underspecified. The intent had been to be able to name the attribute (e.g. sourceAndRole) or a sub-attribute (sourceAndRole.source.uri). We will be correcting this in the RTF report in June and will improve the documentation and correct the data type of the filter element itself.

The intent had been that one would run a query along the lines as "http://<servicebase>/codesystems?matchtarget=sourceAndRole.source&matchvalue=urn:oid:2.16.840.1.113883.4.561" or variants thereof. A similar approach would apply to mappings, etc.

From the UsageContext perspective, there is an applicableContext in the ContextDomainBinding that is intended to serve the same role as UsageContext in the SFM. The OMG specification deliberately did not address the relationship between JurisdictionalDomain (Source) and Context as it was decided that models for organizational relationships were outside of the scope of the core service specification.

Can the restrictToPropertyReference operation in ValueSetCatalogQueryService provide a filter to satisfy the needs described above? If not, what should we use?

The signature you want is "restrict", where filterComponent would contain "sourceAndRole.source"

How can we query only the valuesets for mappings defined by a specific country?

SourceAndRole should work for this as well.

---

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