Home Assistant automation YAML syntax, with a complete example

Learn the structure of one automation, modern key names, indentation, and where to paste the result.

An automation is a structured document describing when Home Assistant should react, what must be true, and what it should do. YAML is the text format used to express that structure. Learning a few conventions makes generated output easier to review and small repairs easier to make. Start with one complete automation rather than a collection of unrelated fragments.

Read the top-level mapping

The alias is the human-readable name and description explains the intent. The triggers list defines events that can start a run. The conditions list defines checks made before the actions proceed. The actions list contains the work to perform. Finally, mode describes what happens if a new run starts while an earlier run is active. An empty conditions list is valid and makes the absence of extra checks explicit.

Use modern names consistently

Current examples use triggers, conditions, and actions at the top level. Each trigger names its type with trigger, while an action call uses action with a value such as light.turn_on. Older examples may instead use singular top-level names, platform for trigger types, and service for calls. These older forms appear in many working installations. When updating a document, change the relevant structural keys carefully rather than replacing every matching word in the file.

A starting-point automation

Every entity ID below is an example. Replace it with your actual entity ID and review all settings before use.

alias: Desk light at evening time
description: Turn on the desk light at 19:00 each day.
triggers:
  - trigger: time
    at: "19:00:00"
conditions: []
actions:
  - action: light.turn_on
    target:
      entity_id: light.desk
mode: single

Indent by structure, not appearance

Spaces indicate nesting. A dash introduces a list item; the properties beneath that item align with one another. Use spaces rather than tabs and keep the indentation consistent. The entity_id under target belongs to the target mapping, while message under data is action data. If those lines move to the wrong level, the YAML may still parse but mean something different. Parsing is useful validation, but it does not prove Home Assistant accepts the configuration.

Quote values that could be ambiguous

Quote states such as "on" and "off", clock times, and durations. Entity IDs are usually plain strings such as light.desk. Display names are not interchangeable with entity IDs. A template is another language embedded inside YAML, so quote simple template strings or use a block scalar for a longer expression. Do not paste account secrets into generated examples. Replace placeholders with IDs you have inspected in your own installation.

Paste into the correct editor

For one automation, open Settings, then Automations, create or open the relevant automation, and choose the three-dot menu followed by Edit in YAML. Paste the mapping without an outer automation key. A hand-maintained automations.yaml file normally contains a list of automations, so its outer structure differs. Back up existing content before replacing it and keep any existing id you deliberately need for an established automation.

Validate behavior after syntax

Save the automation and read any validation message. Check the target action independently, then cause a real trigger and inspect its trace. The Run actions command can help test actions, but it does not reproduce a real trigger or necessarily evaluate the same conditions. Give the automation a clear name so its trace is easy to find later. Keep a short description of timing and exceptions alongside it as the rule evolves.

Keep changes small and reversible

Store a copy of the last working version before changing nested logic. Update the description when behavior changes so the visible name and the YAML tell the same story. If an edit fails, restore that copy and try a smaller change. Avoid combining a syntax cleanup, renamed entities, new conditions, and a different mode in one step. A compact rule with an observed test result gives you a dependable base for adding the next useful feature without losing track of what previously worked.

Further reference: official Home Assistant documentation.