Quality Measure Implementation Guide (STU5), published by HL7 International / Clinical Quality Information. This guide is not an authorized publication; it is the continuous build for version 5.0.0-draft built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/cqf-measures/ and changes regularly. See the Directory of published versions
This topic discusses the use of Clinical Quality Language (CQL) to provide computable and/or executable representation of the various criteria of a measure through the expression-valued elements of the Measure resource. The CQLMeasure and ELMMeasure profiles define the expectations for measures that make use of CQL and/or ELM. Support for the use of other expression languages is possible, but is out of scope for this implementation guide.
Measures that use CQL do so with libaries to contain the logic used to define the various criteria of the measure. CQL libraries are used in accordance with the Using CQL With FHIR (UCWF) implementation guide, as well as additional conformance requirements specific to the use of measures, as detailed in the following sections.
For ease of reference, conformance requirements from the Using CQL With FHIR IG are referred to with the following notation: UCWF:2.1, which refers to Conformance Requirement 2.1 in the Using CQL With FHIR implementation guide.
Consistent with the UCWF IG, Measures that make use of CQL use Libraries.
Conformance Requirement 4.1 (Library Usage):
For example:
library EXM146 version '4.0.0'
Snippet 4-1: Library line from EXM146.cql
Consistent with the UCWF IG, this IG recommends an approach to Library Versioning used within Measures to help track and manage dependencies. The approach recommended here is based on the Semantic Versioning Scheme.
Conformance Requirement 4.2 (Library Versioning):
For example:
library EXM146 version '3.0.0'
This would indicate the first major version of the EXM146 library. A minor change could be released by incrementing the minor version:
library EXM146 version '3.1.0'
And a major change could be released by incrementing the major version, and resetting the minor version: Minor changes are expected to retain backwards-compatibility, but may introduce new features and functionality, while patch changes are expected to retain forward and backwards-compatibility, and may only be used to fix issues.
library EXM146 version '4.0.0'
Snippet 4-2: Library line from EXM146.cql, the fourth major version.
Consistent with the UCWF IG, this IG allows measures to use Nested Libraries. However, this IG requires that all expressions referenced from a Measure be included in a single library to ensure that expression identifiers used in the Measure need not be qualified identifiers.
Conformance Requirement 4.3 (Nested Libraries):
For example:
include Common version '2.0.0' called Common
Snippet 4-3: Nested library within EXM146.cql
Consistent with the UCWF IG, this IG recommends the use of Library Namespaces.
Conformance Requirement 4.4 (Library Namespaces):
For example, the following library declaration illustrates the use of a namespace:
library CMS.Common version '2.0.0'
Snippet 4-4: Library namespace
CQL can be used with any Data Model. In the context of a Measure, any referenced CQL library must identify the same data model.
Conformance Requirement 4.5 (CQL Data Model):
For example:
using FHIR version '4.0.1'
Snippet 4-5: Data Model line from EXM146.cql
Consistent with the UCWF IG, Code Systems referenced within CQL expressions make use of the codesystem
declaration in CQL.
Conformance Requirement 4.6 (Code System Specification):
For example:
codesystem "SNOMED CT:2017-09": 'http://snomed.info/sct'
version 'http://snomed.info/sct/731000124108/version/201709'
Snippet 4-6: codesystem definition line from Terminology.cql.
The representation of codesystem declarations in a Library is discussed in the Terminology topic of this IG.
Consistent with the UCWF IG, Value Sets referenced within CQL expressions make use of the valueset
declaration in CQL.
Conformance Requirement 4.7 (Value Set Specification):
For example:
valueset "Acute Pharyngitis": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.102.12.1011'
Snippet 4-7: Valueset reference from EXM146.cql
The canonical URL for a value set is typically defined by the value set author, though it may be provided by the
publisher as well. For example, value sets defined in the Value Set Authority Center and exposed via the VSAC FHIR
interface have a base URL of http://cts.nlm.nih.gov/fhir/
. This base is then used to construct the canonical URL for
the value set (in the same way as any FHIR URL) using the resource type (ValueSet
in this case) and the id (the value
set OID in this case). Note that the canonical URL is a globally unique, stable, version-independent identifier for the
value set. See Canonical URLs in the base FHIR specification for more information.
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 "Acute Pharyngitis (1)": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.102.12.1011.1'
valueset "Acute Pharyngitis (2)": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.102.12.1011.2'
Snippet 4-8: Valueset declarations for different value sets with the same name
Note carefully that although this URL may be resolveable for some terminology implementations, this is not necessarily the
case. This use of a canonical URL can be resolved as a search by the url
element:
GET fhir/ValueSet?url=http%3A%2F%2Fcts.nlm.nih.gov%2Ffhir%2FValueSet%2F2.16.840.1.113883.3.464.1003.102.12.1011.1
Snippet 4-9: FHIR API query to retrieve a value set by it's canonical identifier using the url search parameter
Consistent with the UCWF IG, Value Set Version information is not required to be included. As a best-practice, terminology versioning information is specified externally using a version manifest. However, if versioning information is included, it must be done in accordnace with terminology usage specified by FHIR.
Conformance Requirement 4.8 (Value Set Specification By Version):
For example:
valueset "Encounter Inpatient SNOMEDCT Value Set":
'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.666.7.307|20160929'
Snippet 4-10: valueset definition from Terminology.cql.
This is a version specific value set reference, and can be resolved as a search by the url
and version
elements:
GET fhir/ValueSet?url=http%3A%2F%2Fcts.nlm.nih.gov%2Ffhir%2FValueSet%2F2.16.840.1.113883.3.666.7.307&version=20160929
Snippet 4-11: FHIR API query to retrieve a value set by it's url and version
Measures that make use of CQL must do so in accordance with Value Set Expansion as described in the UCWF IG.
Conformance Requirement 4.9 (Value Set Expansion):
The representation of valueset
declarations in a Library is discussed in the Terminology topic of this IG, consistent with the Representation in Narrative topic in the UCWF IG.
Consistent with the UCWF IG, this implementation guide recommends against the use of string-based membership testing.
Conformance Requirement 4.10 (String-based Membership Testing):
Consistent with the UCWF IG, CQL used with Measures can make use of direct-reference codes.
Conformance Requirement 4.11 (Direct-reference Codes):
For example:
code "Venous foot pump, device (physical object)": '442023007' from "SNOMED CT"
Snippet 4-12: code definition from Terminology.cql.
The representation of code declarations in a Library is discussed in Terminology of this IG, consistent with the Representation in Narrative topic in the UCWF IG.
This implementation guide recommends the UCUM Best Practices found in the UCWF IG.
Consistent with the UCWF IG, CQL used with Measures may make use of the CQL concept declaration, but care must be taken to ensure that it is not used as a surrogate for proper value set definition.
Conformance Requirement 4.12 (Concepts):
Consistent with the UCWF IG, CQL used by Measures should use descriptive and meaningful library-level identifiers, as discussed in the Library-level Identifiers topic
Conformance Requirement 4.13 (Library-level Identifiers):
Consistent with the UCWF IG, CQL used by Measures must refer to Data Type Names as dictated by the CQL specification, as well as the Data Models in use. For FHIR-based Quality Measures using QI-Core profiles, these will be the author-friendly identifiers for the QI-Core profiles.
Conformance Requirement 4.14 (Data Type Names):
For example:
define "Flexible Sigmoidoscopy Performed":
[Procedure: "Flexible Sigmoidoscopy"] FlexibleSigmoidoscopy
where FlexibleSigmoidoscopy.status = 'completed'
and FlexibleSigmoidoscopy.performed ends 5 years or less on or before end of "Measurement Period"
Snippet 4-13: Expression definition from EXM130.cql
Procedure
is the name of the model data type (FHIR resource type) in this example.
Consistent with the UCWF IG, CQL used by Measures must refer to Element Names as dictated by the CQL specification, as well as the Data Models in use.
Note that when FHIR and FHIR IGs are used as the data model, the term "element" is synonymous with "attribute". Some data models, such as QDM, use the "attribute".
Conformance Requirement 4-15 (Element Names):
Examples of elements (i.e. attributes) conforming to Conformance Requirement 4.15 are given below. For a full list of valid names of attributes for a data model, refer to an appropriate data model specification such as QI-Core.
period
authoredOn
result
Snippet 4-14: Example element names
Consistent with the UCWF IG, CQL used by Measures must follow conventions for naming of Aliases and Arguments.
Conformance Requirement 4.16 (Aliases and Argument Names):
For example:
define "Encounters During Measurement Period":
"Valid Encounters" QualifyingEncounter
where QualifyingEncounter.period during "Measurement Period"
define function "ED Stay Time"(Encounter "Encounter"):
duration in minutes of Encounter.period
Snippet 4-15: Example alias and argument names
QualifyingEncounter
is the alias in this example, while Encounter
is the argument name.
Inclusion of CQL content used within quality measures is accomplished through the use of Library Resources as described by the Using CQL With FHIR implementation guide. These libraries are then referenced from Measure resources using the library
element. The content of the CQL library is included using the content
element of the Library. Conformance requirements for Library resources included with Measure content are discussed in the Related Documents topic of this IG.
Additional guidance and best-practices for the use of CQL in measures can be found in the Patterns topic of the Using CQL With FHIR implementation guide, including guidance on:
The use of Expression Logical Model (ELM) as a basis for sharing logic is discussed in the Using ELM topic of the Using CQL With FHIR implementation guide, including guidance on: