-
Notifications
You must be signed in to change notification settings - Fork 23
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, relying instead on external terminology systems to provide terminological content. Instead, each of these constructs provides a mechanism for defining a logical versioned identifier, and then allows CQL logic to reference these constructs by their local 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.
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.
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'
Note that the because the Value Set Authority Center (VSAC) supports different approaches to retrieving the expansion of a valueset through its Sharing Value Sets (SVS) API. For the purposes of this guidance, two approaches are described: 1) by version, and 2) by profile.
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.
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.
Within the CQL-Based HQMF HTML (Human Readable), value set information would be displayed in the same way as it is now (the OID without the version information). In the underlying HQMF XML, the value set information would be specified using the valueSet and valueSetVersion attributes of the code element within criteria. The value of these attributes would be the full contents of the logical identifiers in the CQL:
valueSet="2.16.840.1.113883.3.464.1003.101.12.1048"
valueSetVersion="urn:hl7:version:2016-04-01"
Or using a profile:
valueSet="2.16.840.1.113883.3.464.1003.101.12.1048"
valueSetVersion="urn:hl7:profile:MU2%20Update%202016-04-01"
Note that in the HQMF, the valueset attribute is an OID, and so the urn:oid: prefix is not required (or allowed). This restriction means that for CQL developed for use with HQMF, valueset identifiers must always be OIDs URNs, not URLs in general.
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" must 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.
When single codes are used within CQL-Based HQMF measures, there are two general categories of usage that need to be accounted for:
- Directly referenced codes in a CQL Retrieve
- Directly referenced codes in an expression (such as a membership or equality test) outside of a retrieve
For the second case, directly referenced codes could be exposed in the HQMF XML and HTML in the same way that value sets are, namely as part of the Data Criteria section. In the HTML (Human-readable), this would be:
"Assessment, Performed: Assessment of breastfeeding"
using "Assessment of breastfeeding SNOMED-CT version March 2016 Code (709261005)"
And they would be represented in the underlying HQMF XML as:
<entry typeCode="DRIV">
<localVariableName value="RiskAssessment_Performed_Assessment_of_breastfeeding"/>
<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="RiskAssessment_Performed_Assessment"
root="ea6be543-6718-4a29-a928-c4acc1b20fca"/>
<code code="709261005"
codeSystem="2.16.840.1.113883.6.96"
codeSystemName="SNOMED-CT"
codeSystemVersion="March 2016">
<displayName value="Assessment of breastfeeding"/>
</code>
<title value="Risk Assessment, Performed"/>
<statusCode code="COMPLETED"/>
</encounterCriteria>
</entry>
However, since the second category of reference can appear anywhere within the CQL, and can be an expression involving any attribute of any data type (including intermediate types not defined in QDM), there is no way in general to map this category of directly referenced codes to the data criteria section.
As a result, we recommend the creation of a new section in the Human Readable HTML, a Terminology section. This section would contain only the code systems, valuesets, and directly referenced codes used by the measure logic, no matter where they appear. It would effectively be an HTML rendering of the terminology-related declarations in the CQL. Given the following CQL declarations:
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'
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" using "2.16.840.1.113883.6.96 version March 2016"
valueset "Face-to-Face Interaction" using "2.16.840.1.113883.3.464.1003.101.12.1048"
code "Assessment of breastfeeding" using "SNOMED-CT version March 2016 Code (709261005)"
The difficulty in expressing this in the underlying HQMF XML is that there is no way to provide a terminology binding without specifying an "act template" to which it is related (i.e. a full Data Criteria). As such, we suggest that a specific template of Observation be used that is only ever part of a terminology usage declaration. This approach can be generalized to allow for all of the terminology declarations. For code systems:
<entry typeCode="DRIV">
<localVariableName value="CodeSystem_SNOMED_CT_March2016"/>
<observationCriteria classCode="OBS" moodCode="EVN">
<templateId>
<item root="TBD: Template for Code System Terminology Declarations"/>
</templateId>
<id extension="CodeSystem_SNOMED_CT_March2016"
root="40280381-3d27-5493-013d-4dc3479d698d"/>
<code codeSystem="2.16.840.1.113883.6.96" codeSystemName="SNOMED CT">
<displayName value="SNOMED_CT_March2016"/>
</code>
<title value="SNOMED-CT:March%202016"/>
</observationCriteria>
</entry>
For value sets:
<entry typeCode="DRIV">
<localVariableName value="ValueSet_Face-to-face-interaction"/>
<observationCriteria classCode="OBS" moodCode="EVN">
<templateId>
<item root="TBD: Template for Value Set Terminology Declarations"/>
</templateId>
<id extension="ValueSet_Face-to-face-interaction"
root="40280381-3d27-5493-013d-4dc3479d698d"/>
<code valueset="2.16.840.1.113883.3.464.1003.101.12.1048">
<displayName value="Face-to-face Interaction"/>
</code>
<title value="ValueSet Face-to-face Interaction"/>
</observationCriteria>
</entry>
and for directly referenced codes:
<entry typeCode="DRIV">
<localVariableName value="Code_Assessment_of_Breastfeeding"/>
<observationCriteria classCode="ENC" moodCode="EVN">
<templateId>
<item root="TBD: Template for Code Terminology Declaration"/>
</templateId>
<id extension="Code_Assessment_of_Breastmentfeeding"
root="ea6be543-6718-4a29-a928-c4acc1b20fca"/>
<code code="709261005"
codeSystem="2.16.840.1.113883.6.96"
codeSystemName="SNOMED-CT"
codeSystemVersion="March 2016">
<displayName value="Assessment of breastfeeding"/>
</code>
<title value="Assessment of Breastfeeding"/>
</observationCriteria>
</entry>
The Data Criteria section would then be the same (except that it no longer contains attribute references), providing the Data Criteria definitions in terms of the terminology declarations already provided.
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.
Authoring Patterns - QICore v4.1.1
Authoring Patterns - QICore v5.0.0
Authoring Patterns - QICore v6.0.0
Cooking with CQL Q&A All Categories
Additional Q&A Examples
Developers Introduction to CQL
Specifying Population Criteria