enable-when-patterns

name	enable-when-patterns
description	Common conditional-display patterns for Questionnaire items via core enableWhen. Covers red-flag triage, skip-if-not- applicable, and branch-on-severity. Use when the user wants conditional logic ("only ask this if they answered yes to X").

enableWhen patterns

When to use this

• The user asks for "only ask this if …" or "skip these unless …".
• You're proposing a follow-up that should only fire when a preceding answer matches a condition.
• You're auditing existing logic and need a pattern reference.

v1 uses core enableWhen, NOT enableWhenExpression

We honor enableWhen (FHIR core array) only. If an item already carries enableWhenExpression (SDC), leave it intact and surface a warning — do NOT rewrite it. Mixing both on the same item is renderer-dependent and forbidden in v1 authoring.

Pattern: any-true (logical OR)

{
  "linkId": "rf-thunderclap-followup",
  "type": "text",
  "enableBehavior": "any",
  "enableWhen": [
    { "question": "rf-thunderclap", "operator": "=", "answerBoolean": true },
    { "question": "rf-fever",       "operator": "=", "answerBoolean": true }
  ]
}

enableBehavior defaults to any; spell it out for clarity.

Pattern: all-true (logical AND)

{
  "linkId": "high-risk-imaging",
  "type": "boolean",
  "text": "Has imaging been ordered?",
  "enableBehavior": "all",
  "enableWhen": [
    { "question": "rf-thunderclap", "operator": "=", "answerBoolean": true },
    { "question": "age-over-50",    "operator": "=", "answerBoolean": true }
  ]
}

Pattern: branch on severity (choice → follow-up)

{
  "linkId": "severity-followup",
  "type": "text",
  "enableWhen": [
    {
      "question": "headache-severity",
      "operator": "=",
      "answerCoding": { "system": "http://snomed.info/sct", "code": "24484000", "display": "Severe" }
    }
  ]
}

For Likert numbers use answerInteger; for free-text branches use answerString.

Operators that work

Operator	Meaning	Notes
exists	answer present (regardless of value)	use with answerBoolean: true to mean "answered".
=	exact match	most common.
!=	not equal	rarely needed; usually flip the operand.
> < >= <=	numeric comparison	only on numeric types.

Group-level (skip whole sections)

enableWhen works on group-typed items too — that's the right shape for "skip the entire pain section unless the patient reported pain". Children are auto-hidden when the group is disabled.

Pitfalls

• Forgetting to populate enableBehavior when there are 2+ conditions. The default is any; if you wanted AND, you must say so.
• Coding the answer with answerString when the source item is choice with answerCoding. The match-shape must align with the source item's answer type.
• Cycles. q2.enableWhen.question = q3 and q3.enableWhen.question = q2 — no renderer guarantees behavior. Cycle-check before proposing.