-
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 URI 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, RFC 3406 for formal or informal urns, there is an expectation of uniqueness. The prefix hl7
gives that.
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, they would show up in the HQMF HTML (Human-readable) as:
"Risk 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>
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