Skip to content
Switch branches/tags
Go to file
3 contributors

Users who have contributed to this file

@brynrhodes @tangiblezero @JPercival

CQL-to-ELM Translator Reference Implementation

The HL7 CQL specification defines both a high-level, author friendly syntax for expressing clinical knowledge, as well as a machine friendly, syntax-independent canonical representation of clinical knowledge called Expression Logical Model (ELM). The high level syntax is designed to support measure and decision support authors, while the canonical representation is designed to support point-to-point sharing and machine processing applications.

The specification describes a formal mechanism for translating the high-level CQL syntax into the canonical ELM representation. This project provides a reference implementation of that translation. The translation component is designed to support use within an Integrated Development Environment (IDE), and has several options and features focused on providing translation support in such an environment. The reference implementation is intended to be used in support of CQF implementations as a tool to enable CQL output to be uniformly and automatically translated into ELM XML or JSON documents for sharing and distribution to support implementation, integration, translation, and execution of CQL-based artifacts.

The CQL-to-ELM Translator is licensed under the open source Apache Version 2.0 license, and releases are made available via the Sonatype Maven repository:

  <name>Sonatype Public</name>

The cql, model, elm, and cql-to-elm packages are required to use the translator:


In addition, to use the translator with QDM, FHIR, and QUICK, the model info packages must be included:



CQL is defined using an ANTLR4 grammar. ANTLR4 is a simple language for describing language grammars and automatically generating the lexical analysis and parsing components for the resulting grammar. The CQL-to-ELM translator uses the visitor classes generated by ANTLR4 to perform the translation processing.

Current Status

The CQL-to-ELM Translator supports all normative language constructs of the latest version of CQL (Release 1 (1.5)), the trial-use functionality of the 1.5 specification, as well as a broad range of functionality to support use of the translator in an Integrated Development Environment. Implementations making use of the translator can submit issues and track resolution progress through the Issues tracker in the Github repository.


1.5 Maintenance

  • Enhanced model info to support advanced authoring capabilities
  • Improved profile-informed model info to support logical content authoring
  • Improved data-requirements inference capabilities
  • Improve retrieve filtering
  • Choice function invocation (if multiple overloads of a method support the different types of a choice, the return value is a choice of the results of the function invocation)
  • Inferred expression support for case features.
  • Multi-filter data-requirements

See the 1.5 Maintenance milestone for details.


The CQL-to-ELM Translator is designed as a component that can be incorporated in integrated development environments. However, it also supports command-line usage, with the following options available:

Option Values Description
input File|Path The name of the input file or directory (REQUIRED). If a directory is given, all files ending in .cql will be processed
model File The name of an input file containing the model info to use for translation. Model info can also be provided through an implementation of the ModelInfoProvider interface
output File The name of the output file or directory. If no output is given, an output file name is constructed based on the input name and target format
format XML (default)|JSON|COFFEE The target format for the output
verify Indicates that the translator should only verify the input, not create output
date-range-optimization Indicates that the translator should perform date range optimization of retrieves where possible
annotations Indicates that the translator should produce source code annotations as part of the output
locators Indicates that the translator should include source code locators within output ELM
result-types Indicates that the translator should include result types in the output ELM
signatures None (default)|Differing|Overloads|All Indicates whether signatures should be included for invocations in the output ELM. Differing will include invocation signatures that differ from the declared signature. Overloads will include declaration signatures when the operator or function has more than one overload with the same number of arguments as the invocation
detailed-errors Indicates that the translator should produce detailed errors
error-level Info (default)|Warning|Error Indicates the minimum severity message that will be reported. If no error-level is specified, all messages will be output
disable-list-traversal Disables traversal of paths on list-valued expressions
disable-list-demotion Disables demotion of list-valued expressions to singletons
disable-list-promotion Disables promotion of singletons to list-valued expressions
enable-interval-demotion Enables demotion of interval-valued expressions to points
enable-interval-promotion Enables promotion of point-valued expressions to intervals
disable-method-invocation Disables method-style invocation support
require-from-keyword Indicates that all queries will be required to start with a from keyword
strict A combination option that is equivalent to specifying all of disable-list-traversal, disable-list-demotion, disable-list-promotion, disable-interval-demotion, disable-interval-promotion, and disable-method-invocation
debug A combination option that is equivalent to specifying all of annotations, locators, and result-types
validate-units Indicates that the translator should validate UCUM units in quantity literals
stdout Indicates that the translator should write output to the console instead of a file