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

Usage

To use these libraries in your implementation guide, include a reference to this implementation guide as an implementation guide dependency. If your implementation guide is specified as an XML resource:

<dependsOn id="cql-us">
  <uri value="http://hl7.org/fhir/us/cql/ImplementationGuide/hl7.fhir.us.cql"/>
  <packageId value="hl7.fhir.us.cql"/>
  <version value="2.0.0"/>
</dependsOn>

If your implementation guide is specified as a JSON resource:

    "dependsOn": [{
      "id": "cql-us",
      "uri": "http://hl7.org/fhir/us/cql/ImplementationGuide/hl7.fhir.us.cql",
      "packageId": "hl7.fhir.us.cql",
      "version": "2.0.0"
    }]

And if your implementation guide is specified using SUSHI, add this to your sushi-config.yaml:

dependencies:
  hl7.fhir.us.cql: 
    id: cql-us
    version: 2.0.0

USCore ModelInfo

Clinical Quality Language (CQL) is a high-level, domain-specific language focused on clinical quality, and it is targeted at measure and decision support artifact authors. Additionally, the CQL specification provides a machine-readable canonical representation called Expression Logical Model (ELM), which is targeted at implementations, and designed to enable automated sharing of clinical knowledge.

To use CQL with USCore, model information must be provided to the implementation environment. The USCore-ModelInfo library provides this information for US Core. To use USCore, include a using declaration as shown in the example below:

using USCore version '6.1.0-derived'

NOTE: The -derived label is used to distinguish this model info from the non-derived model info. See the US Core Model Info page for more information.

Dependencies and Versioning

As with any knowledge artifact, dependencies and versioning are a critical aspect of ensuring correct function, both as part of development and testing, as well as implementation. To ensure version and dependency information is correctly captured, and communicated, best practice is to use a version manifest as part of the development and distribution of knowledge artifacts.

A version manifest is represented as a CRMI Manifest Library (a Library of type asset-collection). It uses relatedArtifact entries to declare both the artifacts that make up the collection (composed-of, marked owned) and the specific versions of every dependency those artifacts rely on (depends-on). Terminology (code system) versions are additionally pinned through the expansion parameters referenced by the manifest, so that value set expansions performed during evaluation resolve to the same codes every time.

Prior Authorization Version Manifest Example

The Prior Authorization Example Version Manifest is a complete example that declares the exact dependency versions used by the prior-authorization example questionnaires in this implementation guide. Downstream implementation guides that reuse these questionnaires (for example, a Da Vinci DTR-based application) can adapt this manifest to declare their own dependency versions.

The example illustrates how each kind of dependency and governance detail is captured:

Because the manifest pins versions rather than relying on "latest", packaging and evaluating the questionnaires against the versions it declares produces reproducible results. When adapting the manifest for a specific deployment, update each pinned version to the version approved for that deployment, and re-review the manifest on the cadence documented within it.