Clinical Quality Language Specification
2.0.0 - R2 STU 1
Clinical Quality Language Specification
2.0.0 - R2 STU 1
Clinical Quality Language Specification, published by Clinical Decision Support WG. This guide is not an authorized publication; it is the continuous build for version 2.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/cql/ and changes regularly. See the Directory of published versions
| Page standards status: Informative | Maturity Level: N/A |
2.0 Change Log
Clinical Quality Language has been published as an HL7 and ANSI Normative standard since December of 2020. Version 1.5.3 of this specification was reaffirmed as an ANSI standard in September 2026, and at the same time, additional features of the language were introduced as trial-use in this CQL R2 STU1 Publication. The following topic provides an overview of the substantive changes introduced in this version. Note that this change summary provides an overview of everything that was changed as part of CQL R2 (i.e. it includes changes that were introduced in the ballot, as well as the reconciliation), whereas the change log that follows in this section details only the changes that were applied as part of reconciliation. For a listing of only changes that were applied as part of ballot, see the v2.0.0-ballot change log.
Directives provide an ability for translator options to be provided as part of the language.
See Directives
The first usage of directives is to provide a default comparison precision:
#DefaultComparisonPrecision: minutes
Means that all comparisons within the library that do not explicitly specify a precision will be performed to the minute.
#DefaultComparisonPrecision: minutes default included libraries
Means that this behavior will also be carried to included libraries that do not specify their own default comparison precision.
See Default Comparison Precision
CQL R2 introduces several enhancements to data model support.
Using statements can now include namespace qualifiers, allowing models to be referenced globally in the same way that libraries are.
using hl7.fhir.us.core.USCore
Using statements can now also include a called clause, allowing models to be referenced by local names
using hl7.fhir.us.core.USCore version '7.0.0' called USC
See Data Models
In addition, the components of models can now be defined directly within CQL with the introduction of define type, define context, and define conversion statements:
See Defining Models
Type Definitions
CQL R2 includes support for defining named types with the new define type statement:
define public type Quantity extends System.Any {
value System.Decimal,
unit System.String
}
Once defined in a library, these types function like any other type defined in a model brought in with a using statement, allowing authors to build data models directly in CQL.
Context Definitions
CQL R2 includes support for defining contexts with the new define context statement:
define context Patient of type FHIR.Patient with key { id }
Once a context is defined, it can be used in a context statement like any context brought in with a using statement.
In addition, types can declare their relationship to contexts with the related to clause of the define type statement:
define type Observation extends DomainResource {
subject Patient,
code CodeableConcept,
value Choice<CodeableConcept, Quantity>
...
}
related to Patient by { subject }
Conversion Definitions
CQL R2 includes support for defining conversions with the new define conversion statement:
define implicit conversion
from FHIR.Period to System.Interval<System.DateTime>
using FHIRHelpers.ToInterval
Once an implicit conversion is defined, it can be used to support implicit conversions like any other conversion brought in with a using statement.
Once an explicit conversion is defined, it can be referenced with the convert function like any other conversion.
CQL R2 includes support for parameter constraints:
/*
@constraint: error
@message: Measurement period must be a year
*/
define IsYearly: start of "Measurement Period" same year as end of "Measurement Period"
These constraints are expressions that must evaluate to true in order to make use of any expressions within the library.
CQL R2 also introduces support for parameter binding:
include ColorectalCancerElements called CCE
bind { AsOf: end of "Measurement Period" }
This example illustrates setting the AsOf parameter in the ColorectalCancerElements library to the end of "Measurement Period" in the current library.
CQL R2 introduces support for equivalent contains, a contains operator that uses equivalent semantics, rather than equality semantics.
define "EquivalentContainsIsTrue": { 'A', 'B', 'C' } ~contains 'a'
define "EquivalentContainsIsFalse": { 'B', 'C' } ~contains 'a'
This support enables not only equivalent contains use cases like the above examples, but terminological contains as well:
define CodeSystemContainsExample: SNOMED ~contains "Random SNOMED Code"
define ValueSetContainsExample: "Inpatient Encounter" ~contains "Random CPT Code"
In addition to providing a generally useful operation, this is used in the retrieve later to enable an important set of use cases involving negation and direct-reference codes.
See Equivalent Contains, Contains CodeSystem, and In Code System
CQL R2 introduced the equivalent in operator to clearly distinguish between equality- and equivalent-based membership:
define "EquivalentInIsTrue": 'a' ~in { 'A', 'B', 'C' }
define "EquivalentInIsFalse": 'a' ~in { 'B', 'C' }
And as with the ~contains operator, the terminological membership operators then make use of this new equivalent in:
define InCodeSystemExample: "Random SNOMED Code" ~in "SNOMED"
define InValueSetExample: "Random CPT Code" ~in "Inpatient Encounter"
For backwards compatibility, in still resolves to the terminological membership operators, but using the new ~in operator makes it explicit that equivalent in is being used.
See Equivalent In, In CodeSystem, and In ValueSet
A significant outstanding issue with supporting the use of direct-reference codes throughout CQL is the negation patterns. When the extent of an activity is represented with a value set, rather than a specific code, then the negation statement looking for negation of a particular code requires the use of the new ~contains operation. This can now be specified explicitly as in:
define "Reason for Macular Edema Absent Not Communicated (Explicit equivalent contains)":
[CommunicationNotDone: reasonCode ~contains "Macular edema absent (situation)"]
And this now means that direct-reference codes can be the target of a negation retrieve, such as:
define "Reason for Macular Edema Absent Not Communicated (Implicit equivalent contains)":
[CommunicationNotDone: "Macular edema absent (situation)"]
See Code Comparator
CQL R2 adds the ability to round Quantity values:
define "QuantityRound": Round(2.54 'cm') // 3 'cm'
See Quantity Round
CQL R2 adds a MatchesFull function, which is a regex match that is required to match the entire string, as opposed to the Matches operation which by default uses partial matching.
define MatchesFullFalse: 'http://fhir.org/guides/cqf/common/Library/FHIR-ModelInfo|4.0.1'.matchesFull('Library') // returns false
define MatchesFullAlsoFalse: 'N8000123123'.matchesFull('N[0-9]{8}') // returns false as the string is not an 8 char number (it has 10)
define MatchesFullTrue: 'N8000123123'.matchesFull('N[0-9]{10}') // returns true as the string has an 10 number sequence in it starting with `N`
See MatchesFull
CQL R2 adds a Slice function that is a generalization of the Take, Skip, and Tail functions:
define SliceStart: Slice({ 1, 2, 3, 4, 5 }, 1) // { 2, 3, 4, 5 }
define SliceEnd: Slice({ 1, 2, 3, 4, 5 }, 1, 3) // { 2, 3 }
See Slice
In addition, CQL R2 incorporates updates to FHIRPath R3. In that update, FHIRPath added support for several capabilities and functions that were already defined in CQL. This support was added to FHIRPath with the same semantics as CQL, and now this update to CQL R2 adds FHIRPath mappings for that functionality to ensure that we maintain alignment between the two specifications.
To support more rigorous description of information, warning, and error messages in CQL authoring and execution, CQL R2 introduces a new mechanism for defining message codes within the specification. For a complete description of this capability, see the Messages appendix.
Clinical Quality Language has been published as an HL7 and ANSI Normative standard since December of 2020. The 2.0.0 ballot version introduced several new features that are the result of implementer feedback and author feature requests. In addition, the existing 1.5.3 Normative version of the specification was reaffirmed during the same September 2025 ballot cycle.
Importantly, no breaking changes have been introduced in CQL R2. The following change log provides a detailed listing of the changes that were applied for the ballot publication.