Terminology in CQL

Terminology in CQL

Clinical Quality Language is designed to support a broad range of terminology use cases. In particular, the language defines first class constructs for the definition of code systems, value sets, concepts, and codes. However, CQL does not define the actual contents of these constructs. Instead, each of these constructs provides a mechanism for defining a logical versioned identifier. CQL logic then references terminologies using the locally defined names.

The following guidance is proposed for the use of these terminology constructs in CQL libraries referenced by CQL-Based HQMF measures. In general, the guidance recommends the use of URIs as the representation format for all the logical identifiers (including versions) used for terminology constructs.

Code Systems

When code systems are referenced within CQL, the OID of the code system should be specified using a URN for the code system. For example:

codesystem "SNOMED-CT:March 2016": 'urn:oid:2.16.840.1.113883.6.96' version 'urn:hl7:version:March%202016'    

The local identifier for the codesystem ("SNOMED-CT:March 2016" in this case) should include the friendly name of the code system and an indication of the version, separated with a colon.

The URN for the version part of the identifier uses the namespace version to indicate that this is the logical identifier of a version.

Note the use of URN syntax as defined by RFC 2141 requires that names be escaped (hence the use of %20 rather than a space). In addition, based on RFC 3406 for formal or informal URNs, there is an expectation of uniqueness. The hl7 prefix provides this unique namespace.

Value Sets

When value sets are referenced within CQL, the OID of the value set should be specified as a URN for the value set:

valueset "Face-to-Face Interaction": 'urn:oid:2.16.840.1.113883.3.464.1003.101.12.1048' 

The local identifier for the value set within CQL should be the same as the name of the value set in the Value Set Authority Center (VSAC). However, because the name of the value set is not guaranteed to be unique, it is possible to reference multiple value sets with the same name, but different identifiers. When this happens in a CQL library, the local identifier should be the name of the value set with a qualifying suffix to preserve the value set name as a human-readable artifact, but still allow unique reference within the CQL library.

For example:

valueset "Face-to-Face Interaction (1)": 'urn:oid:2.16.840.1.113883.3.464.1003.101.12.1048.1' 
valueset "Face-to-Face Interaction (2)": 'urn:oid:2.16.840.1.113883.3.464.1003.101.12.1048.2' 

Note that because the VSAC supports different approaches to retrieving the expansion of a valueset through its Sharing Value Sets (SVS) API, there are multiple possible approaches to specifying expansion parameters for a value set. For the purposes of this guidance, two approaches are described: 1) by version, and 2) by profile.

By Version

When retrieving the expansion of a value set by version, the version identifier attribute should be a URN defining the version:

valueset "Face-to-Face Interaction": 'urn:oid:2.16.840.1.113883.3.464.1003.101.12.1048' 
    version 'urn:hl7:version:2016-04-01'

As with code systems, the version namespace is used to indicate that the identifier is a version.

By Profile

When retrieving expansions by profile, the version identifier attribute should be a URN defining the profile:

valueset "Face-to-Face Interaction": 'urn:oid:2.16.840.1.113883.3.464.1003.101.12.1048'
    version 'urn:hl7:profile:MU2%20Update%202016-04-01'

Here, the profile namespace is used to indicate that the identifier is a profile.

Code System Versions

In addition to the version or profile of a value set, CQL supports specifying the intended code system version to be used when performing the expansion of a value set for any code systems referenced in the definition of that value set:

valueset "Face-to-Face Interaction": 'urn:oid:2.16.840.1.113883.3.464.1003.101.12.1048'
    version 'urn:hl7:version:2016-04-01'
    codesystems { "SNOMED-CT:March 2016" }

The code system to be used is referenced within the codesystems clause of the valueset declaration, "SNOMED-CT:March 2016" in this case, a reference to the previously declared code system. If the value set is defined using codes from multiple code systems, additional code system references can be provided in the codesystems clause.

Codes

When single codes are represented within CQL, the logical identifier is not recommended to be a URN. Instead, the logical identifier is the code from the code system:

code "Assessment of breastfeeding": '709261005' from "SNOMED-CT:March 2016" display 'Assessment of breastfeeding'

Note that for single code usage, the local identifier "Assessment of breastfeeding" should be the same as the description of the code within the terminology in order to avoid conflicting with any usage or license agreements with the referenced terminologies, but can be different to allow for potential naming conflicts, as well as simplification of longer names when appropriate.

Comparing Codes

For terminology comparisons, CQL defines both equality (using the = operator) and equivalence (using the ~ operator tilde). For equality comparisons, two codes are only equal if all their components are equal (i.e. the two codes have the same code, code system, code system version, and display values). For equivalence comparisons, two codes are considered equivalent so long as they have the same code and code system values. Version and display are ignored for the purposes of determining equivalence.

For most use cases involving terminology comparisons, equivalence should be used. Note that value set membership testing in CQL is defined based on equivalence, not equality.

Concepts

In addition to codes, CQL supports a concept construct, which is defined as a set of codes that are all semantically equivalent. There is no direct counterpart within HQMF currently, and it is not clear how or when this construct would be used within measure development. As such concepts are not recommended for use and should be avoided in favor of the other terminological constructs.

Representation in HQMF

To support the use of code systems, value sets, and direct-reference codes within CQL-Based HQMF measure documents, we recommend the creation of a new Terminology Section in the CQL-Based HQMF HTML (Human Readable), as well as several extensions to the HQMF schema.

Representation in the HQMF XML

Within the HQMF XML measure document, the definition section allows value sets used by the measure to be declared. The section also supports inline expansion of value sets. However, current QDM-Based HQMF documents do not make use of this section, relying instead on the value set elements of codes specified within the HQMF QDM templates in the data criteria section. We recommend that this section be used in CQL-Based HQMF documents to provide a complete declaration of the terminology used by the measure.

To support this, the definition section is extended with two new elements, a code to support direct-reference codes, and a codeSystem to support specifying intended code system versions for value set expansion.

Direct-Reference Codes

When single codes are used within CQL-Based HQMF measures, there are two general categories of usage that need to be accounted for:

1. Directly referenced codes in a CQL Retrieve
2. Directly referenced codes in an expression (such as a membership or equality test) outside of a retrieve

Both of these cases will result in the appearance of a code element in the definition section of the HQMF XML. For example:

code "Venous foot pump, device (physical object)": '442023007' from "SNOMED-CT:March 2016" 
  display 'Venous foot pump, device (physical object)'

This direct-reference code would appear in the definition section as:

<definition>
  <cql-ext:code 
      code="442023007" 
      codeSystem="2.16.840.1.113883.6.96" 
      codeSystemName="SNOMED-CT" 
      codeSystemVersion="201609">
    <!-- This is the identifier of the Code from the CQL library -->
    <displayName value="Venous foot pump, device (physical object)"/>
  </cql-ext:code>
</definition>

When the code is used directly in a CQL retrieve, the code is provided as part of the Data Criteria in the same way that value sets are provided now. This provides some backwards compatibility for existing HQMF processing systems:

define "Venous Foot Pumps Applied":
  ["Device, Applied": "Venous foot pump, device (physical object)"]

In addition to the definition of the direct-reference code above, this retrieve would result in the following Data Criteria entry:

<entry typeCode="DRIV">
  <localVariableName value="Venousfootpumps(VFP)_DeviceApplied_sqAaY"/>
  <procedureCriteria classCode="PROC" moodCode="EVN">
  <templateId>
    <item extension="2015-09-30" root="2.16.840.1.113883.10.20.28.3.13"/>
  </templateId>
  <id extension="Venousfootpumps(VFP)_DeviceApplied" root="40280381-3d27-5493-013d-4bd0bae45a5b"/>
  <!-- NOTE: This code is defined by the HQMF QDM Templates, not the measure itself -->
  <code code="360030002" codeSystem="2.16.840.1.113883.6.96">
    <displayName value="Application of Device"/>
  </code>
  <title value="Device, Applied"/>
  <statusCode code="COMPLETED"/>
  <participation typeCode="DEV">
    <role classCode="MANU">
    <playingDevice classCode="DEV" determinerCode="KIND">
      <!-- Use the full code information directly (no need to reference the definition above) -->
      <code code="442023007" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SNOMED-CT" codeSystemVersion="201609">
      <!-- This is the identifier of the Code from the CQL library -->
      <displayName value="Venous foot pump, device (physical object)"/>
      </code>
    </playingDevice>
    </role>
  </participation>
  </procedureCriteria>
</entry>

If the direct-reference code is not used within a CQL retrieve, it will only appear in the definition section, not in any data criteria.

Value Sets

When value sets are referenced in CQL, the same two categories of reference must be accounted for:

1. Value sets referenced in a CQL Retrieve
2. Value sets referenced in an expression (such as a membership or equality test) outside of a retrieve

Both of these cases will result in the appearance of a valueSet element in the definition section of the HQMF XML. For example:

valueset "Encounter Inpatient SNOMEDCT Value Set":
  'urn:oid:2.16.840.1.113883.3.666.7.307' 
  version 'urn:hl7:version:20160929'
  codesystems { "SNOMED-CT" }

As with direct reference codes, this declaration will result in an entry in the definition section of the HQMF XML:

<definition>
  <valueSet classCode="OBS" moodCode="DEF">
    <!-- This is the id of the value set from the CQL library with the URI prefixes removed -->
    <id root="2.16.840.1.113883.3.666.5.307"/>
    <!-- This is the identifier of the ValueSet from the CQL library -->
    <title value="Encounter Inpatient SNOMEDCT Value Set"/>
    <!-- Version attribute from the CQL value set declaration, without URI prefixes -->
    <cql-ext:version value="20160929"/>
    <!-- System attribute(s) from the CQL value set declaration. This example only uses one code system because the value set is specifically a SNOMED-CT value set. However, if the value set is defined with multiple code systems, multiple system elements may be provided here to identify the intended version of each code system to be used to obtain the expansion of the value set. -->
    <cql-ext:system value="SNOMED-CT"/>
  </valueSet>
</definition>

And when the value set is used in a retrieve, it will appear in a data criteria in the same way that it does in the current QDM-Based HQMF measure document:

define "Inpatient Encounter":
  ["Encounter, Performed": "Encounter Inpatient SNOMEDCT Value Set"]

This retrieve will result in the following data criteria entry:

<entry typeCode="DRIV">
  <localVariableName value="EncounterInpatient_EncounterPerformed_Gyjcg"/>
  <encounterCriteria classCode="ENC" moodCode="EVN">
    <templateId>
      <item extension="2015-09-30" root="2.16.840.1.113883.10.20.28.3.5"/>
    </templateId>
    <id extension="EncounterInpatient_EncounterPerformed" root="ea6be543-6718-4a29-a928-c4acc1b20fca"/>
    <!-- Valueset is still referenced by OID from data criteria -->
    <!-- ValuesetVersion is specified -->
    <!-- Do Not use displayName for the name of the value set, refer to the definition.title element -->
    <!-- Do Not use URIs, for consistency with HQMF and V3 in general, use the OIDs -->
    <code valueSet="2.16.840.1.113883.3.666.5.307" valueSetVersion="20160929"/>
    <title value="Encounter, Performed"/>
    <statusCode code="COMPLETED"/>
  </encounterCriteria>
</entry>

If the value set is not used within a CQL retrieve, it will only appear in the definition section, not in any data criteria.

Code Systems

Code system declarations are used in CQL as part of Code and Value Set declarations. When they are used in Code declarations, because the code system information can be specified as part of the code element already, there is no need to reference the code system declaration.

For value sets, however, code systems are used to specify the intended code system version to be used to expand the value set, and as such, need to be present in the terminology section of the HQMF.

When a code system declaration appears in the CQL for a measure:

codesystem "SNOMED-CT": 'urn:oid:2.16.840.1.113883.6.96'
  version 'urn:hl7:version:201609'

It will result in a codeSystem entry in the definition section:

<definition>
  <!-- This definition correspondes to the Code System declaration from the CQL library. The id is the id of the code system declaration with URI prefixes removed. The name is the identifier of the Code System in CQL, 'SNOMED-CT' in this case. This is the target of the system element in the valueSet definition, referenced by the name element. -->
  <cql-ext:codeSystem id="2.16.840.1.113883.6.96" name="SNOMED-CT" version="201609"/>
</definition>

This definition is then referenced by name from the system element of the valueSet definition as described in the Value Sets section above.

Representation in the HQMF HTML (Human Readable)

Within the human readable, a new Terminology section will provide a complete description of the terminologies used within the measure. For example, given the following terminologies declared in the measure CQL:

codesystem "SNOMED-CT:March 2016": 'urn:oid:2.16.840.1.113883.6.96' version 'urn:hl7:version:March%202016'    
valueset "Face-to-Face Interaction": 'urn:oid:2.16.840.1.113883.3.464.1003.101.12.1048' codesystems { "SNOMED-CT:March 2016" }
code "Assessment of breastfeeding": '709261005' from "SNOMED-CT:March 2016" display 'Assessment of breastfeeding'

The Terminology section in the Human Readable HTML would contain:

codesystem "SNOMED-CT:March 2016" (2.16.840.1.113883.6.96 version March 2016)
valueset "Face-to-Face Interaction" (2.16.840.1.113883.3.464.1003.101.12.1048, SNOMED-CT version March 2016)
code "Assessment of breastfeeding" ("SNOMED-CT version March 2016 Code (709261005)")

For data criteria that reference value sets and codes, the human readable would only contain name of the value set or code as declared in the terminology section, a value set version, if applicable, and the versions of any code systems used, if applicable:

"Encounter, Performed: Face-to-Face Interaction" using "Face-to-Face Interaction (2.16.840.1.113883.3.464.1003.101.12.1048, SNOMED-CT version March 2016)"
"Assessment, Performed: Assessment of breastfeeding" using "Assessment of breastfeeding (SNOMED-CT version March 2016 Code 709261005)"