elastic · benironside · May 26, 2026
@@ -0,0 +1,5 @@
+**Schema convention.** In each schema table below, the `Location` column indicates where each parameter sits in the YAML:
+
+- `top level` — Alongside `type` and `name`, at the top of the step or trigger definition.
+- `` `with` `` — Inside the step's `with:` block.
+- `` `on` `` — Inside the trigger's `on:` block.
@@ -28,6 +28,9 @@ AI steps let workflows call a large language model (LLM) for reasoning, classifi
 `connector-id`, `agent-id`, and `inference-id` are **top-level step fields** (alongside `name`, `type`, `if`, `foreach`), written in **kebab-case**. They are not nested under `with`, and not `connectorId`. Inside `with`, most AI parameters use `camelCase` (`systemPrompt`, `maxLength`, `includeRationale`). Authentication-style references stay at the top level in kebab-case; content parameters stay inside `with` in camelCase.
 :::
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## `ai.prompt` [ai-prompt]
 
 ```{applies_to}

@@ -41,6 +41,9 @@ Every `cases.*` step shares the same conventions, so once you learn one step the
     severity: high
 ```
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 % Ben Ironside Goldstein, 2026-04-27: Engineering review (Janmonschke) noted that not all 27 steps
 % support push-case. A complete list of which steps support it would strengthen this section once
 % available. For now the page documents the optional flag generally and leaves per-step support

@@ -52,6 +52,9 @@ The execution engine enforces a maximum composition depth to prevent infinite re
 
 ---
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## `workflow.execute` [workflow-execute]
 
 Run a child workflow synchronously. The parent waits for the child to finish and receives its validated outputs.

@@ -62,6 +62,9 @@ Refer to [Pass data and handle errors](/explore-analyze/workflows/authoring-tech
 
 ---
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## Variables and mapping
 
 ### `data.set` [data-set]

@@ -25,6 +25,9 @@ All {{kib}} actions are automatically authenticated using the permissions or API
 The detection alert step type IDs use **PascalCase**, not lowercase or snake_case: `kibana.SetAlertsStatus`, `kibana.SetAlertTags`. The editor rejects lowercase variants. This is the most common authoring surprise on the {{kib}} namespace.
 :::
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## Step types
 
 - [`kibana.SetAlertsStatus`](#kibana-setalertsstatus): Change the status of one or more detection alerts.

@@ -17,9 +17,12 @@
 
 The `loop.break` step exits the innermost enclosing [`foreach`](/explore-analyze/workflows/steps/foreach.md) or [`while`](/explore-analyze/workflows/steps/while.md) loop immediately. Use it to stop iterating once a condition is met, for example when you want to process items until you find the first critical match and then move on.
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## Parameters
 
 The `loop.break` step takes no step-specific parameters; only the standard `name` and `type` fields required on every step.

 | Parameter | Location | Type | Required | Description |
 |---|---|---|---|---|

@@ -15,8 +15,11 @@

 # Loop continue [workflows-loop-continue-step]
 
 The `loop.continue` step skips the rest of the current iteration in the innermost enclosing [`foreach`](/explore-analyze/workflows/steps/foreach.md) or [`while`](/explore-analyze/workflows/steps/while.md) loop and moves on to the next iteration. Use it to skip items that don't meet a filter, without nesting the remaining logic inside an `if`.
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## Parameters
 
 `loop.continue` takes no parameters.

@@ -18,9 +18,12 @@
 Streams action steps operate on Observability [Streams](/solutions/observability/streams/streams.md) from a workflow. Use them to list available streams, fetch a specific stream's configuration, or pull significant events from a stream's time window.

 :::{warning}
 Streams action steps, along with the Streams feature itself, are in technical preview in 9.4. Schemas and semantics can change in future releases. Use these steps for prototypes and investigation workflows; hold off on critical automation until Streams reaches GA.
 :::
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## Step types
 
 - [`kibana.streams.list`](#kibana-streams-list): Enumerate available streams.

@@ -17,6 +17,9 @@ products:
 
 The `switch` step evaluates an expression once and compares its value against each case's `match` field in order, then dispatches to the first matching case and executes its `steps`. Use it for multi-way branching where an `if` chain would be awkward (for example, routing by alert category, severity tier, or environment name).
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## Parameters
 
 | Parameter | Location | Type | Required | Description |

@@ -19,6 +19,9 @@ The `waitForInput` step pauses workflow execution until a human submits input. I
 
 For the end-to-end pattern including resume API details and design guidance, refer to [Human-in-the-loop](/explore-analyze/workflows/authoring-techniques/human-in-the-loop.md).
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## Parameters
 
 | Parameter | Location | Type | Required | Description |

@@ -19,6 +19,9 @@ The `while` step runs its nested steps repeatedly as long as a {{kib}} Query Lan
 
 Use `while` for polling patterns: checking a status until it reaches `ready`, retrying an operation until it succeeds, or waiting for an external job to complete. For iterating over a known collection, use [`foreach`](/explore-analyze/workflows/steps/foreach.md) instead.
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## Parameters
 
 | Parameter | Location | Type | Required | Description |

@@ -24,6 +24,9 @@ Event-driven triggers let workflows react to events elsewhere in {{kib}}. Two tr
 The event-driven trigger system is in technical preview, including the triggers documented on this page. The schema and semantics can change in future releases.
 :::
 
+:::{include} ../_snippets/schema-location-legend.md
+:::
+
 ## `workflows.failed`
 
 Fires when any workflow execution reaches the `failed` terminal state. Use this trigger to build handler workflows that react to failures in your production workflows, for example by paging on-call, opening a case, or logging to a dedicated index for observability.
@@ -163,8 +166,6 @@ Cases triggers fire when cases change. Use them to react to case lifecycle event
 - `event.caseId` — The case ID, the alphanumeric identifier that is unique to each case.
 - `event.owner` — The solution that owns the case. It can be `securitySolution` for {{elastic-sec}} cases, `observability` for Observability cases, or `cases` for Stack cases.
 
-**Schema convention.** In each trigger's schema table below, the `Location` column indicates where each parameter sits in the trigger YAML. `top level` means the parameter sits alongside `type`; `` `on` `` means it sits inside the `on:` block, parallel to how `workflows.failed` uses `on:` for its condition.
-
 Use `event.owner` in `on.condition` to filter by solution. For example, a workflow that only fires for {{elastic-sec}} cases:
 
 ```yaml
-Original file line number
+Diff line change
@@ Expand Up @@
     ---
+    :::{include} ../_snippets/schema-location-legend.md
+    :::
     ## `workflow.execute` [workflow-execute]
     Run a child workflow synchronously. The parent waits for the child to finish and receives its validated outputs.
@@ Expand Down @@