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:
<repository>
<id>sonatype-public</id>
<name>Sonatype Public</name>
<url>https://oss.sonatype.org/content/groups/public/</url>
</repository>
The cql, model, elm, and cql-to-elm packages are required to use the translator:
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>cql</artifactId>
<version>1.3.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>model</artifactId>
<version>1.3.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>elm</artifactId>
<version>1.3.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>cql-to-elm</artifactId>
<version>1.3.0-SNAPSHOT</version>
</dependency>
In addition, to use the translator with QDM, FHIR, and QUICK, the model info packages must be included:
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>quick</artifactId>
<version>1.3.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>qdm</artifactId>
<version>1.3.0-SNAPSHOT</version>
</dependency>
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.
The CQL-to-ELM Translator supports all language constructs of the latest version of CQL (Release 1 STU 3 (1.3)), 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.
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 |