STU3 Candidate

This page is part of the FHIR Specification (v1.8.0: STU 3 Draft). The current version which supercedes this version is 5.0.0 . For a full list of available versions, see the Directory of published versions

G.2 Using Expressions

This topic discusses the use of expression logic within FHIR resources using expression languages such as FluentPath and Clinical Quality Language (CQL). The clinical reasoning module defines an approach to representing logic that enables dynamic functionality to be utilized directly within the Clinical Reasoning resources, as well as within FHIR resources more generally using extensions.

G.2.1 Expression Elements

In general, the use of expressions involves the following elements:

  • Description - A natural language description of the logic.
  • Language - The expression language used to represent the logic.
  • Expression - The expression itself in the identified language.

This general pattern is to used to represent expression logic throughout the resources in the Clinical Reasoning module and allows expression logic to be represented at different levels:

  • Unstructured - The logic in this case can be communicated using natural language without the expectation that it is computable. This information is useful for communicating the intended dynamic semantics to environments that do not support computable evaluation.
  • Structured - The logic is specified as a computable expression in a formal language. This information is useful for communicating the logic to environments that are expected to support the computation.
  • Mixed - The logic in this case is communicated using both a natural language description, as well as a computable expression in a formal language. This information is useful for communicating to environments that may support the computation as well as to environments that do not, or to environments that support the computation but desire human-readable information to more easily understand the logic.
G.2.1.1 Description

The description element can be used either alone, to communicate unstructured logic, or together with the other elements to provide a natural language narrative for the formal representation. The element is typically optional to enable usage in both contexts.

G.2.1.2 Expression Language

The language element identifies the expression language used to represent the logic. The Clinical Reasoning module defines support for FluentPath and Clinical Quality Language, but support for other languages can be provided.

The language element is specified using the Media Type of the language. For inline expressions using FluentPath and Clinical Quality Language, the media type SHALL be specified as follows:

  • FluentPath - text/fluentpath
  • Clinical Quality Language - text/cql

For example, the following fragment illustrates the use of CQL to define a dynamicValue as part of an activity definition: 

<dynamicValue>
  <path value="timing.event"/>
  <language value="text/cql"/>
  <expression value="Now()"/>
</dynamicValue>

Note that when extensions are used, each language defines a specific extension, so the content type is implied. For example: 

<event>
  <extension url="http://hl7.org/fhir/StructureDefinition/cqif-basic-cqlExpression">
    <valueString value="Now()"/>
  </extension>
</event>
G.2.1.3 Expression

The expression element specifes the formal representation of the expression logic in the identified expression language. The expression may be inline, as in the above examples, or it may be a reference to a named expression defined in a logic library. For example, the following fragment illustrates the use of a named expression to define a dynamicValue as part of an activity definition: 

<dynamicValue>
  <path value="reasonCode"/>
  <expression value="RiskAssessmentScore"/>
</dynamicValue>

The example specifies that the reasonCode element should be set to the result of evaluating the RiskAssessmentScore expression. This expression is expected to be present in a Library referenced by the containing resource: 

<library>
  <reference value="Library/mmi-suiciderisk-orderset-logic"/>
</library>

If the containing resource has a library element (such as ActivityDefinition and PlanDefinition), and only specifies a single library, the expression is evaluated as though it is in scope in that library. However, if the resource references multiple libraries, the referenced expression must be qualified with the name of the library in order to ensure unambiguous resolution.

For resources that do not have a library element, the library extension can be used to reference a library from any resource.

For simplicity, resources that use logic libraries SHOULD reference at most one library to avoid the need to qualify expression references.

G.2.2 Evaluation Context

In general, when an expression is evaluated, it is evaluated in the context of the containing resource. This means that the resource is available within the expression so that the current values of the resource can be accessed.

Note that this is the general case for establishing the evaluation context for expressions. Many of the clinical reasoning resources, such as the Measure, will define specific behavior for the evaluation context that overrides this general behavior.

For FluentPath expressions, the expression is evaluated with the containing resource as the context.

For CQL expressions, an implicit Context parameter is defined that allows the expression access to the containing resource.

G.2.2.1 Parameters

In addition to the evaluation context, the expression may access parameters defined by referenced libraries. As with expression identifier resolution, the name of a parameter can be used directly so long as there is only one library referenced by the resource. Otherwise, the name of the library must be used to qualify the parameter name to avoid ambiguity.

If the expression uses parameters, a Library SHALL be used to define the required parameters.

G.2.2.2 Data Requirements

The data requirements for a given expression describe the minimum data required in order to achieve a successful evaluation of the expression. More data may in general be provided, but not less. For example, an expression may reference lab results for hemoglobin A1C tests over the past two years. If a system provides data for the last three years, the expression can still be successfully evaluated, but if a system provides data for only the last year, the expression may produce incorrect results based on the absence of the expected data.

In the scenario that an evaluation service is not colocated with the clinical information, the service has no general way of knowing whether or not a request has fulfilled the stated data requirements for a expression. As such, this is a critical aspect of implementation. The service assumes the stated data requirements will be provided as part of a request, and requesters shall provide at least the data specified by the data requirements when requesting evaluation for an expression.

Within CQL, data requirements can be inferred based on the retrieve expressions used. This process is described in detail in the Clinical Quality Language Specification, but in general, the set of data requirements is represented by elements of the DataRequirement type. This type is similar to a parameter definition, with the following differences:

  • No name element - Because there is no need for a name to inference on the data, there is no need to specify a name for the data required.
  • Code and date filters - The CQL retrieve also allows for data accessed to be filtered by membership in a specific valueset, as well as by date range. The DataRequirement type represents these filters via the codeFilter and dateFilter elements.

For CQL expressions that contain retrieves, a Library SHOULD be used to describe the data requirements. However, the $data-requirements operation can also be used to infer the data requirements based on usage within the expression.

G.2.3 FluentPath

FluentPath is a lightweight path-based navigation language intended to provide simple but flexible access to graph-structured data. It is defined as a general purpose specification available here .

G.2.4 Clinical Quality Language

Clinical Quality Language defines a high-level clinically-oriented syntax to enable formal representation of clinical logic. It is defined as a general purpose specification available here:

HL7 Standard: Clinical Quality Language Specification, Release 1 .

September 2016 Ballot Note: The Clinical Quality Language specification is in the process of being published as Release 1.1. That version of the CQL specification should be used with this content.