---
title: YAML rule schema reference
description: Complete field reference for {{alerting-v2}} YAML rule definitions: required fields, metadata, schedule, grouping, state transitions, no-data handling, and duration format.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5528/explore-analyze/alerting/kibana-alerting-v2/rules/yaml-rule-schema-reference-v2
products:
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Unavailable
---

# YAML rule schema reference
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/5528/explore-analyze/alerting/kibana-alerting-v2/rules/create-rule-with-yaml-v2).

## 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


| 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 results. `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/<id>` | 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    |