--- title: YAML rule schema reference for the experimental alerting system description: YAML rule definitions in Kibana's 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/6523/explore-analyze/alerting/kibana-alerting-experimental/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 YAML rule schema is part of the experimental alerting system in Kibana. This page lists valid fields for YAML rule definitions. For examples and authoring guidance, refer to [Create rules using the YAML editor](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6523/explore-analyze/alerting/kibana-alerting-experimental/rules/create-rule-with-yaml). ## Required fields | 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 | Max 256 characters | The name of the rule. | | `schedule.every` | duration | For example, `5s`, `1m`, `5m` | How often the rule runs. Minimum interval applies. | | `evaluation.query.base` | string | Valid ES|QL query, max 10,000 characters | The query that checks your data on each run. | ## Metadata fields | Field | Type | Accepted values | Description | |------------------------|------------------|----------------------|-------------------------------------------------| | `metadata.description` | string | Max 1,024 characters | Optional description of what the rule monitors. | | `metadata.owner` | string | Max 256 characters | Team or person responsible for the rule. | | `metadata.tags` | array of strings | Max 100 tags | Labels for filtering and organization. | ## Schedule fields | Field | Type | Accepted values | Description | |---------------------|----------|------------------------------------------|------------------------------------------------------------------------------------| | `schedule.lookback` | duration | For example, `5m`, `24h` | How far back in time the query searches on each run. | | `time_field` | string | Any valid field name, max 128 characters | The timestamp field used for the lookback window filter. Defaults to `@timestamp`. | ## Recovery policy fields The `recovery_policy` field is optional. When absent, the rule emits no recovery events and active alert episodes don't close automatically. Omitting `recovery_policy` is only possible when creating a rule via the API or Agent Builder. Rules created through the Kibana UI always include `recovery_policy.type: no_breach` by default. | Field | Type | Accepted values | Description | |------------------------------|--------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | `recovery_policy.type` | string | `no_breach` or `query` | How recovery is detected. `no_breach` recovers when the query returns no breach results for the active group. `query` uses a separate recovery query. | | `recovery_policy.query.base` | string | Valid ES|QL query | Required when `recovery_policy.type` is `query`. The query that checks whether the condition has cleared. | ## 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 | 0 or more | Number of consecutive breaches required before the episode becomes active. | | `state_transition.pending_timeframe` | duration | For example, `5m` | Time window within which the breach count must be met. | | `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 | 0 or more | Number of consecutive clear evaluations required before the episode recovers. | | `state_transition.recovering_timeframe` | duration | For example, `5m` | Time window within which the recovery count must be met. | ## Grouping fields | Field | Type | Accepted values | Description | |-------------------|------------------|----------------------------------------|-----------------------------------------------------------------------------| | `grouping.fields` | array of strings | Max 16 fields, each max 256 characters | Fields to group results by. Each unique combination becomes its own series. | ## No-data fields | Field | Type | Accepted values | Description | |---------------------|----------|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `no_data.behavior` | string | `no_data`, `last_status`, or `recover` | What happens when the query returns no results. `no_data` records a no-data event. `last_status` keeps the current status. `recover` closes any active episode. | | `no_data.timeframe` | duration | For example, `5m` | How long the query must return no results before the no-data behavior applies. | ## Artifact fields | Field | Type | Accepted values | Description | |---------------------|--------|------------------------|-----------------------------------------------------------------------------------------| | `artifacts[].type` | string | For example, `runbook` | The type of artifact being attached. | | `artifacts[].value` | string | Markdown content | The content of the artifact. Runbooks are rendered as markdown in the rule detail view. | ## Notification policy fields | Field | Type | Accepted values | Description | |-------------------------------|--------|-------------------------|------------------------------------------| | `notification_policies[].ref` | string | Format: `policies/` | Links a notification policy to the rule. | ## Duration format All duration fields accept the following units: | Unit | Example | Meaning | |------|---------|---------| | `s` | `30s` | Seconds | | `m` | `5m` | Minutes | | `h` | `1h` | Hours | | `d` | `7d` | Days |