In addition to our general documentation standards, we also have a set of standards for documenting snippets of YAML. The standards described on this page, apply to all our YAML based code across the project, with the main focus on documentation.
Our YAML standards provide our end-users with a consistent look, the best practices and a uniform approach for solving problems in YAML.
This section is about basic YAML usage, and thus not Home Assistant specific.
An indentation of 2 spaces must be used.
We should avoid the use of truthy boolean values in YAML. They often throw
off people new to YAML. Therefore, we only allow the use of
as boolean values, in lower case.
This keeps it compatible with the YAML 1.2 specifications as well, since that
version dropped support for several unquoted truthy booleans (e.g.,
off and similar).
Adding comments to blocks of YAML can really help the reader understand the example better.
The indentation level of the comment must match the current indentation level. Preferably the comment is written above the line the comment applies to, otherwise lines may become hard to read on smaller displays.
Comments should start with a capital letter and have a space between the
# and the start of the comment.
Sequences in YAML are also known as lists or arrays. In the Home Assistant world, we refer to them as lists in end-user documentation. This originates from the Python language the Home Assistant core is developed in.
Sequences can be written in two different styles; block and flow style. We prefer the use of block style sequences.
Block style sequences need to be indented under the key they belong to.
The use of flow style should be avoided. While simple, short and clean, with longer data in it, it becomes harder to read.
If used, flow style sequences have space after each comma
, and no white
space before opening and closing:
Mappings in YAML are also known as associative arrays, hash tables, key/value pairs, collections or dictionaries. In the Home Assistant world, we refer to them as mappings in end-user documentation.
Mappings can be written in different styles, however, we only allow the use of block style mappings. Flow style (that looks like JSON) is not allowed.
Null values should be implicitly marked. The use of explicit null values should
be avoided (
Strings are preferably quoted with double quotes (
Avoid the use of
\n or other new line indicators in YAML configuration when
possible. The same applies to avoiding long, single line, strings.
Instead, make use of the literal style (preserves new lines) and folded style (does not preserve new lines) strings.
In the examples above the no chomping operators are used (
>). This is
preferred, unless the example requires a different handling of the ending new
line. In those cases the use of the strip operator (
>-: no trailing new
line, any additional new lines are removed from the end) or keep operator
|-: trailing new line, and keep all additional new lines from the end)
The Home Assistant YAML section, provides additional guidelines on how to handle strings in Home Assistant configuration examples.
Within Home Assistant, we also have some things that can be done in different ways, while still adhering to the above set styling. This part is here to take care of that.
A configuration option using a default value, should not be part of the example. Unless, the example is specifically for educating about that option.
For example, our
condition options in automations, is optional and an empty
 by default.
As written in the first chapter, strings are preferably enquoted with double quotes. However, the following value types are exempted from this rule, as is makes our examples more readable:
- Entity IDs (e.g.,
- Entity attributes (e.g.,
- Device IDs
- Area IDs
- Platform types (e.g.,
- Condition types (e.g.,
- Trigger platforms (e.g.,
- Service names (e.g.,
- Device classes (e.g.,
- Event names
- Values that accept a limited set of possible, hardcoded values.
If you want to fire a service call for an entity ID (for example, to turn on a light), you can do so in three different ways.
The entity ID can be specified as a property of the service level, part of the data that is sent in the service call or as an entity in a service target.
Service targets is the most modern way and allows one to target a service call for an entity, device or area. Therefore, the target is the most flexible of the options available and is the one that should be used.
Home Assistant has a lot of places that access both a scalar value or a list of scalar values. Additionally, sometimes, it even accepts a comma-separated string value as a list.
The following applies in case a single value or a list of scalar values is accepted:
- Putting multiple values in a single scalar value (comma separated string) must not be used.
- If a list is used, it must be block style.
- A list with a single scalar value should not be used.
- The use of a single scalar value is allowed.
Home Assistant has properties that accept both a mapping or a list of mappings.
Well known examples are:
In case a property accepts a single mapping or a list of mappings, a list of mappings must be used, even when a single mapping is passed in.
This makes it easier to understand that one can add more items to it and also easier to copy and paste a single item into your own code.
Home Assistant templates are powerful, but they can be really confusing or hard to understand for a less experienced user. Therefore, the use of templates should be avoided if a pure YAML version is available.
Additionally, the use of templates requires additional escaping in our documentation to avoid our website code to confuse it for the Liquid syntax. Avoiding templates in general removes the need of additional escaping.
Templates are strings, and thus are double-quoted. As a result of that, single quotes should be used inside the template.
Long lines in templates should be avoided and split across multiple lines to make more clear what happens and keep them readable.
See the chapters on strings above for additional information on multi-line string formatting.
Prefer shorthand style templates over-expressive format, as they provide a cleaner syntax.
Spacing around the filter pipe marker
| is required. If this makes
readability unclear, the use of additional parentheses is recommended.
We do not allow the use of the states object directly if a helper method is available.
For example; don't use
states.sensor.temperature.state, instead use
This applies to
to avoid errors and error messages when the entity isn’t ready yet
(e.g., during Home Assistant startup).