YAML Style Guide
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.
#
YAMLThis section is about basic YAML usage, and thus not Home Assistant specific.
#
IndentationAn indentation of 2 spaces must be used.
#
BooleansWe 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 true
and false
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., y
, n
,
yes
, no
, on
, off
and similar).
#
CommentsAdding 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
comment hash #
and the start of the comment.
#
SequencesSequences 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 sequencesBlock style sequences need to be indented under the key they belong to.
#
Flow style sequencesThe 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:
#
MappingsMappings 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 valuesNull values should be implicitly marked. The use of explicit null values should
be avoided (~
and null
).
#
StringsStrings are preferably quoted with double quotes ("
).
#
Multi-line stringsAvoid 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)
is allowed.
#
Additional string guidanceThe Home Assistant YAML section, provides additional guidelines on how to handle strings in Home Assistant configuration examples.
#
Home Assistant YAMLWithin 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.
#
Default valuesA 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
list []
by default.
#
Strings (continued)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.,
binary_sensor.motion
) - Entity attributes (e.g.,
temperature
) - Device IDs
- Area IDs
- Platform types (e.g.,
light
,switch
) - Condition types (e.g.,
numeric_state
,state
) - Trigger platforms (e.g.,
state
,time
) - Service names (e.g.,
light.turn_on
) - Device classes (e.g.,
problem
,motion
) - Event names
- Values that accept a limited set of possible, hardcoded values.
For example,
mode
in automations.
#
Service targetsIf 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.
#
Properties that accept a scalar or a list of scalarsHome 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.
#
Properties that accept a mapping or a list of mappingsHome Assistant has properties that accept both a mapping or a list of mappings.
Well known examples are: condition
, action
, sequence
.
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.
#
TemplatesHome 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.
#
Quoting styleTemplates are strings, and thus are double-quoted. As a result of that, single quotes should be used inside the template.
#
Template string lengthLong 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.
#
Short style condition syntaxPrefer shorthand style templates over-expressive format, as they provide a cleaner syntax.
#
FiltersSpacing around the filter pipe marker |
is required. If this makes
readability unclear, the use of additional parentheses is recommended.
#
Accessing states & state attributesWe 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
states('sensor.temperature')
.
This applies to states()
, is_state()
, state_attr()
and is_state_attr()
,
to avoid errors and error messages when the entity isn’t ready yet
(e.g., during Home Assistant startup).