This page is part of the Quality Measure STU2 for FHIR R4 Implementation Guide (v2.1.0: STU3 Ballot 1) based on FHIR R4. The current version which supercedes this version is 3.0.0. For a full list of available versions, see the Directory of published versions

Using CQL

Libraries

A CQL artifact is referred to as a library.

Conformance Requirement 4.1 (Library Declaration):

1. Any CQL library referenced by a Measure must contain a library declaration line as the first line of the library.
2. The library identifier SHALL be a valid un-quoted identifier and SHALL NOT contain underscores
3. The library declaration line SHALL contain a version number.
4. The library version number SHALL follow the convention :
   < major >.< minor >.< patch >

Library Versioning

This IG recommends an approach to versioning libraries 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):

1. For artifacts in draft status, the versioning scheme SHALL NOT apply, and there is no expectation that artifact contents are stable
2. The versioning scheme SHALL apply when an artifact moves to active status.

There are three main types of changes that can be made to a library. First, a library can be changed in a way that would alter the public use of its components. Second, a library can be changed by adding new components or functionality but without changing existing components are used. And third, a library can be changed in a way that does not change existing components or add new components, but only corrects or improves the originally intended functionality. By exposing version numbers that identify all three types of changes, libraries can be versioned in a way that makes clear when a change will impact usage, versus when a change can potentially be safely incorporated as an update. The first type of change will be referred to as a “major” change, and will require incrementing of the “major version number”. The second type of change will be referred to as a “minor” change, and will only require incrementing of the “minor version number”. And finally, the third type of change will be referred to as a “patch”, and will only require incrementing the “patch version number”. Version numbers for CQL libraries can then be represented as:

<major>.<minor>.<patch>

For example:

library EXM146 version '1.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 '1.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 '2.0.0'

Snippet 4-1: Library line from EXM146.cql, the second major version.

Nested Libraries

CQL allows libraries to re-use logic already defined in other libraries. This is accomplished by utilizing the include line as in Snippet 4-2.

includes Common version '2.0.0' called Common

Snippet 4-2: Nested library within EXM146.cql

The set of all CQL libraries used to define a Measure must adhere to Conformance Requirement 4.3.

Conformance Requirement 4.3 (Nested Libraries):

1. CQL libraries SHALL be structured such that all CQL expressions referenced by the Measure population criteria are contained within a single library.
2. CQL libraries SHALL use a called clause for all included libraries
3. The called-alias for an included library SHOULD be consistent for usages across libraries

Because of this conformance statement, the primary library for a measure can always be determined by looking at the library referenced by the initial population criteria for the measure.

Library Namespaces

CQL allows libraries to define a namespace that can be used to organize libraries across different groups of users. Within a namespace, library names are required to be unique. Across namespaces, the same library name may be reused. For example, OrganizationA and OrganizationB can both define a library named Common, so long as they use different namespaces. For example, consider the following library declaration:

library CMS.Common version '2.0.0'

This example declares a library named Common in the CMS namespace. Per the CQL specification, the namespace for a library is included in the ELM, along with a URI that provides a globally unique, stable identifier for the namespace. For example, the URI for the CMS namespace would be https://ecqi.healthit.gov/ecqm/measures.

Note that this is a URI that may or may not correspond to a reachable web address (a URL). The important aspect is not the addressability, but the uniqueness, ensuring that library name collisions cannot occur.

Conformance Requirement 4.4 (Library Namespaces):

1. CQL libraries SHOULD use namespaces.
2. When a namespace is not used, the library SHALL be considered part of a “public” global namespace for the purposes of resolution within a given environment.

In addition, because the namespace of a library is part of the text, changing the namespace of a library requires a new version, just like any other change to the text of the library. However, because a change to the namespace is not a material change to the library itself, changing the namespace does not require a different version-independent identifier to be used for the library.

Data Model

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):

1. All CQL expressions used directly or indirectly within a measure SHALL reference a single data model
2. Data Model declarations SHALL include a version declaration.

For example:

using FHIR version '3.0.0'

Snippet 4-3: Data Model line from EXM146.cql

Code Systems

Conformance Requirement 4.6 describes how to specify a code system within a CQL library.

Conformance Requirement 4.6 (Code System Specification):

1. Within CQL, the identifier of any code system reference SHALL be specified using a URI for the code system.
2. The URI SHALL be the canonical URL for the code system
3. The Code System declaration MAY include a version, consistent with the URI specification for FHIR and the code system

For example:

codesystem "SNOMED CT:2017-09": 'http://snomed.info/sct'
  version 'http://snomed.info/sct/731000124108/version/201709'

Snippet 4-4: codesystem definition line from Terminology.cql.

The canonical URL for a code system is a globally unique, stable, version-independent identifier for the code system. The base FHIR specification defines canonical URLs for most common code systems here.

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

Version information for code systems is not required to be included in eCQMs; terminology versioning information may be specified externally. However, if versioning information is included, it must be done in accordance with the terminology usage specified by FHIR.

If no version is specified, then the default behavior for a FHIR terminology server is to use the most recent code system version available on the server.

Value Sets

Conformance Requirement 4.7 describes how to specify a valueset within a CQL library.

Conformance Requirement 4.7 (Value Set Specification):

1. Within CQL, the identifier of any value set reference SHALL be specified using a URI for the value set.
2. The URI SHALL be the canonical URL for the value set
3. The URI MAY include a version, consistent with versioned canonical URL references in FHIR

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-5: 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'

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

Value Set Version

Version information for value sets is not required to be included in eCQMs; terminology versioning information may be specified externally. However, if versioning information is included, it must be done in accordance with the terminology usage specified by FHIR.

Conformance Requirement 4.8 describes how to retrieve an expansion of a value set by version.

Conformance Requirement 4.8 (Value Set Specification By Version):

1. When retrieving the expansion of a value set by version, append the version identifier to the canonical URL of the value set, separated by a pipe (|)

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-6: 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

Value Set Expansion

It is important to maintain the distinction between the definition of a value set and the expansion of a value set. The searches described in previous sections all retrieve the definition of a value set. For the purposes of local evaluation, implementations may wish to retrieve the expansion of a value set, or the set of all codes that are defined to be in the value set by the definition.

Because the definition of a value set can, and often does, include codes from a code system based on properties of that code system, the expansion of a value set is sensitive to the versions of the code systems used in the definition. This means that in general, the expansion of a value set is version-specific, and care must be taken to ensure that version considerations are taken into account when using the results of an expansion.

Conformance Requirement 4.9 (Value Set Expansion):

1. Expressions that require implementations to perform the complete expansion of a value set SHOULD NOT be used. The use of the terminology membership operator is preferred.

For example, rather than combining multiple value sets using a “union”, separate membership tests in each value set should be used. For more information, see the Value Set Expansion topic in the base FHIR specification.

Representation in a Library

The representation of valueset declarations in a Library is discussed in the Measure Conformance Chapter of this IG.

String-based Membership Testing

Although CQL allows the use of strings as input to membership testing in value sets, this capability should be disallowed in measure CQL as it can lead to incorrect matching if the code system is ignored.

Conformance Requirement 4.10 (String-based Membership Testing):

1. String-based membership testing SHALL NOT be used in CQL libraries

For example, given a valueset named "Administrative Gender", the following CQL expression would be non-conformant:

'female' in "Administrative Gender"

Codes

When direct-reference codes are represented within CQL, the logical identifier is not recommended to be a URI. Instead, the logical identifier is the code from the code system.

Conformance Requirement 4.11 (Direct Referenced Codes):

1. When direct-reference codes are represented within CQL, the logical identifier:
   a. MUST NOT be a URI.
   b. SHALL be a code from the code system.

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

Snippet 4-7: code definition from Terminology.cql.

Note that for direct-reference code usage, the local identifier (in Snippet 4-7 the local identifier is “Venous foot pump, device (physical object)”) 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.

CQL supports both version-specific and version-independent specification of and comparison to direct-reference codes. The best practice is for measure authors to use version-independent direct-reference codes and comparisons unless there is a specific reason not to (such as the code is retired in the current version). Even in the case that version-specific direct-reference codes are required, best practice is still to use the equivalent (~) operator in CQL for the comparison (again, unless there is a specific reason to do version-specific comparison)

Representation in a Library

When direct-reference codes are used within eCQMs, they will be represented in the narrative (Human-readable) as:

"Assessment, Performed: Assessment of breastfeeding"
using "Venous foot pump, device (physical object) SNOMED CT Code (442023007)"

The representation of code declarations in a Library is discussed in Measure Conformance Chapter of this IG.

Concepts

In addition to codes, CQL supports a concept construct, which is defined as a set of codes that are all semantically equivalent. CQL Concepts are not currently used within measure development and SHALL NOT be used within FHIR-based eCQMs, except to the extent that individual codes will be implicitly converted to concepts for the purposes of comparison with the Concept-value elements in FHIR resources.

Conformance Requirement 4.12 (Concepts):

1. The CQL concept construct SHALL NOT be used.

Library-level Identifiers

A “library-level identifier” is any named expression, function, parameter, code system, value set, concept, or code defined in the CQL. The library name referenced in the library-line, the data model, and any referenced external library should not be considered “library-level identifiers”. Library-level identifiers ought to be given a descriptive meaningful name (avoid abbreviations) and conform to Conformance Requirement 4.13.

Conformance Requirement 4.13 (Library-level Identifiers):

1. Library-level identifiers referenced in the CQL:
   a. SHOULD Use quoted identifiers
   b. SHOULD Use Title Case
   c. MAY Include spaces

For example:

define function
   "Includes Or Starts During"(Condition "Condition", Encounter "Encounter"):
      Interval[Condition.onset, Condition.abatement] includes Encounter.period
         or Condition.onset during Encounter.period

Snippet 4-8: Function definition from Common.cql

Data Type Names

A “data type” in CQL refers to any named type used within CQL expressions. They may be primitive types, such as the system-defined “Integer” and “DateTime”, or they may be model-defined types such as “Encounter” or “Medication”. For FHIR-based eCQMs using the QI-Core profiles, these will be the author-friendly identifiers for the QI-Core profile. Data types referenced in CQL libraries to be included in a Measure must conform to Conformance Requirement 4.14.

Conformance Requirement 4.14 (Data Type Names):

1. Data type names referenced in CQL SHALL:
   a. Use quoted identifiers only if necessary (i.e. the data type name includes spaces)
   b. Use PascalCase plus appropriate spacing

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-9: Expression definition from EXM130.cql

Negation in FHIR

Two commonly used patterns for negation in quality measurement are:

• Absence of evidence for a particular event
• Documentation of an event not occurring, together with a reason

For the purposes of quality measurement, when looking for documentation that a particular event did not occur, it must be documented with a reason in order to meet the intent. If a reason is not part of the intent, then the absence of evidence pattern should be used, rather than documentation of an event not occurring.

To address the reason an action did not occur (negation rationale), the eCQM must define the event it expects to occur using appropriate terminology to identify the kind of event (using a value set or direct-reference code), and then use additional criteria to indicate that the event did not occur, as well as identifying a reason.

The following examples differentiate methods to indicate (a) presence of evidence of an action, (b) absence of evidence of an action, and (c) negation rationale for not performing an action. In each case, the “action” is an administration of medication included within a value set for “Antithrombotic Therapy”.

Presence

Evidence that “Antithrombotic Therapy” (defined by a medication-specific value set) was administered:

define "Antithrombotic Administered":
  ["MedicationAdministration": "Antithrombotic Therapy"] AntithromboticTherapy
    where AntithromboticTherapy.status = 'completed'
      and AntithromboticTherapy.category = "Inpatient Setting"

Absence

No evidence that “Antithrombotic Therapy” medication was administered:

define "No Antithrombotic Therapy":
  not exists (
    ["MedicationAdministration": "Antithrombotic Therapy"] AntithromboticTherapy
      where AntithromboticTherapy.status = 'completed'
        and AntithromboticTherapy.category = "Inpatient Setting"
  )

Negation Rationale

Evidence that “Antithrombotic Therapy” medication administration did not occur for an acceptable medical reason as defined by a value set referenced by the eCQM (i.e., negation rationale):

define "Antithrombotic Not Administered":
  ["MedicationAdministration": "Antithrombotic Therapy"] NotAdministered
    where NotAdministered.notGiven is true
      and NotAdministered.reasonNotGiven in "Medical Reason"

In this example for negation rationale, the logic looks for a member of the value set “Medical Reason” as the rationale for not administering any of the anticoagulant and antiplatelet medications specified in the “Antithrombotic Therapy” value set. To report Antithrombotic Therapy Not Administered, this is done by referencing the URI of the “Antithrombotic Therapy” value set using the value set extension to indicate providers did not administer any of the medications in the “Antithrombotic Therapy” value set. By referencing the value set URI to negate the entire value set rather than reporting a specific member code from the value set, clinicians are not forced to having to arbitrarily select a specific medication from the “Antithrombotic Therapy” value set that they did not administer in order to negate.

Similarly, to report “Procedure, Not Performed”: “Cardiac Surgery” with a reason, the URI of “Cardiac Surgery” value set is referenced by using the value set extension to indicate providers did not perform any of the cardiac surgery specified in the “Cardiac Surgery” value set.

Attribute Names

All attributes referenced in the CQL follow Conformance Requirement 4.15.

Conformance Requirement 4-15 (Attribute Names):

1. Data model attributes referenced in the CQL:
   a. SHALL NOT Use quoted identifiers
   b. SHALL Use camelCase

Examples of attributes conforming to Conformance Requirement 4.15 are given below. For a full list of valid of attributes, refer to an appropriate data model specification such as QI-Core.

period
authoredOn
result

Aliases and Argument Names

Aliases are used in CQL as local variable names to refer to sections of code. When defining a function, argument names are used to create scoped variables that refer to the function inputs. Both aliases and argument names conform to Conformance Requirement 4.16.

Conformance Requirement 4.16 (Aliases and Argument Names):

1. Aliases and argument names referenced in the CQL:
   a. SHALL NOT Use quoted identifiers
   b. SHALL Use PascalCase
   c. SHOULD Use descriptive names (no abbreviations)

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

Library Resources

filename = <CQL library name>.cql

Use of Terminologies

FHIR supports various types of terminology-valued elements, including:

• code
  
• Coding
  
• CodeableConcept
  

These types correspond directly to the CQL primitive types:

• String
  
• Code
  
• Concept
  

In addition to the type of element, FHIR provides the ability to bind these elements to specific codes, in the form of a direct-reference code (constraint to a specific code in a CodeSystem), or a binding to a ValueSet. These bindings can be different binding strengths

• required - To be conformant, the concept in this element SHALL be from the specified value set.
  
• extensible - To be conformant, the concept in this element SHALL be from the specified value set if any of the codes within the value set can apply to the concept being communicated. If the value set does not cover the concept (based on human review), alternate codings (or, data type allowing, text) may be included instead.</br>
• preferred - Instances are encouraged to draw from the specified codes for interoperability purposes but are not required to do so to be considered conformant.
  
• example - Instances are not expected or even encouraged to draw from the specified value set. The value set merely provides examples of the types of concepts intended to be included.
  

Within CQL, references to terminology code systems, value sets, codes, and concepts are directly supported, and all such usages are declared within CQL libraries, as described in the Terminology section of the CQL Author’s Guide.

When referencing terminology-valued elements within CQL, the following comparison operations are supported:

• Equal (=)
  
• Equivalent (~)
  
• In (in)
  

Time Valued Quantities

For time-valued quantities, in addition to the definite duration UCUM units, CQL defines calendar duration keywords to support calendar-based durations and arithmetic. For example, UCUM defines an annum (‘a’) as 365.25 days, whereas the year (‘year’) duration in CQL is specifically a calendar year. This difference is important, especially when performing calendar arithmetic.

For example if we take a datetime and subtract a calendar year

@2019-01-01T05:00:00 - 1 year

This would resolve to 2018-01-01T05:00:00

However, if we take the same datetime and subtract a UCUM annum

@2019-01-01T05:00:00 - 1 'a'

This would resolve to 2017-12-31T23:00:00

See the definition of the Quantity type in the CQL Author’s Guide, as well as the Date/Time Arithmetic discussion for more information.

Translation to ELM

Tooling exists to support translation of CQL to ELM for distribution in XML or JSON formats. These distributions are included with eCQMs to facilitate implementation. The existing translator tooling applies to both measure and decision support development, and has several options available to make use of different data models in different environments. For measure development with FHIR, the following options are recommended: