Using CQL with FHIR, published by HL7 International / Clinical Decision Support. This guide is not an authorized publication; it is the continuous build for version 2.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/cql-ig/ and changes regularly. See the Directory of published versions

Using ELM

This topic specifies conformance requirements for the use of Expression Logical Model (ELM) content as part of FHIR Knowledge Artifacts.

Translation to ELM

Tooling exists to support translation of CQL to ELM for distribution in XML or JSON formats. These distributions can be included with knowledge artifacts to facilitate implementation. The existing translator tooling applies to both measure and decision support development, and has several options available to make use of different data models in different environments.

Conformance Requirement 5.1 (ELM Libraries):

1. Compiled ELM MAY be distributed either independently, or in combination with the source CQL
2. Libraries that include ELM SHALL conform to either the ELMJSONLibrary or ELMXMLLibrary (or both)
3. Compiled ELM SHALL be logically equivalent to the source CQL

Conformance Requirement 5.2 (Recommended Translator Options):

For knowledge artifact development with FHIR, the following options are recommended:

Specifying Translator Options

The FHIR specification defines the cqlOptions extension to support defining the expected translator options used with a given Library, or set of Libraries. When this extension is not used, the recommended options above SHOULD be used. When this extension is present on a Library, it SHALL be used to provide options to the translator when translating CQL for that library. When this extension is present in an asset collection or implementation guide, it SHALL be used to provide options to the translator unless the options are provided directly by the library.

Conformance Requirement 5.3 (Specifying Translator Options):

1. Translator options SHOULD be provided in either a CQLLibrary or an ELMLibrary
2. Translator options specified in a Library take precedence over options defined in an asset collection or implementation guide
3. If no translator options are provided, the recommended options above SHOULD be used
4. If translator options are provided in a CQLLibrary or ELMLibrary, the options SHALL be consistent with the translator options reported by the ELM content

The cqlOptions extension references a contained Parameters resource that contains a parameter for each option specified, as well as a translatorVersion parameter that indicates the version of the translator used to produce the ELM. For example:

{
  "resourceType": "Library",
  "id": "FHIRCommon",
  "meta": {
    "profile": [ "http://hl7.org/fhir/uv/cql/StructureDefinition/cql-library" ]
  },
  "contained": [ {
    "resourceType": "Parameters",
    "id": "options",
    "parameter": [ {
      "name": "translatorVersion",
      "valueString": "2.9.0-SNAPSHOT"
    }, {
      "name": "option",
      "valueString": "EnableAnnotations"
    }, {
      "name": "option",
      "valueString": "EnableLocators"
    }, {
      "name": "option",
      "valueString": "DisableListDemotion"
    }, {
      "name": "option",
      "valueString": "DisableListPromotion"
    }, {
      "name": "format",
      "valueString": "XML"
    }, {
      "name": "format",
      "valueString": "JSON"
    }, {
      "name": "analyzeDataRequirements",
      "valueBoolean": true
    }, {
      "name": "collapseDataRequirements",
      "valueBoolean": true
    }, {
      "name": "compatibilityLevel",
      "valueString": "1.5"
    }, {
      "name": "enableCqlOnly",
      "valueBoolean": false
    }, {
      "name": "errorLevel",
      "valueString": "Info"
    }, {
      "name": "signatureLevel",
      "valueString": "Overloads"
    }, {
      "name": "validateUnits",
      "valueBoolean": true
    }, {
      "name": "verifyOnly",
      "valueBoolean": false
    } ]
  } ],
  "extension": [ {
    "url": "http://hl7.org/fhir/StructureDefinition/cqf-cqlOptions",
    "valueReference": {
      "reference": "#options"
    }
  } ],
  "url": "http://ecqi.healthit.gov/ecqms/Library/FHIRCommon",
  "version": "4.1.000",
  "name": "FHIRCommon",
  ...
}

ELM Suitability

Because certain translator options impact language features and functionality, translated ELM may not be suitable for use in all contexts if the options used to produce the ELM are inconsistent with the options in use in the evaluating environment. To determine suitability of ELM for use in a given environment, the following guidance SHALL be followed:

Conformance Requirement 5.4 (ELM Suitability):

1. If the library has function overloads (i.e. function definitions with the same name and different argument lists), the ELM SHALL have been translated with a SignatureLevel of Overloads or All
2. If the evaluation environment or the ELM translator options have a compatibility level set, the compatibility level of the environment SHALL be consistent with the compatibility level used to produce the ELM
3. If the ELM has a compatibility level set, it SHALL be consistent with the version of the translator used in the evaluation environment
4. The translator version used to produce the ELM SHOULD be consistent with the translator version used in the evaluation environment
5. The translator options used in the evaluation environment SHALL be consistent with the translator options used to produce the ELM for at least the following options:
   • DisableListTraversal
   • DisableListDemotion
   • DisableListPromotion
   • EnableIntervalDemotion
   • EnableIntervalPromotion
   • DisableMethodInvocation
   • RequireFromKeyword
   • SignatureLevel
6. For authoring environments, the following additional translator options MAY be used to determine suitability of available ELM:
   • EnableAnnotations
   • EnableLocators
   • EnableResultTypes