Clinical
Reasoning
This
page
is
part
of
the
FHIR
Specification
v6.0.0-ballot3:
Release
6
Ballot
(3rd
Draft)
(see
Ballot
Notes
).
The
current
version
is
5.0.0
.
For
a
full
list
Continuous
Integration
Build
of
available
versions,
see
FHIR
(will
be
incorrect/inconsistent
at
times).
See
the
Directory
of
published
versions
|
Responsible
Owner:
Work
Group
Clinical
Decision
Support
|
Standards Status : Trial Use |
This
topic
discusses
the
use
of
expression
logic
within
FHIR
resources
using
expression
languages
such
as
FHIRPath
and
Clinical
Quality
Language
(CQL)
.
The
clinical
reasoning
module
resources
use
the
Expression
datatype
to
represent
logic
that
enables
dynamic
functionality
to
be
utilized
directly
within
the
Clinical
Reasoning
resources,
as
well
as
within
FHIR
resources
more
generally
using
extensions.
In general, the use of expressions involves the following elements:
This general pattern is used to represent expression logic throughout the resources in the Clinical Reasoning module and allows expression logic to be represented at different levels:
For
example,
the
dynamicValue
element
of
the
ActivityDefinition
and
PlanDefinition
resources
contains
an
expression
element
directly.
However,
for
resources
that
do
not
define
these
elements,
the
cqf-expression
extension
can
be
used
to
enable
expression
information
to
be
associated
with
any
FHIR
resource.
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. Note that if both an expression and a description are provided, the expression is considered to override the description element, although the description should reflect the semantics of the expression as accurately as possible.
<dynamicValue>
<path value="timing.event"/>
<expression>
<description value="Now"/>
</expression>
</dynamicValue>
The language element identifies the expression language used to represent the logic. The ExpressionLanguage value set defines support for FHIRPath, Clinical Quality Language, and FHIR Query (FHIR's RESTful query syntax), but support for other languages can also be provided.
The language element is specified using the Media Type of the language. For inline expressions using FHIRPath and Clinical Quality Language, the media type SHALL be specified as follows:
text/fhirpath
text/x-fhir-query
text/cql
text/cql-identifier
text/cql-expression
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"/>
<expression>
<language value="text/cql-expression"/>
<expression value="Now()"/>
</expression>
</dynamicValue>
Note that when extensions are used, the same Expression structure is used for the extension. For example:
<event>
<extension url="http://hl7.org/fhir/StructureDefinition/cqf-expression">
<valueExpression>
<language value="text/cql-expression"/>
<expression value="Now()"/>
</valueExpression>
</extension>
</event>
Note
that
for
backwards
compatibility
with
implementations
that
were
built
prior
to
the
introduction
of
text/cql-identifier
and
text/cql-expression
,
systems
MAY
treat
expressions
with
text/cql
as
though
they
had
specified
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>
<language value="text/cql-identifier"/>
<expression value="RiskAssessmentScore"/>
</expression>
</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
value="http://hl7.org/fhir/Library/mmi-suiciderisk-orderset-logic"/>
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
example,
the
following
fragment
illustrates
multiple
libraries
being
referenced
by
the
containing
resource:
<library value="http://hl7.org/fhir/Library/mmi-suiciderisk-orderset-logic"/>
<library value="http://hl7.org/fhir/Library/another-orderset-logic"/>
The following fragment illustrates how an expression reference (reasonCode) would be qualified in the case of multiple library references:
<dynamicValue>
<path value="reasonCode"/>
<expression>
<language value="text/cql"/>
<expression value=""mmi-suiciderisk-orderset-logic".RiskAssessmentScore"/>
</expression>
</dynamicValue>
Note
the
use
of
the
"
escape
sequence
on
the
library
scope.
This
escape
sequence
is
needed
for
XML
attributes
delimited
with
double
quotes
to
avoid
premature
closure
of
the
attribute,
which
would
result
in
malformed
XML.
The
following
is
an
example
of
how
to
escape
double
quotes
in
JSON:
"dynamicValue": [
"path": "reasonCode",
"expression": {
"language": "text/cql",
"expression": "\"mmi-suiciderisk-orderset-logic\".RiskAssessmentScore"
}
]
For
resources
that
do
not
have
a
library
element,
the
library
extension
can
be
used
to
reference
a
library
from
any
resource.
The
library
extension
enables
a
resource
to
add
a
reference
to
a
library
when
it
could
not
otherwise.
For simplicity, resources that use logic libraries SHOULD reference at most one library to avoid the need to qualify expression references. Take, for example, the case of updating a library reference in a resource. If the resource has multiple library references, then every expression qualifier that referred to the previous library must be updated. However, if the libraries were combined into a single reference, then only the reference would need to be updated.
When
CQL
expressions
are
identifier
(i.e.,
using
an
Expression
element
with
a
language
of
text/cql-identifier
),
if
the
expression
element
has
a
reference
,
the
identifier
SHALL
be
to
an
expression
in
the
referenced
library.
When
CQL
expressions
are
included
in-line
(i.e.,
with
a
language
specifier
of
text/cql-expression
),
then
that
expression
SHALL
have
access
to
any
libraries
referenced
by
the
resource
(with
either
a
library
element
or
the
cqf-library
extension).
This
means
that
in-line
expressions
may
reference
declarations
in
those
libraries
by
using
the
name
of
the
library
as
a
qualifier.
For example, given a PlanDefinition with a library element referencing the Example library in this IG, the following CQL in-line expression is valid:
exists
(Example."Flexible
Sigmoidoscopy
Performed")
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.
For
FHIRPath
expressions,
the
expression
is
evaluated
with
the
containing
resource
using
the
%context
environment
variable.
For
example,
when
evaluated
against
a
Patient
resource,
the
following
expression
will
return
all
given
elements
of
all
name
elements
for
the
patient:
%context.name.given
And because FHIRPath expressions can be used within CQL, the same approach works for accessing the context in a CQL expression.
Knowledge
artifacts
with
a
subject
element,
such
as
Measure,
establish
the
evaluation
context
based
on
that
subject.
For
example,
when
the
subject
is
Patient
,
the
expression
is
evaluated
in
the
context
of
a
patient,
passed
in
as
an
argument
to
the
operation
performing
the
evaluation.
For
example,
the
Measure/$evaluate
operation
takes
a
subject
parameter
that
establishes
the
subject
context
for
the
evaluation.
In
CQL,
this
corresponds
to
the
context
for
the
expression.
Note that subject at the root of Measure is being deprecated because it is more flexible to provide it on each group. If group.subject is not present then the CQL context is 'unfiltered'.
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.
Note
that
the
way
that
parameters
are
bound
to
the
expression
from
the
evaluation
context
varies
based
on
where
the
evaluation
is
taking
place,
but
in
general,
the
parameters
are
bound
by
name
to
the
parameters
defined
in
the
evaluation
operation.
For
example,
in
the
$apply
operation,
parameters
defined
by
libraries
can
be
provided
as
named
parameters
in
the
operation
invocation.
For
more
details
on
how
parameter
binding
occurs
within
each
context,
refer
to
the
specific
documentation
for
the
$apply
,
$evaluate
,
and
$evaluate-measure
operations.
To encourage consistency and facilitate usage, operations SHOULD make any parameters to the operation available as context variables accessible in the evaluation context for any expressions evaluated as part of operation processing.
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 laboratory test 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 an 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:
codeFilter
and
dateFilter
elements.
mustSupport
element.
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.
The
mapping
from
FHIR
Quantity
to
CQL
System.Quantity
can
only
be
applied
if
the
FHIR
Quantity
has
a
UCUM
code,
i.e.
i.e.,
a
system
of
http://unitsofmeausure.org
and
a
code
is
present.
As
part
of
the
mapping,
time-valued
UCUM
units
are
mapped
to
the
calendar
duration
units
defined
in
FHIRPath
and
CQL,
according
to
the
following
map:
| UCUM unit | Calendar Unit |
|---|---|
| a | year |
| mo | month |
| d | day |
| h | hour |
| min | minute |
| s | second |
| ms | millisecond |
For
example,
the
FHIR
Quantity
1
'a'
would
be
implicitly
converted
to
the
CQL
System.Quantity
1
year
.
FHIRPath
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
.
FHIRPath is used throughout the FHIR specification whenever path selection is needed, such as in the definition of search parameters, or when describing invariants as part of the definition of resources and profiles. FHIRPath expressions generally provide a simple and effective means of navigating and accessing the elements of FHIR resources to retrieve data.
Despite the name, FHIRPath is published as an independent specification from FHIR, allowing it to be used with any graph-structured data, not just FHIR. For more information on using FHIRPath with the FHIR specification, refer to the FHIRPath topic.
Clinical
Quality
Language
(CQL)
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
.
CQL is used to describe the logic used by knowledge artifacts such as clinical decision support rules, quality measure logic, and conditions and actions within order sets and protocols. CQL expressions generally provide a means of computing new information from existing data.
For
more
guidance
and
best-practices
for
the
use
of
CQL
with
FHIR-based
knowledge
artifacts,
refer
to
the
Using
CQL
with
FHIR
implementation
guide.
FHIR
®©
HL7.org
2011+.
FHIR
R6
hl7.fhir.core#6.0.0-ballot3
generated
on
Tue,
Apr
1,
Mon,
Nov
10,
2025
12:26+1100.
15:23+0000.
Links:
Search
|
Version
History
|
Contents
|
Glossary
|
QA
|
Compare
to
R4
|
Compare
to
R5
|
Compare
to
Last
Ballot
|
|
Propose
a
change