---
title: YAML rule schema reference for Kibana Universal Alerting
description: YAML rule definitions support fields for detection mode, schedule, query, grouping, and recovery. Reference tables list all valid field values.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/9019/explore-analyze/alerting/esql/rules/yaml-rule-schema-reference
products:
- Elastic Documentation
- Kibana
applies_to:
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Planned
---
# 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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/9019/explore-analyze/alerting/esql/rules/create-esql-rule).
## Base rule fields
These fields are required on every rule.
| Field | Type | Accepted values | Description |
|------------------|--------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `kind` | string | `alert` or `signal` | Whether the rule tracks ongoing alerts (`alert`) or records point-in-time observations (`signal`). Set when the rule is created and can't be modified when editing the rule. |
| `metadata.name` | string | Any string | The name of the rule. Max 256 characters. |
| `schedule.every` | duration | Any duration string | How often the rule runs. For example: `5s`, `1m`, `5m`. Minimum interval applies. |
| `query.base` | ES|QL string | Any ES|QL query | The query that selects the data the rule evaluates. |
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`.
## Query fields
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.
| Field | Type | Description |
|------------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `query.base` | ES|QL string | The ES|QL query that selects the data to evaluate. Must include a `FROM` clause. Kibana applies the time filter from `schedule.lookback` using `time_field`. Required. |
| `query.breach.segment` | ES|QL segment string | An optional ES|QL clause that Kibana appends to `query.base`, for example `WHERE avg_cpu > 0.85`. Don't include a `FROM` clause. |
Several settings depend on the breach segment:
- To use the `condition` recovery strategy, set `query.breach`. Refer to [Recovery strategy](#recovery-strategy).
- To use a no-data strategy other than `ignore`, set `query.breach` or `no_data.query`. Refer to [No-data strategy](#no-data-strategy).
## Metadata fields
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.
| Field | Type | Accepted values | Description |
|-------------------------|------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metadata.description` | string | Any string | Optional description of what the rule monitors. Max 1,024 characters. |
| `metadata.tags` | array of strings | Array of strings | Labels for filtering and organization. Max 20 tags, each max 128 characters. |
| `metadata.routing_tags` | array of strings | Array of strings | Tags that link the rule's alerts to action policies. An action policy applies when it has at least one of these tags. Only valid when `kind: alert`. Max 20 tags, each max 128 characters. To learn more, refer to [Add routing tags to a rule](/elastic/docs-content/pull/9019/explore-analyze/alerting/esql/action-policies/create-configure-action-policy#add-routing-tags). |
## Schedule fields
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.
| Field | Type | Accepted values | Description |
|---------------------|----------|---------------------|--------------------------------------------------------------------------------------------------------|
| `schedule.lookback` | duration | Any duration string | How far back in time the query searches on each run. For example: `5m`, `24h`. |
| `time_field` | string | Any field name | The timestamp field used for the lookback window filter. Max 128 characters. Defaults to `@timestamp`. |
## Recovery strategy
The `recovery` object controls how Kibana detects that an alert has recovered. It's required when `kind: alert`, and `strategy` selects the behavior.
| Field | Type | Accepted values | Description |
|---------------------|----------------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `recovery.strategy` | string | `no_breach`, `condition`, `query`, or `manual` | How recovery is detected. - `no_breach`: Recovers an alert when its group no longer appears in the breach results. - `condition`: Recovers an alert when `query.base` plus `recovery.segment` returns the group. Requires `query.breach`. - `query`: Recovers an alert when `recovery.query` returns the group. - `manual`: Doesn't recover automatically. Close the alert with a user action. |
| `recovery.segment` | ES|QL segment string | Any ES|QL clause | Required when `strategy` is `condition`. An ES|QL clause that Kibana appends to `query.base`, for example `WHERE avg_cpu < 0.60`. Don't include a `FROM` clause. |
| `recovery.query` | ES|QL string | Any ES|QL query | Required when `strategy` is `query`. An independent ES|QL query with its own `FROM` clause. A group that this query returns recovers its alert. |
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.
Rules with `kind: signal` can't set `recovery`. A rule with `strategy: manual` can't set `state_transition.recovering`, because the recovery delay has no effect when alerts never recover on their own.
## State transition fields
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.
| Field | Type | Accepted values | Description |
|-----------------------------------------|----------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `state_transition.pending.count` | integer | Integer, 0–1000 | Consecutive matches the alert spends in `pending` before it becomes `active` on the next match. For example, `2` opens the alert on the third consecutive match. Set to `0` to open it on the first match. |
| `state_transition.pending.timeframe` | duration | Any duration string | How long the condition must hold before the alert becomes active. For example: `5m`. |
| `state_transition.pending.operator` | string | `and` or `or` | Allowed only when you set both `count` and `timeframe`. `and` requires both and `or` requires either. Defaults to `or`. |
| `state_transition.recovering.count` | integer | Integer, 0–1000 | Consecutive recoveries the alert spends in `recovering` before it becomes `inactive` on the next recovery. For example, `2` closes the alert on the third consecutive recovery. Set to `0` to close it on the first recovery. |
| `state_transition.recovering.timeframe` | duration | Any duration string | How long the condition must hold before the alert recovers. For example: `5m`. |
| `state_transition.recovering.operator` | string | `and` or `or` | Allowed only when you set both `count` and `timeframe`. `and` requires both and `or` requires either. Defaults to `or`. |
```yaml
state_transition:
pending:
count: 2
timeframe: 5m
operator: and
recovering:
count: 1
```
## Grouping fields
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.
| Field | Type | Accepted values | Description |
|-------------------|------------------|----------------------|---------------------------------------------------------------------------------------------------------------------|
| `grouping.fields` | array of strings | Array of field names | Fields to group results by. Each unique combination becomes its own series. Max 16 fields, each max 256 characters. |
## No-data strategy
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.
| Field | Type | Accepted values | Description |
|--------------------|--------------|-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `no_data.strategy` | string | `ignore`, `keep_last`, or `resolve` | What happens when a group has no data. - `ignore`: Doesn't check whether a group still has data. Missing groups don't produce `no_data` events. - `keep_last`: Holds the alert's current status. - `resolve`: Closes the alert the first time the rule finds no data for the group. |
| `no_data.query` | ES|QL string | Any ES|QL query | Optional presence query that checks whether a group has data. Allowed with `keep_last` and `resolve`. If you omit it, Kibana uses `query.base` as the presence query. |
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.
Rules with `kind: signal` can't set `no_data`.
## Artifact fields
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.
| Field | Type | Accepted values | Description |
|---------------------------------|--------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `artifacts[].id` | string | Any string | Artifact identifier. Required. Max 256 characters. |
| `artifacts[].type` | string | Any string | Use `runbook` or `dashboard`. Other strings are allowed. Max 128 characters. |
| `artifacts[].data` | object | Type-specific object | Required. The artifact's content. Max 32 fields. |
| `artifacts[].data.content` | string | Non-empty string | The Markdown body of a runbook. Kibana displays it on the **Runbook** tab of the rule details page. Required when `type` is `runbook`. Max 50,000 characters. |
| `artifacts[].data.dashboard_id` | string | Non-empty string | ID of the dashboard to link. Required when `type` is `dashboard`. Max 1,024 characters. |
The following example attaches a runbook and a dashboard to the same rule.
```yaml
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"
```
## Duration format
All duration fields accept the following units:
| Unit | Example | Meaning |
|------|---------|---------|
| `s` | `30s` | Seconds |
| `m` | `5m` | Minutes |
| `h` | `1h` | Hours |
| `d` | `7d` | Days |
## Related pages
- [Create an ES|QL rule](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/9019/explore-analyze/alerting/esql/rules/create-esql-rule): Author rules using the YAML editor, with a live sandbox for previewing results.
- [Configure a rule](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/9019/explore-analyze/alerting/esql/rules/configure-a-rule): Field-by-field guidance for each setting, with examples and when-to-use recommendations.