---
type: "doc"
source: "source/clinicalreasoning-topics-definitional-resources.html"
---
\[%settitle Clinical Reasoning%\] \[%file newheader%\] \[%file newnavbar%\]

| Responsible Owner: Work Group [\[%wgt cds%\]]([%wg cds%]) | [Standards Status](versions#std-process): [Informative](versions#std-process) |
| --- | --- |

### Definitional Resources

Part of defining knowledge artifacts such as order sets, protocols, and decision support rules is describing in a patient- or context-independent way the activities to be performed. For example, when defining an order set, the orderable items must be described with enough detail to enable the creation of the items when the order set is applied. These descriptions can be thought of as _templates_ for the creation of patient- or context-specific resources and are often referred to as _definitional_ resources, to distinguish them from _intent_ resources (that signal an intention to take some action for a specific patient), as well as _event_ resources (that signal that some action has actually been taken for a patient).

Definitional resources in clinical reasoning build on the [Definition](definition) pattern established in the [Workflow](workflow) module. The treatment here is from the clinical reasoning perspective, specifically discussing how definitional resources can be used as knowledge artifacts to provide computable representations of clinical knowledge.

In the most general case, these definitional resources only need to describe the most basic aspects of the activity to be performed, such as:

-   Who - Which person should perform the activity, often specified as a participant role such as a provider specialty.
-   What - What type of activity should be performed, often specified simply as a category or a concept.
-   When - When the activity should be performed, often specified relative to the time the plan is applied.
-   Where - Where the activity should take place, often specified as a facility role.
-   Why - Why the activity should be performed

However, this level of conceptual description often does not carry enough information to enable computable description of activities. For example, medication activities will often involve specific drug and dosage information that must be captured as part of the definition. Further, it is often the case that the values for the elements of resources to be created cannot be specified exactly as part of the definition, but must be specified using a formula that allows for the calculation to be based on patient- or context-specific information.

Note to implementers: Although there are currently only a few _definitional_ resources defined (ActivityDefinition, ObservationDefinition, SpecimenDefinition), the concept is general, and this is a deliberate design decision to avoid the overhead of defining and maintaining a different definitional resource for every category of request. We anticipate that as the use cases for definitional activities require more specialized elements to be represented, additional definitional resources will be defined.

#### Activity Flow

For more information on the general process of realizing definitional resources, refer to the [Applying a PlanDefinition](plandefinition) and [Applying an ActivityDefinition](activitydefinition) topics.

For a more detailed treatment of representing and realizing clinical activities as part of computable guidelines, refer to the [Activity Flow](http://hl7.org/fhir/uv/cpg/activityflow.html) topic in the Clinical Guidelines implementation guide.

#### ActivityDefinition

The [ActivityDefinition](activitydefinition) resource supports the description of definitional resources within FHIR:

| Who | participantType | Specifies the type of participant that should perform the activity. |
| --- | --- | --- |
| What | kind and code | Specifies the type of activity to be performed. |
| When | timing | Specifies when the activity should be performed. |
| Where | location | Specifies where the activity should be performed. |
| Why | reason, documentation | Specifies why the activity should be performed. |

##### Referral Request

For example, the following fragment illustrates a definition to create a referral request:

```
<ActivityDefinition>
  <description value="refer to primary care mental-health integrated care program for evaluation and treatment
   of mental health conditions now"/>
  <kind value="ServiceRequest"/>
  <code>
    <coding>
      <system value="http://snomed.info/sct"/>
      <code value="306206005"/>
      <display value="Referral to service"/>
    </coding>
  </code>
  <timingTiming>
    <event>
      <extension url="http://hl7.org/fhir/StructureDefinition/cqf-expression">
        <valueExpression>
          <language value="text/cql-expression"/>
          <expression value="Now()"/>
        </valueExpression>
      </extension>
    </event>
  </timingTiming>
  <participantType value="practitioner"/>
</ActivityDefinition>
```

This definition specifies:

-   The `kind` of resource to be created, a `ServiceRequest`
-   That the resulting resource should have a `code` of `SNOMED 306206005: Referral to service`
-   That is should occur `Now()` (i.e., as soon as possible)
-   That it involves a `practitioner`

Note the use of an expression to represent the value of the timing element as `Now()`.

##### Medication Request

For medication activities, the [ActivityDefinition](activitydefinition) resource has some basic elements such as the `product` and `quantity`, and `dosageInstruction` but there are cases where elements that need to be set on the resulting MedicationRequest are not present on the ActivityDefinition (such as `dispenseRequest`). In those cases, the `dynamicValue` expression elements can be used to describe the values for elements that are present on the target resource, but not in the definitional resource. For example:

```
<ActivityDefinition>
  <id value="citalopramPrescription"/>
  <status value="draft"/>
  <category value="drug"/>
  <productReference>
    <reference value="#citalopramMedication"/>
  </productReference>
  <dynamicValue>
    <path value="dispenseRequest.numberOfRepeatsAllowed"/>
    <expression>
      <language value="text/cql-expression"/>
      <expression value="3"/>
    </expression>
  </dynamicValue>
  <dynamicValue>
    <path value="dispenseRequest.quantity"/>
    <expression>
      <language value="text/cql-expression"/>
      <expression value="30 '{tbl}'"/>
    </expression>
  </dynamicValue>
</ActivityDefinition>
```

To specify that a particular device should be used in the administration of a medication, use the `action.typeCanonical` element set to an instance of a DeviceDefinition resource:

```
<typeCanonical value="http://example.org/fhir/DeviceDefinition/administration-device"/>
```

This will then result in the creation of a MedicationRequest resource with the device element set to that DeviceDefinition.

##### Observation

The [ObservationDefinition](observationdefinition) resource supports the definition of an observation to be taken.

##### Specimen

The [SpecimenDefinition](specimendefinition) resource supports the definition of a specimen to be collected.

##### Message

The [MessageDefinition](messagedefinition) resource supports the definition of a message to be communicated. NOTE: This is a system-level message, as opposed to a human-to-human message, which would be modeled using the CommunicationRequest and Communication resources.

##### Questionnaire

The [Questionnaire](questionnaire) resource can be used to directly support describing information to be collected as part of a process. The [Structured Data Capture](http://hl7.org/fhir/uv/sdc) implementation guide provides detailed information for supporting this use case.

##### Event Resources

Note that the ActivityDefinition resource is specifically designed to support _request_ resources, typically with an intent of _proposal_ to ensure that clinician interaction can be part of interpreting the results of any automated reasoning processes. However, it is possible to construct _event_ resources as part of the reasoning process, such as Observations, Procedures, RiskAssessments, DetectedIssues, etc. To support this case, implementations should make use of a Task resource with _proposal_ intent, where the `focus` of the Task would be the computed event resource.

#### EvidenceVariable

The [EvidenceVariable](evidencevariable) resource supports the description of definitional resources for variables to be referenced from an Evidence resource:

| Who | topic | Could specify the category of evidence variable (eg condition, exposure); available for future uses |
| --- | --- | --- |
| What | characteristic.definition\[x\] | Specifies a component of the definition of the evidence variable |
| When | characteristic.timeFromStart | Subelement of characteristic to specify when the definitional component was or will be determined |
| Where | type | Specifies the type of variable (eg dichotomous. Categorical, continuous, descriptive) |
| How | Characteristic.method | Specifies how the definitional component was or will be determined |

For example, the following fragment illustrates a definition of "intracranial hemorrhage within 7 days" as a characteristic from an EvidenceVariable instance:

```
<characteristic>
  <description value="intracranial hemorrhage within 7 days"/>
  <definitionCodeableConcept>
    <coding>
      <system value="http://snomed.info/sct"/>
      <code value="1386000"/>
      <display value="Intracranial hemorrhage (disorder)"/>
    </coding>
  </definitionCodeableConcept>
  <timeFromStart>
    <description value="within 7 days"/>
    <range>
      <low>
        <value value="0"/>
        <unit value="day"/>
        <system value="http://unitsofmeasure.org"/>
        <code value="d"/>
      </low>
      <high>
        <value value="7"/>
        <unit value="day"/>
        <system value="http://unitsofmeasure.org"/>
        <code value="d"/>
      </high>
    </range>
  </timeFromStart>
</characteristic>
```

\[%file newfooter%\]