FHIR PlanDefinition is the resource for representing clinical care pathways, treatment protocols, and quality measures as structured, executable definitions. It's powerful but underused; understanding when it applies avoids force-fitting.
When PlanDefinition fits
1. Evidence-based treatment protocols. "Diabetic patient with HbA1c >8 gets X action within Y days." 2. Quality measure definitions. Measure resources reference PlanDefinition for calculation logic. 3. Clinical decision support content. CDS Hooks rules can be defined as PlanDefinition + ActivityDefinition. 4. Care pathway automation. Multi-step care coordination workflows.
When it doesn't fit
1. Simple single-step rules. Overkill for "if X then Y" logic. 2. Non-clinical business rules. PlanDefinition assumes clinical action model. 3. Free-form clinical narratives. PlanDefinition is structured; narratives belong elsewhere.
Related resources
- **ActivityDefinition — a specific action within a PlanDefinition. - PlanDefinition.action.trigger — event that initiates the action. - PlanDefinition.action.condition — pre-conditions before action fires. - PlanDefinition.action.definition** — reference to ActivityDefinition or Questionnaire.
Execution engines
MITRE's cqf-ruler is the reference implementation for PlanDefinition execution. It combines HAPI FHIR + CQL Framework to execute logic. Aidbox and some commercial servers support PlanDefinition execution natively.
Common integration mistakes
1. Treating PlanDefinition as static reference. It's meant to be executed, not just stored. 2. Missing CQL binding. Complex logic requires CQL; without it, PlanDefinition is just structure. 3. No trigger integration. PlanDefinition without event-driven triggers doesn't fire automatically. 4. Manual translation to application code. Defeats the purpose of a declarative model.
Where teams see value
Quality measure reporting, chronic condition management, and CMS-0057 Provider Access data-driven decisions are the common productive uses. Sites that treat PlanDefinition as executable clinical logic (not documentation) get value; sites that treat it as reference documentation don't.
