YAML rule schema reference for Kibana Universal Alerting

Kibana Universal Alerting YAML rule definitions accept the following fields. For authoring guidance, refer to Create an ES|QL rule.

These fields are required on every rule.

Rules with kind: alert also require the recovery and no_data objects. The rule APIs reject an alert rule that omits either one. If you omit them in the YAML editor of the rule form, Kibana fills in strategy: no_breach for recovery and strategy: ignore for no_data.

Every rule has one base query that selects the data to evaluate. To match only some rows, add a breach segment. Without one, every row that query.base returns is a match.

Several settings depend on the breach segment:

• To use the condition recovery strategy, set query.breach. Refer to Recovery strategy.
• To use a no-data strategy other than ignore, set query.breach or no_data.query. Refer to No-data strategy.

These optional fields add descriptive information to a rule for identification and filtering, and link the rule to action policies. None affect rule evaluation behavior.

These fields control how far back each evaluation looks and which timestamp field is used for the time range filter. Both are optional, but omitting schedule.lookback means the query runs without a time bound.

The recovery object controls how Kibana detects that an alert has recovered. It's required when kind: alert, and strategy selects the behavior.

The condition strategy requires query.breach. Without a breach segment, every row of query.base already matches, so the recovery condition could only return groups that are still breaching.

Only valid when kind: alert. Controls how many consecutive detections are required before an alert becomes active or recovers.

State transition settings are nested objects. state_transition.pending delays when an alert opens, and state_transition.recovering delays when an alert closes. In each object, set count, timeframe, or both.

state_transition:
  pending:
    count: 2
    timeframe: 5m
    operator: and
  recovering:
    count: 1
		

Use grouping to split a rule's detections into independent series, one per unique combination of field values. This lets a single rule track multiple subjects without creating a separate rule for each, for example, tracking CPU usage per host. Each series maintains its own alert lifecycle.

When a data source goes silent, a quiet source and a healthy one can look the same to a rule. The no-data setting controls what the rule does with an alert when its group has no data.

The no_data object is required when kind: alert, and strategy selects the behavior.

A strategy other than ignore requires query.breach or no_data.query. That way, Kibana can tell a group with no data apart from a group that stopped breaching.

Artifacts let you attach reference material directly to a rule, such as a runbook or a linked dashboard. Kibana stores the artifact with the rule and displays it on the rule details page, so responders have context when an alert fires.

The artifacts array is optional and accepts up to 100 entries. Every artifact needs id, type, and data, as shown in the following table.

The following example attaches a runbook and a dashboard to the same rule.

artifacts:
  - id: checkout-runbook
    type: runbook
    data:
      content: |
        Fires when checkout error rate exceeds 10%.
  - id: checkout-errors-dashboard
    type: dashboard
    data:
      dashboard_id: "8ac12f90-3d2b-11ef-9a4e-0242ac120002"
		

1. type determines which data field the artifact requires.
2. The runbook Markdown goes in data.content.
3. The dashboard ID goes in data.dashboard_id.

All duration fields accept the following units:

• Create an ES|QL rule: Author rules using the YAML editor, with a live sandbox for previewing results.
• Configure a rule: Field-by-field guidance for each setting, with examples and when-to-use recommendations.