Clinical Quality Language Specification
2.0.0 - R2 STU 1

Clinical Quality Language Specification - Downloaded Version 2.0.0 See the Directory of published versions

## CQL Specification

Official URL: http://cql.hl7.org/ImplementationGuide/hl7.cql | Version: 2.0.0
Active as of 2026-07-29 | Computable Name: CQL
Other Identifiers: OID:2.16.840.1.113883.4.642.40.71

### Clinical Quality Language (CQL)

HL7 Standard: Clinical Quality Language Specification, Release 2 Trial-Use Publication (CQL 2.0.0)

HL7 Trial-Use Specification

> This is a trial-use publication of the CQL specification that introduces substantive new features, numerous corrections, clarifications, and enhancements, and no breaking changes. Normative elements of the specification remain normative from a maturity perspective (i.e. normative aspects of the specification will not change in backwards-incompatible ways). New content introduced in this trial-use are marked as such, and trial-use content that was introduced in 1.5 remains trial-use in this version.

Clinical Quality Language (CQL) is a high-level, domain-specific language focused on clinical quality and targeted at measure and decision support artifact authors.

In addition, this specification describes a machine-readable canonical representation called Expression Logical Model (ELM) targeted at implementations and designed to enable sharing of clinical knowledge.

> For a complete description of the changes to this version, please review the version history.

Title Page | License | Version History | Executive Summary

#### Getting Started

Welcome to the HL7 Clinical Quality Language (CQL) specification!

CQL has matured into a capable and flexible specification for representing clinically-focused logic, and is being used in a broad variety of applications from cohort definition and quality measurement, to clinical decision and cognitive support, computable guidelines, and public health reporting. See the Examples page for examples of these various usages, and be sure to visit the Reference Implementations page for a description of the available tooling and resources, as well as a link to community projects.

To join the active and growing community of CQL authors and implementers, subscribe to the CQL stream on the FHIR Zulip. As with any HL7 specification, we welcome continued feedback and are constantly striving to improve. If you have comments or suggestions, or even just notice a typo, please let us know by submitting an issue via the HL7 JIRA, just set the "Project" to FHIR and the "Specification" to "Clinical Quality Language" in the issue you submit.

#### Organization of this Specification

The organization of this specification follows the outline of the perspectives discussed in the Approach section—conceptual, logical, and physical. Below is a listing of the chapters with a short summary of the content of each.

Chapter 1 – Introduction provides introductory and background material for the specification.

Chapter 2 – Author’s Guide provides a high-level discussion of the CQL syntax. This discussion is a self-contained introduction to the language targeted at clinical quality authors.

Chapter 3 – Developer’s Guide provides a more in-depth look at CQL targeted at developers familiar with typical development languages such as Java, C#, and SQL.

Chapter 4 – Logical Specification provides a complete description of the elements that can be used to represent quality logic. Note that Chapters 2 and 3 describe the same functional capabilities of the language, and that anything that can be expressed in one mechanism can be equivalently expressed in the other.

Chapter 5 – Language Semantics describes the intended semantics of the language, covering topics such as data layer integration and expected run-time behavior.

Chapter 6 – Translation Semantics describes the mapping between CQL and ELM, as well as outlines for how to perform translation from CQL to ELM, and vice versa.

Chapter 7 – Physical Representation is reference documentation for the XML schema used to persist ELM.

Appendix A – CQL Syntax Formal Specification discusses the ANTLR4 grammar for the language.

Appendix B – CQL Reference provides a complete reference for the types and operators available in CQL, and is intended to be used by authors and developers alike.

Appendix C – Reference Implementations provides information about where to find reference implementations for a CQL-ELM translator, a CQL Execution Framework for JavaScript, and other related tooling.

Appendix D – Listing of references used throughout the specification

Appendix E – Definitions of acronyms used throughout the specification

Appendix F – Glossary of terms

Appendix G – Formatting Conventions and Best Practices for authoring readable and maintainable CQL

Appendix H – Timing Interval Calculation Examples

Appendix I – FHIRPath Function Translation mapping from FHIRPath function names to CQL expressions

Appendix J – List Of Tables

Appendix K – List Of Figures

Appendix L - CQL Syntax Diagrams providing a visual illustration of CQL grammar rules

Appendix M - An index of all the messages defined in the specification

#### Dependencies

IG | Package | FHIR | Comment
--- | --- | --- | ---
Clinical Quality Language Specification | hl7.cql#2.0.0 | R4 |
HL7 Terminology (THO) | hl7.terminology.r4#7.3.0 | R4 | Automatically added as a dependency - all IGs depend on HL7 Terminology
FHIR Extensions Pack | hl7.fhir.uv.extensions.r4#5.3.0 | R4 | Automatically added as a dependency - all IGs depend on the HL7 Extension Pack
FHIR Tooling Extensions IG | hl7.fhir.uv.tools.r4#1.1.2 | R4 | for example references

#### Cross Version Analysis

This is an R4 IG. None of the features it uses are changed in R4B, so it can be used as is with R4B systems. Packages for both R4 (hl7.cql.r4) and R4B (hl7.cql.r4b) are available.

#### Global Profiles

There are no Global profiles defined