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.

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.

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.

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`.

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.

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.

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.

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.

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.

Field	Type	Accepted values	Description
`notification_policies[].ref`	string	Format: `policies/<id>`	Links a notification policy to the rule.

All duration fields accept the following units: