This page is part of the Clinical Quality Language Specification (v2.0.0-ballot: R2 STU 1) based on FHIR (HL7® FHIR® Standard) R4. This version is a pre-release. The current official version is 1.5.3. For a full list of available versions, see the Directory of published versions

CQL Specification

Official URL: http://cql.hl7.org/ImplementationGuide/hl7.cql				Version: 2.0.0-ballot
Active as of 2025-08-09				Computable Name: CQL

Clinical Quality Language (CQL)

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

HL7 Trial-Use Specification

This is a trial-use ballot 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 Clinical Quality Language 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 the Clinical Quality Language 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 Clinical Quality 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 – References

Appendix E – Acronyms

Appendix F – Glossary

Appendix G – Conventions

Appendix H – Timing Interval Calculation Examples

Appendix I – FHIRPath Function Translation

Appendix J – List Of Tables

Appendix K – List Of Figures

Appendix L - CQL Syntax Diagrams

Appendix M - Messages Index

Dependencies

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