PlanDefinition — Orchestrating clinical actions

The backbone of a protocol, care pathway or order set. Combines ActivityDefinition, ECA (Event-Condition-Action) rules and CQL libraries to dynamically generate a CarePlan or a RequestOrchestration.

Purpose of the resource

PlanDefinition represents a template of ordered actions — protocol, order set, pathway, ECA rule. Its scope is broader than ActivityDefinition: a PlanDefinition can trigger other nested PlanDefinitions, instantiate several ActivityDefinitions in parallel, and carry conditional rules.

Typical use cases:

• Order set — bundle of medical orders for a given situation (ICU admission, suspected stroke).
• Clinical protocol — sequence of assessments and treatments to apply.
• CDS rule — trigger (Observation, MedicationRequest) + condition (CQL) + actions.
• Care pathway — structured journey for a condition (diabetes, heart failure).

Key fields

Action model

The action field is recursive and carries the orchestration logic:

• trigger — when to fire (TriggerDefinition: named event, data condition, scheduling).
• condition — CQL/FHIRPath precondition (applicability, start, stop).
• input / output — required and produced data.
• relatedAction — dependency with another action (before, after, concurrent).
• selectionBehavior — any | all | all-or-none | exactly-one | at-most-one | one-or-more.
• requiredBehavior — must | could | must-unless-documented.
• cardinalityBehavior — single | multiple.
• definitionCanonical — points to ActivityDefinition, Questionnaire, or another PlanDefinition.
• Nested action — for sub-protocols.

JSON example

{
  "resourceType": "PlanDefinition",
  "id": "low-suicide-risk-order-set",
  "url": "http://example.org/PlanDefinition/low-suicide-risk-order-set",
  "version": "5.0.0",
  "name": "LowSuicideRiskOrderSet",
  "title": "Low Suicide Risk Order Set",
  "type": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
      "code": "order-set",
      "display": "Order Set"
    }]
  },
  "status": "active",
  "experimental": true,
  "date": "2026-05-15",
  "publisher": "HL7 International (Clinical Decision Support WG)",
  "action": [{
    "title": "Suicide Risk Assessment",
    "definitionCanonical": "http://example.org/ActivityDefinition/suicide-risk-assessment"
  }]
}

$apply operation

The $apply operation materialises a PlanDefinition for a subject and context:

• POST /PlanDefinition/{id}/$apply with subject, encounter, practitioner, organization.
• The server evaluates trigger, condition and dynamicValue.
• It returns a CarePlan or a RequestOrchestration aggregating the concrete resources (MedicationRequest, ServiceRequest, Task…).

Common pitfalls

• Actions without title — clinicians do not know what to tick in the order set.
• Unversioned CQL — the library must pin a version for reproducibility.
• Circular relatedAction — evaluation of the plan loops.
• Missing selectionBehavior on a group — default is any, rarely what is intended.

Related resources

• ActivityDefinition — atomic actions composed.
• Library — referenced CQL logic.
• RequestOrchestration — output of $apply.
• CarePlan — instantiated care plan.
• FHIR R5 hub.