Using CQL With FHIR
3.0.0-ballot - STU 3 Ballot

Using CQL With FHIR - Downloaded Version null See the Directory of published versions

## Using ModelInfo

Page standards status: Trial-use | Highlight text changes?

This topic specifies conformance requirements for the use of Model Information as part of FHIR Knowledge Artifacts that make use of Clinical Quality Language (CQL).

### ModelInfo

To use CQL with FHIR, model information (ModelInfo) must be provided to the implementation environment. To create this ModelInfo FHIR StructureDefinition resources can be processed according to the following rules:

1. For each StructureDefinition, if the kind is `primitive-type`, `complex-type` (except for types based on Extension), or `resource` (with no derivation or a derivation of `specialization`), a ClassInfo with the same name as the structure definition is created
   1. For each element:
      1. If the element is not a backbone element, a corresponding element with the name and type is added to the ClassInfo. If the maximum cardinality of the element is not "1", the element is created as a list type.
      2. If the element is a backbone element, a new ClassInfo is created with the child elements of the backbone element and a new element is added to the containing ClassInfo with the type of the ClassInfo. Note that this process is recursive and so may result in multiple levels of nested class creation. As such the name of the ClassInfo must include the name of all the parent classes as qualifiers in order to ensure uniqueness. This approach also supports the ability of FHIR elements to reference other element definitions, though a post-processing fixup step is typically needed to resolve these references.

If this process is run against the StructureDefinitions from the base FHIR specification, it produces a complete representation of all the FHIR Resources as classes in the ModelInfo. However, because FHIR primitive types actually have elements (e.g. `value`, `id`, and `extension`), this process produces classes in the ModelInfo for each of the FHIR primitive types, and only the `value` elements of these FHIR primitives are typed with the actual CQL primitive types. This means that to access the actual values of FHIR elements for comparison against CQL primitive values, the `.value` path must be used:

    Patient.gender.value = 'female'

To facilitate comparison by authors, these primitives can be implicitly converted to CQL primitive types, and the FHIRHelpers library (generated alongside the FHIR-ModelInfo) defines these implicit conversions.

To make use of these implicit conversions within a CQL library, include the FHIRHelpers library:

    include hl7.fhir.uv.cql.FHIRHelpers version '4.0.1'

> NOTE: Previous versions of the FHIRHelpers library were included A) as embedded resources in the CQL-to-ELM translator (referenced without a namespace and the version `4.0.1`), as well as B) in the CQFramework Common implementation guide (referenced with the namespace `fhir.cqf.common` and the version `4.0.1`). In both these cases, the content is the same as what is now published in this implementation guide, with the namespace `hl7.fhir.uv.cql` and the version `4.0.1`. Note that the version here is explicitly aligned with the FHIR specification version, because the FHIRHelpers library is generated as part of the process of constructing the model information and so is cohesively tied to the FHIR specification version.

#### ModelInfo Libraries

Similar to CQL content, ModelInfo can be included in FHIR Library resources to facilitate distribution.

Conformance Requirement 6.1 (ModelInfo Libraries):

1. Libraries used to package ModelInfo SHALL conform to the CQLModelInfo profile
2. The identifying elements of a modelinfo SHALL conform to the following requirements:
   - Library.url SHALL be `<CQL model namespace url>/Library/<CQL model name>-ModelInfo`
   - Library.name SHALL be `<CQL model name>`
   - Library.version SHALL be `<CQL model version>`
3. For model info libraries included in FHIR implementation guides, the CQL model namespace is defined by the implementation guide as follows:
   - CQL model namespace name SHALL be IG.packageId of the implementation guide being described by the model info
   - CQL model namespace url SHALL be IG.canonicalBase of the implementation guide being described by the model info
4. To avoid issues with characters between web ids and names, CQL model names SHALL NOT have underscores.

The prohibition against underscores in CQL model names is required to ensure compliance with the canonical URL pattern (because URLs by convention should not use underscores). In addition, many publishing environments will use the canonical tail (i.e. the name of the library) as the logical id of the Library resource, which does not allow underscores per the FHIR specification.

This implementation guide includes FHIR-ModelInfo, a ModelInfo for FHIR version 4.0.1.

> NOTE: Previous versions of the FHIR-ModelInfo library were included A) as embedded resources in the CQL-to-ELM translator (referenced without a namespace and the semantic version of the FHIR specification being modeled), as well as B) in the CQFramework Common implementation guide (referenced with the canonical reference `http://fhir.org/guides/cqf/common/Library/FHIR-ModelInfo|4.0.1`). The content of the 4.0.1 version of this ModelInfo is the same as what is now published in this implementation guide, with the canonical reference `http://hl7.org/fhir/uv/cql/Library/FHIR-ModelInfo|4.0.1`. Note the model information version here is explicitly aligned with the FHIR specification version being modeled, not the version of this implementation guide. This is to avoid any confusion about what version of the FHIR model is being used in a given CQL library.

#### Derived ModelInfo

CQL can be used with a FHIR ModelInfo directly, as described above. However, FHIR profiles include a wealth of computable information about the intended structure of the clinical data involved in an exchange, including terminology bindings, constraints, descriptive metadata, slices, and extensions. To facilitate authoring that can easily reference this information, the tooling to construct ModelInfo from the base FHIR StructureDefinitions has been enhanced to support building ModelInfo that is specific to an implementation guide.

There are multiple approaches to generating ModelInfo based on the profiles in an implementation guide. The first of these is Derived ModelInfo, which performs the following step for each profile:

1. Each profile (StructureDefinition with derivation set to `constraint`) results in a new ClassInfo in the ModelInfo, derived from the ClassInfo for the baseDefinition of the profile
   1. `namespace` is set to the `modelName`
   2. `name` is set to the `name` element of the StructureDefinition (without the prefix if the name is prefixed with the modelName)
   3. `baseType` is set to the qualified name of the class corresponding to the `baseDefinition`
   4. `identifier` is set to the canonical `url` of the StructureDefinition
   5. `label` is set to the `title` of the StructureDefinition (unless overridden by the cqf-modelInfo-label extension)
   6. `retrievable` is set to `true` (unless overridden by the cqf-modelInfo-isRetrievable extension)
   7. `primaryCodePath` is set based on the cqf-modelInfo-primaryCodePath extenssion

For example, processing the US Core 7.0.0 implementation guide produces a ModelInfo with a ClassInfo for the EncounterProfile:

    using USCore version '7.0.0'

    ...

    define "Encounters":
      ["EncounterProfile"]

Conceptually, this expression results in any Encounter resource that conforms to the US Core Encounter Profile.

> NOTE: How systems implement the requirement that retrieve expressions only result in resource instances that conform to the requested profile is not prescribed, because there are many different ways this requirement can be achieved. Because profile conformance testing can be expensive, there are performance tradeoffs associated with how this is done in any particular environment.

#### Profile-informed ModelInfo

The second widely used approach to generating ModelInfo based on the profiles in an implementation guide is called Profile-informed Authoring, and takes greater advantage of the information defined in profiles, including slices and extensions. However, it also "flattens" the types produced in the ModelInfo, so that authors are presented with a complete picture of FHIR from the perspective of the particular implementation guide. This approach has some advantages, but it also has the primary disadvantage of preventing reuse of logic across implementation guides, because profiles in each implementation guide result in entirely separate classes in CQL.

This approach has been used for artifacts authored with USCore and QICore versions 6 and below, and is constructed by performing the following steps for each profile:

1. Each profile (StructureDefinition with derivation set to `constraint`) results in a new ClassInfo in the ModelInfo, derived from the ClassInfo for the baseDefinition of the profile
   1. `namespace` is set to the `modelName`
   2. `name` is set to the `name` element of the StructureDefinition
   3. `baseType` is set to the qualified name of the class corresponding to the `type` (as opposed to the `baseDefinition` used for Derived ModelInfo)
   4. `identifier` is set to the canonical `url` of the StructureDefinition
   5. `label` is set to the `title` of the StructureDefinition (unless overridden by the cqf-modelInfo-label extension)
   6. `retrievable` is set to `true` (unless overridden by the cqf-modelInfo-isRetrievable extension)
   7. `primaryCodePath` is set based on the cqf-modelInfo-primaryCodePath extenssion
2. FHIR Primitive types are mapped to CQL types according to the FHIR Type Mapping section.
3. Extensions and slices defined in profiles are represented as first-class elements in the ClassInfo. Specifically, ClassInfo structures are created with elements as defined by the slice or extension definitions.
   1. For slices, a new ClassInfo is created derived from the ClassInfo corresponding to the element being sliced, and named based on the `sliceName` element of the slice definition. An element of this type and named with the `sliceName` is then added to the containing ClassInfo.
   2. For extensions, a new ClassInfo is created derived from the `Extension` ClassInfo and named based on the `name` of the extension definition. An element of this type and named with the extension `sliceName` is then added to the containing ClassInfo.
4. If a terminology-valued element has a `cqf-notDoneValueSet` or `codeOptions` extension defined, the element is typed as a Choice of the terminology-value (CodeableConcept, Coding, or Code) and ValueSet, allowing retrieves to be performed against the ValueSet referenced by the cqf-notDoneValueSet or codeOptions extension

For example, consider the US Core Blood Pressure Profile. This profile has two slices of the `component` element, named `systolic` and `diastolic`. The resulting USCore ModelInfo has classes derived from the `USCore.Observation.Component` class:

      <typeInfo xsi:type="ClassInfo" namespace="USCore" name="Observation.Component.systolic" retrievable="false" baseType="USCore.Observation.Component"/>
      <typeInfo xsi:type="ClassInfo" namespace="USCore" name="Observation.Component.diastolic" retrievable="false" baseType="USCore.Observation.Component"/>

and then elements in the `USCore.BloodPressureProfile` class corresponding to these slices:

      <element name="systolic" elementType="USCore.Observation.Component.systolic"/>
      <element name="diastolic" elementType="USCore.Observation.Component.diastolic"/>

For extensions, consider the US Core Ethnicity Extension. This is a complex extension, and so the constructed ClassInfo has elements for each of the elements defined by the extension:

      <typeInfo xsi:type="ClassInfo" namespace="USCore" name="EthnicityExtension" identifier="http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity" label="US Core Ethnicity Extension" retrievable="false" baseType="USCore.Extension">
          <element name="ombCategory" elementType="System.Code"/>
          <element name="detailed">
              <elementTypeSpecifier xsi:type="ListTypeSpecifier" elementType="System.Code"/>
          </element>
          <element name="text" elementType="System.String"/>
          <element name="url" elementType="System.String"/>
      </typeInfo>

And the `USCore.PatientProfile` class then has an element named `ethnicity` of this type:

      <element name="ethnicity" elementType="USCore.EthnicityExtension"/>

> NOTE: Importantly, with profile-informed modelinfo, each element in the modelinfo includes a `target` mapping that specifies an expansion to be performed by the translator so that access in the ELM is performed directly against the base FHIR resources, rather than requiring engines (and by extension runtime environments) to deal with data in terms of the profile definitions. As a result, the ELM output of CQL libraries using profile-informed authoring is in terms of the base FHIR resources. Note that for implementations that support profile-informed CQL, this means that the result of retrieve expressions must respect the profile stated in the `templateId` element of the retrieve. This is not to say that the FHIR resource must declare profiles to which they conform, only that with profile-informed authoring, there is an expectation that the ELM expects that FHIR resources returned through a retrieve will conform to the stated profiles. How that conformance is guaranteed is left up to implementations.

#### ModelInfo Settings

In addition, to support more fine-grained control over the process of producing ModelInfo from FHIR StructureDefinitions, this implementation guide defines several ModelInfo-related extensions:

- cqf-modelInfo-isIncluded - Determines whether to create a ClassInfo for the profile or extension on which it appears
- cqf-modelInfo-isRetrievable - Determines whether the ClassInfo for the profile on which it appears is marked retrievable (i.e. can appear as the target type of a Retrieve in CQL)
- cqf-modelInfo-label - Specifies an author-friendly title for the ClassInfo (i.e. an alternate name by which the type can be referenced in CQL type specifiers)
- cqf-modelInfo-primaryCodePath - Specifies the primary code path for the ClassInfo produced from the profile on which it appears (i.e. the default path for terminology-valued filters when the type is used in a Retrieve in CQL)
- cqf-modelInfoSettings - Specifies additional settings used to produce the ModelInfo for profiles and extensions defined in the Implementation Guide on which it appears

> NOTE: All the setting information provided by the StructureDefinition extensions (cqf-modelInfo-…) can be provided directly in the cqf-modelInfoSettings Parameters resource to support the case where the StructureDefinition resources being used for generation are already published or otherwise not under the authoring control of the model information author.