Skip to content

Add documentation on triggers yaml #2884

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
joostlek wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Add documentation on triggers yaml #2884

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion docs/automations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,9 @@ from homeassistant.helpers.trigger import Trigger, TriggerActionRunner, TriggerC
from homeassistant.helpers.typing import ConfigType

_OPTIONS_SCHEMA = vol.Schema({
vol.Required("event_type"): cv.string,
vol.Required("behavior", default="any"): vol.In(
["first", "last", "any"]
),
})
Comment on lines 33 to 37
Copy link
Member Author

@joostlek joostlek Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like we should adapt this trigger to be more realistic, I'd love for the example YAML to adhere to the example trigger, but from the example it wasn't clear what event_type: str was used for

Copy link
Member

@abmantis abmantis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think we should have a single consistent example on this page. Lets update the class to represent a nicer trigger.


_CONFIG_SCHEMA = vol.Schema({
Expand Down Expand Up @@ -95,4 +97,31 @@ async def async_get_triggers(hass: HomeAssistant) -> dict[str, type[Trigger]]:
}
```

### Trigger schema

The frontend uses the `triggers.yaml` file to know the structure of the triggers.
Copy link
Member

@abmantis abmantis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The frontend uses the `triggers.yaml` file to know the structure of the triggers.
Triggers should have their description in a `triggers.yaml` file. The description specifies the structure of the triggers and is used by the frontend, for example.

it is also used on core, in the get_triggers_for_target websocket api, not only for frontend.

This file is similar to `services.yaml`.

For example, the following snippet shows a trigger that takes a target binary sensor with a specific device class and a select selector with a predefined set of options.
Copy link
Member

@abmantis abmantis Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For example, the following snippet shows a trigger that takes a target binary sensor with a specific device class and a select selector with a predefined set of options.
The following snippet shows a trigger that takes a target binary sensor with a specific device class and a select selector with a predefined set of options.

if we update the example class above, I think we can simplify this sentence since it is part of the full example in the current top section.


```yaml
occupancy_cleared:
target:
entity:
domain: binary_sensor
device_class: presence
fields:
behavior:
required: true
default: any
selector:
select:
translation_key: trigger_behavior
options:
- first
- last
- any
```