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>2.8.0</version>
</dependency>
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>model</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>elm</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>cql-to-elm</artifactId>
<version>2.8.0</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>2.8.0</version>
</dependency>
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>qdm</artifactId>
<version>2.8.0</version>
</dependency>
To use the DataRequirementsProcessor, a component that performs data requirements analysis on ELM, as well as converts those data requirements to FHIR DataRequirement instances and renders the metadata for a CQL Library as a FHIR ModuleDefinition Library, the elm-fhir package must be included:
<dependency>
<groupId>info.cqframework</groupId>
<artifactId>elm-fhir</artifact>
<version>2.8.0</version>
</dependency>
Note that this elm-fhir package includes a dependency on the HAPI FHIR Structures libraries (client-side dependencies) in order to provide FHIR object representation support. This is the only package from the translator that includes a specific dependency on FHIR.
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 normative language constructs of the latest version of CQL (Release 1 (1.5.2)), 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.
The current release of the translator is version 2.8.0, which includes support for QDM 5.6, enhanced model info to support more advanced authoring capabilities, including profile-informed authoring, as well as a new DataRequirementsProcessor to support data requirements inference and analysis and the 5.0.0 model info for QICore (also included in the QICore-ModelInfo library published as part of QICore).
There is a significant backlog of issues currently being worked. The backlog is organized into a Maintenance milestone which has all planned maintenance updates. As new versions are released, items are worked from that maintenance list first. A high level summary of the current maintenance list is:
- 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
- Improved errors and warnings (case-mismatch warning, identifier hiding, soundex mismatch)
See the 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 |
The class CqlTranslatorOptions provides use of cql-options files in directories with the translator. A JSON schema file that documents the class' structure can be found at clinical_quality_language\Src\java\cql-to-elm\src\test\resources\org\cqframework\cql\cql2elm\json.
An instance of the class with default options can be accessed through defaultOptions(), and returns the following translator options:
- EnableAnnotations
- EnableLocators
- DisableListDemotion
- DisableListPromotion
- ErrorSeverity.Info
- SignatureLevel.None
- Format.XML
Several constructors exist allowing user control of specified options, such as:
CqlTranslatorOptions(CqlTranslator.Options... options)CqlTranslatorOptions(CqlTranslatorException.ErrorSeverity errorLevel,
LibraryBuilder.SignatureLevel signatureLevel,
CqlTranslator.Options... options)CqlTranslatorOptions(CqlTranslator.Format format, boolean dateRangeOptimizations,
boolean annotations, boolean locators, boolean resultTypes, boolean verifyOnly,
boolean detailedErrors, CqlTranslatorException.ErrorSeverity errorLevel,
boolean disableListTraversal, boolean disableListDemotion, boolean disableListPromotion,
boolean enableIntervalDemotion, boolean enableIntervalPromotion,
boolean disableMethodInvocation, boolean requireFromKeyword, boolean validateUnits,
LibraryBuilder.SignatureLevel signatureLevel, String compatibilityLevel)toString() has been overridden to provide an easy-to-read breakdown of existing options within an instance of this class.