---
title: YAML rule schema reference for the experimental alerting system
description: YAML rule definitions in the experimental alerting system 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/7416/explore-analyze/alerting/experimental-alerting-system/rules/yaml-rule-schema-reference
products:
- Kibana
applies_to:
- Elastic Cloud Serverless: Experimental
- Elastic Stack: Planned
---
# YAML rule schema reference for the experimental alerting system
This page lists valid fields for YAML rule definitions in the experimental alerting system. For authoring guidance, refer to [Create an ES|QL rule](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7416/explore-analyze/alerting/experimental-alerting-system/rules/create-esql-rule).
## Base rule fields
These four fields are required on every rule, regardless of format or mode. The value of `query.format` determines which additional query fields are required.
| Field | Type | Accepted values | Description |
|------------------|----------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `kind` | string | `alert` or `signal` | Whether the rule tracks ongoing episodes (`alert`) or records point-in-time observations (`signal`). |
| `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.format` | string | `composed` or `standalone` | The query structure the rule uses. `standalone` means each condition (breach, recovery, no-data) is a separate, self-contained ES|QL query. `composed` means you write one base query and each condition is a pipe segment appended to it. The UI always creates `standalone` rules. |
### Fields for `query.format: composed`
Use `composed` when breach, recovery, and no-data conditions all start from the same data shape. Define that shape once in the base query and each condition adds only what differs.
| Field | Type | Description |
|--------------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| `query.base` | ES|QL string | Base query that runs on every evaluation. Time filters are applied automatically using the lookback window. Required. |
| `query.breach.segment` | ES|QL segment string | ES|QL segment appended to the base query for breach detection. Written as a pipe command, for example `\| WHERE count > 5`. Required. |
| `query.recovery.segment` | ES|QL segment string | ES|QL segment appended to the base query for recovery detection. Required when `recovery_strategy` is `query`. |
### Fields for `query.format: standalone`
Use `standalone` when conditions need full independence. Each query can target different indices, apply different filters, or return a completely different shape.
| Field | Type | Description |
|------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| `query.breach.query` | Full ES|QL string | Full ES|QL query for breach detection. Required. |
| `query.recovery.query` | Full ES|QL string | Full ES|QL query for recovery detection. Required when `recovery_strategy` is `query`. |
| `query.no_data.query` | Full ES|QL string | Full ES|QL query that detects presence of data. Required when `no_data_strategy` is not `none`. Only supported on `standalone` format. |
## Metadata fields
These optional fields add descriptive information to a rule for identification, ownership, and filtering. 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.owner` | string | Any string | Team or person responsible for the rule. Max 256 characters. |
| `metadata.tags` | array of strings | Array of strings | Labels for filtering and organization. Max 20 tags, each max 128 characters. |
## 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_strategy` field is optional. When omitted, the rule emits no recovery events and active alert episodes don't close automatically.
| Field | Type | Accepted values | Description |
|---------------------|--------|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `recovery_strategy` | string | `no_breach`, `query`, or `none` | How recovery is detected. -`no_breach`: Recovers an episode when its active group no longer appears in the breach results. - `query`: Evaluates a separate recovery query defined in `query.recovery.segment` (composed) or `query.recovery.query` (standalone) - `none`: Turns off recovery. |
Signal-mode rules (`kind: signal`) must omit `recovery_strategy` or set it to `none`. Any other value fails validation.
## State transition fields
Only valid when `kind: alert`. Controls how many consecutive detections are required before an episode becomes active or recovers.
| Field | Type | Accepted values | Description |
|-----------------------------------------|----------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `state_transition.pending_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before becoming active. |
| `state_transition.pending_count` | integer | Integer, 0–1000 | Number of consecutive breaches required before the episode becomes active. Set to `0` to skip the pending phase and transition directly to active on the first breach. |
| `state_transition.pending_timeframe` | duration | Any duration string | How long the condition must remain continuously breached before the episode becomes active. For example: `5m`. |
| `state_transition.recovering_operator` | string | `AND` or `OR` | Whether both the count and timeframe must be met (`AND`) or either one (`OR`) before recovering. |
| `state_transition.recovering_count` | integer | Integer, 0–1000 | Number of consecutive clear evaluations required before the episode recovers. Set to `0` to skip the recovering phase and transition directly to inactive on recovery. |
| `state_transition.recovering_timeframe` | duration | Any duration string | How long the condition must remain continuously non-breaching before the episode recovers. For example: `5m`. |
## 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 episode 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
Use `no_data_strategy` to control what the rule does when an evaluation returns no results. This matters when data sources can go silent. Without this setting, a quiet data source and a healthy one look identical to the rule.
| Field | Type | Accepted values | Description |
|--------------------|--------|---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `no_data_strategy` | string | `emit`, `last_known_status`, `recover`, or `none` | Optional. What happens when the rule evaluates and returns no results. `emit` records a no-data event. `last_known_status` holds the last known status. `recover` forces recovery. `none` disables no-data detection. |
No-data detection is only supported with `query.format: standalone`. Setting `no_data_strategy` to any active value on a `composed` rule has no effect because `query.no_data.query` can only be defined on a standalone query. Signal-mode rules (`kind: signal`) must omit `no_data_strategy` or set it to `none`.
## Artifact fields
Artifacts let you attach reference material directly to a rule, such as a runbook. The content is stored with the rule and displayed in the rule detail view so responders have context when an alert fires. All artifact fields are optional.
| Field | Type | Accepted values | Description |
|---------------------|--------|-----------------|-----------------------------------------------------------------------------------------------------------|
| `artifacts[].id` | string | Any string | Artifact identifier. Required. Max 256 characters. |
| `artifacts[].type` | string | Any string | The type of artifact being attached. For example: `runbook`. |
| `artifacts[].value` | string | Any string | The content of the artifact. Accepts markdown. Runbooks are rendered as markdown in the rule detail view. |
## 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/7416/explore-analyze/alerting/experimental-alerting-system/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/7416/explore-analyze/alerting/experimental-alerting-system/rules/configure-a-rule): Field-by-field guidance for each setting, with examples and when-to-use recommendations.