# V2.0 Change Log - Clinical Quality Language Specification v2.0.0

* [**Table of Contents**](toc.md)
* [**Changes**](changes.md)
* **V2.0 Change Log**

## V2.0 Change Log

| | |
| :--- | :--- |
| *Page standards status:*[Informative](http://hl7.org/fhir/R4/versions.html#std-process) | [Maturity Level](http://hl7.org/fhir/versions.html#maturity): N/A |

**2.0 Change Log**

### STU Changes (v2.0.0)

#### Change Summary

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](#ballot-changes-v200-ballot).

##### Directives

Directives provide an ability for translator options to be provided as part of the language.

See [Directives](03-developersguide.md#directives)

###### Default Comparison Precision

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](03-developersguide.md#defaultcomparisonprecision)

##### Using Enhancements

CQL R2 introduces several enhancements to data model support.

###### Model Qualifiers

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

```

###### Model Aliases

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](03-developersguide.md#data-models-1)

###### Model Definitions

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](03-developersguide.md#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.

See [Defining Class Types](03-developersguide.md#defining-class-types)

**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 }

```

See [Defining Contexts](03-developersguide.md#defining-contexts)

**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.

See [Defining Conversions](03-developersguide.md#defining-conversions)

##### Parameter Enhancements

###### Parameter Constraints

* [FHIR-48682](https://jira.hl7.org/browse/FHIR-48682) - Added support for parameter constraints

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.

See [Parameter Constraints](03-developersguide.md#parameter-constraints)

###### Parameter Binding

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.

See [Parameter Binding](03-developersguide.md#parameter-binding)

##### Terminology Enhancements

###### Equivalent Contains

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](09-b-cqlreference.md#equivalentcontains), [Contains CodeSystem](09-b-cqlreference.md#equivalentcontains-codesystem), and [In Code System](09-b-cqlreference.md#equivalentin-codesystem)

###### Equivalent In

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](09-b-cqlreference.md#equivalentin), [In CodeSystem](09-b-cqlreference.md#equivalentin-codesystem), and [In ValueSet](09-b-cqlreference.md#equivalentin-valueset)

###### Contains In a Retrieve

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](04-logicalspecification.md#codecomparator)

##### Miscellaneous New Functions

###### Round(Quantity)

CQL R2 adds the ability to round Quantity values:

```
define "QuantityRound": Round(2.54 'cm') // 3 'cm'

```

See [Quantity Round](09-b-cqlreference.md#round)

###### MatchesFull

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](09-b-cqlreference.md#matchesfull)

###### Slice

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](09-b-cqlreference.md#slice)

##### FHIRPath Alignment

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.

See [FHIRPath Translation](16-i-fhirpathtranslation.md)

##### Messages

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](20-m-messages.md) appendix.

#### Change Log

##### Compatible, Substantive

* [FHIR-57620](https://jira.hl7.org/browse/FHIR-57620): Relax library versioning restriction
* [FHIR-55384](https://jira.hl7.org/browse/FHIR-55384): Add a Comparable function
* [FHIR-53532](https://jira.hl7.org/browse/FHIR-53532): Relax error checking for string overload of value set membership operator
* [FHIR-52783](https://jira.hl7.org/browse/FHIR-52783): Conversion grammar doesn't support qualifiers
* [FHIR-52462](https://jira.hl7.org/browse/FHIR-52462): More Clarification Needed on Defining Models
* [FHIR-52443](https://jira.hl7.org/browse/FHIR-52443): Provide guidance on support for arbitrary units
* [FHIR-52044](https://jira.hl7.org/browse/FHIR-52044): Include a repeatAll function
* [FHIR-52040](https://jira.hl7.org/browse/FHIR-52040): Add support for order-preserving combine
* [FHIR-53144](https://jira.hl7.org/browse/FHIR-53144): Clarify expected behavior of a relationship clause
* [FHIR-52485](https://jira.hl7.org/browse/FHIR-52485): Technical Corrections in In (CodeSystem)
* [FHIR-52471](https://jira.hl7.org/browse/FHIR-52471): Typo in EquivalentContains
* [FHIR-52353](https://jira.hl7.org/browse/FHIR-52353): Errors and Formatting Issues in Parameter Defaults Section
* [FHIR-52304](https://jira.hl7.org/browse/FHIR-52304): Spelling and Grammatical Issues
* [FHIR-52258](https://jira.hl7.org/browse/FHIR-52258): Broken link to QUICK model
* [FHIR-52219](https://jira.hl7.org/browse/FHIR-52219): Round example has typo
* [FHIR-52043](https://jira.hl7.org/browse/FHIR-52043): Correct description of Power
* [FHIR-52041](https://jira.hl7.org/browse/FHIR-52041): Clarify remark about unit resulting from multiplication

##### Non-Substantive

* [FHIR-57723](https://jira.hl7.org/browse/FHIR-57723): Correct includes and included in examples
* [FHIR-57721](https://jira.hl7.org/browse/FHIR-57721): Correct properly included in example
* [FHIR-57390](https://jira.hl7.org/browse/FHIR-57390): Correct contradictory description of included in semantics
* [FHIR-57255](https://jira.hl7.org/browse/FHIR-57255): Clarify behavior of Date addition
* [FHIR-56799](https://jira.hl7.org/browse/FHIR-56799): Corrections to timing calculation examples
* [FHIR-56285](https://jira.hl7.org/browse/FHIR-56285): Incorrect additional overload specified for list properly includes
* [FHIR-56137](https://jira.hl7.org/browse/FHIR-56137): Clarify millisecond component is represented in literals as a decimal
* [FHIR-56136](https://jira.hl7.org/browse/FHIR-56136): Clarify relationship to timezone offset policy in FHIRPath
* [FHIR-55657](https://jira.hl7.org/browse/FHIR-55657): Clarify the expected result of type testing on null
* [FHIR-53904](https://jira.hl7.org/browse/FHIR-53904): FHIRPath select mapping does not include all
* [FHIR-53487](https://jira.hl7.org/browse/FHIR-53487): Clarify transitivity of conversion
* [FHIR-53222](https://jira.hl7.org/browse/FHIR-53222): Clarify formatting conventions
* [FHIR-53173](https://jira.hl7.org/browse/FHIR-53173): Comparison of Durations with Months, Days, and Years
* [FHIR-53172](https://jira.hl7.org/browse/FHIR-53172): Comparisons Between Calendar and Definite Duration Quantities
* [FHIR-53152](https://jira.hl7.org/browse/FHIR-53152): Correct timezone offset handling for date extraction
* [FHIR-53148](https://jira.hl7.org/browse/FHIR-53148): Clarify calendar duration conversion semantics
* [FHIR-53145](https://jira.hl7.org/browse/FHIR-53145): Add a best-practice note about the use of precision
* [FHIR-53141](https://jira.hl7.org/browse/FHIR-53141): Clarify result of Ceiling and Floor for overflow/underflow is null
* [FHIR-53044](https://jira.hl7.org/browse/FHIR-53044): Provide a structured representation of capabilities
* [FHIR-52937](https://jira.hl7.org/browse/FHIR-52937): DateTime null behavior is inconsistent
* [FHIR-52880](https://jira.hl7.org/browse/FHIR-52880): Rounding example seems incorrect
* [FHIR-52879](https://jira.hl7.org/browse/FHIR-52879): Typo in directives page
* [FHIR-52782](https://jira.hl7.org/browse/FHIR-52782): Library block should come first
* [FHIR-52780](https://jira.hl7.org/browse/FHIR-52780): Fix related context example
* [FHIR-52565](https://jira.hl7.org/browse/FHIR-52565): A summary of changes from 1.5 to 2.0 would be helpful
* [FHIR-52513](https://jira.hl7.org/browse/FHIR-52513): Clarify value/purpose of equivalent capability
* [FHIR-52512](https://jira.hl7.org/browse/FHIR-52512): Unqualified unique identifier
* [FHIR-52497](https://jira.hl7.org/browse/FHIR-52497): Inconsistency in List Equal Description
* [FHIR-52494](https://jira.hl7.org/browse/FHIR-52494): Appendix M - Messages has visible code comments (?)
* [FHIR-52493](https://jira.hl7.org/browse/FHIR-52493): Change Log does not include Messages
* [FHIR-52491](https://jira.hl7.org/browse/FHIR-52491): Rules for Slice Operation Are Confusing (and not quite right in one case)
* [FHIR-52487](https://jira.hl7.org/browse/FHIR-52487): In (ValueSet) should be EquivalentIn (ValueSet)
* [FHIR-52486](https://jira.hl7.org/browse/FHIR-52486): Contains (ValueSet) should be EquivalentContains (ValueSet)
* [FHIR-52483](https://jira.hl7.org/browse/FHIR-52483): Technical Corrections in Contains (Codesystem)
* [FHIR-52473](https://jira.hl7.org/browse/FHIR-52473): Include Example of EquivalentContains w/ null in list and null on RHS
* [FHIR-52470](https://jira.hl7.org/browse/FHIR-52470): Include Example for Parameter Binding
* [FHIR-52468](https://jira.hl7.org/browse/FHIR-52468): Consider Example for Guarding Against Null in Boolean Expressions
* [FHIR-52461](https://jira.hl7.org/browse/FHIR-52461): Typo in Defining Models
* [FHIR-52460](https://jira.hl7.org/browse/FHIR-52460): Minor Clarification/Guidance Re: Types with Same Name as System Type
* [FHIR-52458](https://jira.hl7.org/browse/FHIR-52458): Show Example of Using Unqualified Model in Data Model Intro
* [FHIR-52456](https://jira.hl7.org/browse/FHIR-52456): Additional Guidance / Warnings for DefaultComparisonPrecision
* [FHIR-52303](https://jira.hl7.org/browse/FHIR-52303): Additional Definitions and Words
* [FHIR-52264](https://jira.hl7.org/browse/FHIR-52264): Extraneous white space
* [FHIR-52262](https://jira.hl7.org/browse/FHIR-52262): Extraneous white space
* [FHIR-52260](https://jira.hl7.org/browse/FHIR-52260): Typo
* [FHIR-52255](https://jira.hl7.org/browse/FHIR-52255): Tools not used
* [FHIR-52250](https://jira.hl7.org/browse/FHIR-52250): What is the intent of the table?
* [FHIR-52243](https://jira.hl7.org/browse/FHIR-52243): Chapter descriptions
* [FHIR-52241](https://jira.hl7.org/browse/FHIR-52241): Inconsistent use of the CQL acronym
* [FHIR-52240](https://jira.hl7.org/browse/FHIR-52240): CQL declaration statements
* [FHIR-52239](https://jira.hl7.org/browse/FHIR-52239): Typo
* [FHIR-52238](https://jira.hl7.org/browse/FHIR-52238): Typo
* [FHIR-52237](https://jira.hl7.org/browse/FHIR-52237): General question about acronyms
* [FHIR-52221](https://jira.hl7.org/browse/FHIR-52221): Add clarifying parameter to match constraints
* [FHIR-52042](https://jira.hl7.org/browse/FHIR-52042): LastPositionOf with an empty string should return the length of the string
* [FHIR-52039](https://jira.hl7.org/browse/FHIR-52039): Return empty or error when doing math with "special units"
* [FHIR-51758](https://jira.hl7.org/browse/FHIR-51758): Add additional string functions from FHIRPath
* [FHIR-49939](https://jira.hl7.org/browse/FHIR-49939): Clarify preferred unit output for operations that convert UCUM units
* [FHIR-49866](https://jira.hl7.org/browse/FHIR-49866): Clarify behavior of interval operators and null boundaries
* [FHIR-44905](https://jira.hl7.org/browse/FHIR-44905): Considerations re precision and uncertainty
* [FHIR-44879](https://jira.hl7.org/browse/FHIR-44879): Clarify that choice types should not be used to create potentially ambiguous overloads
* [FHIR-44597](https://jira.hl7.org/browse/FHIR-44597): Add FHIR-based examples
* [FHIR-39620](https://jira.hl7.org/browse/FHIR-39620): Provide examples of duration offset with before timing phrases
* [FHIR-39184](https://jira.hl7.org/browse/FHIR-39184): Improve implicit conversions to quantity values
* [FHIR-35916](https://jira.hl7.org/browse/FHIR-35916): Add a best-practice that alias names should not be re-used in peer scopes

### Ballot Changes (v.2.0.0-ballot)

#### Change Summary

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.

#### Change Log

##### Compatible, Substantive

* [FHIR-31019](https://jira.hl7.org/browse/FHIR-31019): Support qualified identifiers for model specifiers
* [FHIR-31392](https://jira.hl7.org/browse/FHIR-31392): Support contains as a terminology comparator
* [FHIR-31397](https://jira.hl7.org/browse/FHIR-31397): Multi-filter support in Retrieve
* [FHIR-31675](https://jira.hl7.org/browse/FHIR-31675): Add terminological overloads for contains
* [FHIR-33126](https://jira.hl7.org/browse/FHIR-33126): Provide the ability to specify parameter binding in includes
* [FHIR-33247](https://jira.hl7.org/browse/FHIR-33247): Consider specific operators for equivalent membership
* [FHIR-34014](https://jira.hl7.org/browse/FHIR-34014): Ability to define named tuple types
* [FHIR-37827](https://jira.hl7.org/browse/FHIR-37827): Allow tags without a value
* [FHIR-40612](https://jira.hl7.org/browse/FHIR-40612): Would like Tail and Head functions with parameter
* [FHIR-41326](https://jira.hl7.org/browse/FHIR-41326): Provide a "default comparison precision"
* [FHIR-44827](https://jira.hl7.org/browse/FHIR-44827): Add FHIRPath mapping for defineVariable
* [FHIR-44828](https://jira.hl7.org/browse/FHIR-44828): Add FHIRPath mapping for date/time extractors
* [FHIR-44829](https://jira.hl7.org/browse/FHIR-44829): Add FHIRPath mapping for precision/boundary functions
* [FHIR-48682](https://jira.hl7.org/browse/FHIR-48682): Consider parameter constraints
* [FHIR-48760](https://jira.hl7.org/browse/FHIR-48760): Declare model artifacts in CQL itself instead of XML files
* [FHIR-48762](https://jira.hl7.org/browse/FHIR-48762): Add the ability to alias a model declaration
* [FHIR-48809](https://jira.hl7.org/browse/FHIR-48809): Add FHIRPath mapping for additional string functions
* [FHIR-50456](https://jira.hl7.org/browse/FHIR-50456): Support matchesFull
* [FHIR-51030](https://jira.hl7.org/browse/FHIR-51030): Round should be supported for Quantity types

##### Non-Substantive

* [FHIR-31398](https://jira.hl7.org/browse/FHIR-31398): Expand informative modelInfo description
* [FHIR-39612](https://jira.hl7.org/browse/FHIR-39612): Allow for concepts with no codes
* [FHIR-41169](https://jira.hl7.org/browse/FHIR-41169): Incorrect results from "CumulativeDuration" function in the documentation
* [FHIR-41731](https://jira.hl7.org/browse/FHIR-41731): Clarify compile-time vs run-time terms
* [FHIR-42731](https://jira.hl7.org/browse/FHIR-42731): Conditional branches should be of the same type
* [FHIR-44599](https://jira.hl7.org/browse/FHIR-44599): Enhance support for FHIR references
* [FHIR-44825](https://jira.hl7.org/browse/FHIR-44825): Clarify ToString behavior with quantity
* [FHIR-44910](https://jira.hl7.org/browse/FHIR-44910): Remove underscores in library name examples
* [FHIR-44922](https://jira.hl7.org/browse/FHIR-44922): Deprecate the NotEqual node
* [FHIR-46281](https://jira.hl7.org/browse/FHIR-46281): Clarify LowBoundary/HighBoundary semantics
* [FHIR-46817](https://jira.hl7.org/browse/FHIR-46817): Correct examples of lowBoundary and highBoundary functions
* [FHIR-48534](https://jira.hl7.org/browse/FHIR-48534): Change tests.zip to link to github tests
* [FHIR-48818](https://jira.hl7.org/browse/FHIR-48818): Document initial case
* [FHIR-48867](https://jira.hl7.org/browse/FHIR-48867): Clarify when seconds and milliseconds should be combined in comparisons and calculations
* [FHIR-49652](https://jira.hl7.org/browse/FHIR-49652): Reference to is QDM unhelpful
* [FHIR-49684](https://jira.hl7.org/browse/FHIR-49684): Date/time arithmetic - subtraction < 0
* [FHIR-51412](https://jira.hl7.org/browse/FHIR-51412): Divide by zero example is incorrect
* [FHIR-50198](https://jira.hl7.org/browse/FHIR-50198): Correction to disambiguate %context parameter from context definition
* [FHIR-50455](https://jira.hl7.org/browse/FHIR-50455): Error in matches example
* [FHIR-50938](https://jira.hl7.org/browse/FHIR-50938): Clarify successor/predecessor should be precision-aware for decimals

