YAML documentation formatting and standards

[frenck]

Context

Across the documentation, there is a wild different use of standards when writing YAML. Especially newer users might get confused by "older" methods (e.g., things we needed templates for back in the day). But also different ways to write YAML in the same way.

Proposal

I want to make an effort into making it look consistent and "best" practice for the end-users.

Some goals:

• Have a consistent style.
• Avoid confusion between different YAML scalar types.
• Show best practices for both YAML & Home Assistant usage.
• Some things in Home Assistant can be done in more ways, pick the best one.

YAML

Basic YAML usage; no specific rules for our features. This is fully compatible with the styling Prettier applies.

• Indentation of 2 spaces.

  # Good
  example:
    one: 1
  
  # Bad
  example:
      bad: 2

• Only allow for true and false (lower case) for YAML booleans, no truthy values.
  This keeps it compatible with YAML 1.2 (that dropped support for several unquoted; y/n/yes/no/on and similar). Additionally, it helps to avoid confusion with on, or no for people from Norway.

  # Good
  one: true
  two: false
  
  # Bad
  one: True
  two: on
  three: yes

• Comments must match the current indentation level.

  # Good
  example:
    # Comment
    one: true
  
  # Bad
  example:
  # Comment
    one: false

• Block style sequences, must be indented under the key.

  # Good
  example:
    - 1
    - 2
    - 3
  
  # Bad
  example:
  - 1
  - 2
  - 3

• Flow style sequences have space after each comma , and no white space before opening and closing:

  # Good
  example: [1, 2, 3]
  
  # Bad
  example: [ 1,2,3 ]
  example: [ 1, 2, 3 ]
  example: [1,2,3]

  The use of flow style should be avoided, while the above example is simple, short and clean. With longer data in it, it becomes long and harder to read quickly.

• Mappings must be block style, flow style mappings should not be used,

  # Good
  example:
    one: 1
    two: 2
  
  # Bad
  example: { one: 1, two: 2 }

• Null values should be implicitly marked.

  # Good
  example:
  
  # Bad
  example: ~
  example: null

• Strings are preferably quoted with double quotes (")

  # Good
  example: "Hi there!"
  
  # Meh...
  example: Hi there!
  
  # Bad
  example: 'Hi there!'

Home Assistant specific YAML

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.

Basics

• String are double quoted. Exempted from this rule are:

  • Entity IDs
  • Entity attributes
  • Device IDs
  • Area IDs
  • Condition types (e.g., numeric_state, state)
  • Trigger platforms (e.g., state, time)
  • Service names (e.g., light.turn_on)
  • Event names
  • Values that accept a limited set of possible, hardcoded values.
    For example, mode in automations.

  # Good
  action:
    - service: notify.frenck
      data:
        message: "Hi there!"
    - service: light.turn_on
      target:
        entity_id: light.office_desk
        area_id: living_room
      data:
        transition: 10
  
  # Bad
  action:
    - service: "notify.frenck"
      data:
        message: Hi there!

• Default values should not be part of the YAML.

  # Good
  - alias: "Test"
     trigger:
       -  platform: state
           entity_id: binary_sensor.motion
  
  # Bad
  - alias: "Test"
     trigger:
       -  platform: state
           entity_id: binary_sensor.motion
     condition: []

Service targets

If you want to fire a service call towards 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 towards service call or as an entity in a service target.

This is confusing for some and had lead to different topics on the forum, issues, and completely different usages across the documentation.

Service targets have been introduced recently, as part of Blueprints and allow one to target a service call towards an entity, device or area. And is, therefore, the most flexible of the options available.

The suggestion is to adjust all documentation to use this consistently.

# Good
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room
  - service: light.turn_on
    target:
      area_id: light.living_room
  - service: light.turn_on
    target:
      area_id: living_room
      entity_id: light.office_desk
      device_id: 21349287492398472398

# Bad
action:
  - service: light.turn_on
    entity_id: light.living_room
  - service: light.turn_on
     data:
       entity_id: light.living_room

Properties that accept a scalar or a list of scalars

We have a lot of places that access both a scalar value or a list of scalar values, additionally, sometimes, we even accept a comma-separated string value as a list.

• Putting multiple values in a single scalar value (comma separated string) must not be used.
• The use of a single scalar value is allowed.
• A list with a single scalar value should not be used.
• If a list is used, it must be block style.

# Good
entity_id: light.living_room
entity_id:
  - light.living_room
  - light.office

# Bad
entity_id: light.living_room, light.office
entity_id: [light.living_room, light.office]
entity_id:
  - light.living_room

Properties that accept a mapping or a list of mappings

Additional to the lists above, we also have 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 mapping must be used. Even when a single mapping is passed in.

This makes it easier to understand one can add more items to it and easier to copy and paste a single item into your own code.

# Good
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room

# Bad
action:
  service: light.turn_on
  target:
    entity_id: light.living_room

Templates

The use of templates should be avoided. If there is a pure YAML version available, this should be used. It is easier to follow for the less technical user.

It also removes the need for escaping it from the liquid template engine our website uses.

# Good
condition:
  - condition: numeric_state
    entity_id: sun.sun
    attribute: elevation
    below: 4

# Bad
condition:
  - condition: template
    value_template: "{{ state_attr('sun.sun', 'elevation') < 4 }}"

Additionally, long lines in templates should be avoided and split across multiple lines to make more clear what happens.

# Good
value_template: >-
  {{
    is_state('sensor.bedroom_co_status', 'Ok')
    and is_state('sensor.kitchen_co_status', 'Ok')
    and is_state('sensor.wardrobe_co_status', 'Ok')
  }}

# Bad
value_template: "{{ is_state('sensor.bedroom_co_status', 'Ok') and is_state('sensor.kitchen_co_status', 'Ok') and is_state('sensor.wardrobe_co_status', 'Ok') }}"

Finally, prefer shorthand style templates over-expressive format, as they
provide a cleaner syntax.

# Good
condition:
  - "{{ some_value == some_other_value }}" 

# Bad
condition:
  - condition: template
    value_template: "{{ some_value == some_other_value }}"

We do not allow the use of the states object directly if a helper method is available. For example now allowing 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 message when the entity isn’t ready yet (e.g., during Home Assistant startup).

Spacing around the filter pipe marker | is required. If this makes readability unclear, the use of additional parentheses is recommended.

# Good
condition:
  - "{{ some_value | float }}" 
  - "{{ some_value == (some_other_value | some_filter) }}" 

# Bad
condition:
  - "{{ some_value == some_other_value|some_filter }}" 

Finally, templates are strings, and thus are double-quoted. As a result of that, single quotes should be used inside the template.

# Good
condition:
  - "{{ 'some_value' == some_other_value }}" 

# Bad
condition:
  - '{{ "some_value" == some_other_value }}'

Consequences

Tons of examples to adjust, but at least we have something to hold on to.

[frenck]

Ok, so the above might be missing things and I might be a bit opinionated (in general I tried to stick with what Prettier does for general formatting).

For Home Assistant it would be nice to know if this covers it all, or if one thinks it should be documented differently. Mainly... well... there are so many ways to do things 🤷

[thomasloven]

Good stuff!

The null value marker is a unique and confusing syntax element. If it's recommended, I suggest to use null instead, because that's more clear. However; I would argue argue against this rule because it means the marker will have to be removed if additional options are added to a property that earlier had none.

E.g. going from

frontend: ~

to

frontend:
  themes: !include_dir_merge_named my_themes

The risk is that the removal of ~ (or null) will have to be explained or reminded about for each instance in the documentation.

[DubhAd]

Given that ~ is used in MQTT Discovery to mark the base topic, using it here to mean nothing could lead to confusion. Not to say that null won't confuse some, but it should be easier to explain and understand.

[frenck]

looks like example is explicitly disabled, while the opposite would likely be true...

Yes, that is why I like ~...

[thomasloven]

That's what I meant. I retract my claim that null is better than ~.

[raman325]

FWIW this is the first time I've learned that ~ can be used in place of null

[frenck]

Updated OP to reflect the discussion in this subthread.

[thomasloven]

A consideration about the service targets.

I've taken to give all my examples in discord with entity_id within the service data, because of how /developer-tools/service works. Selecting a target entity there will put the entity in the service data field, and after adding additional parameters and testing that the service call does what you want, it's easy to just copy everything from that box and paste it into your automation.

I worry that this may cause more confusion than it cures - with the way dev-service works today.

[frenck]

I agree, I think we need to look into how service calls work in the developer tools, to see if we can make it target aware for service implemented as an entity service.

I'm not sure if I would let that block a direction to go into.

[frenck]

So some real quick off-github discussion and a bit off-topic for this proposal may be:

How about we added selectors to the service.yaml schema's... And add support for the target UI thing in the developer tools?

In general, the dev tools need some love there (for example, templates don't work in data of service calls).

[raman325]

I had proposed some additional keys in services.yaml to accomplish the same thing: https://github.com/home-assistant/architecture/issues?q=is%3Aissue+author%3Araman325+is%3Aclosed

selector seems like a good idea as an alternative since it's already in use, I only mention it to say that I like your idea of giving dev tools more TLC

[tomlut]

The use of templates should be avoided.

Does this extend to using the choose: action over using jinja if/else templates?

Style suggestions I have read elsewhere:

No spacing around the filter pipe marker | this makes it more obvious when people attempt to round a number at the end of an expression rather than the full expression.

# Good
condition:
  - "{{ some_value == some_other_value|some_filter }}" 

# Bad
condition:
  - "{{ some_value == some_other_value | some_filter }}" 

Single quotes inside double quotes:

# Good
condition:
  - "{{ 'some_value' == some_other_value }}" 

# Bad
condition:
  - '{{ "some_value" == some_other_value }}'

[frenck]

Does this extend to using the choose: action over using jinja if/else templates?

Yes. There is no specific exception made for any of that in the proposal above.

Single quotes inside double quotes:

This is covered in the current text of the proposal, as: String are double quoted, which covers templates (as they are strings). Nevertheless, the example is good, so adding that for clarity 👍

No spacing around the filter pipe marker | this makes

Good catch! That isn't covered by the current proposal indeed.

I'm on the same boat as @pvizeli, spacing helps with readability.

this makes it more obvious when people attempt to round a number at the end of an expression rather than the full expression

That is usually a result of writing readable in general. E.g., using extra parentheses or newlines.

condition:
  - "{{ some_value == (some_other_value | some_filter) }}" 

Anyone else? Yes/no spaces around the pipe (|) marker?

[Jc2k]

I've always found Jinja's pipe syntax hard to read. But I think I find with spaces to be slightly more readable and consistent.

[TomBrien]

I would say with space. I don't think there are any other operators (ok pipe isn't really an operator) which we are saying no space for

[frenck]

Spaces seem to be the consensus, so will add that 👍

[frenck]

Updated OP to reflect the discussion in this subthread.

[frenck]

OK, so I'm left with the null/~/ (nothing) dilemma on the nulling of things.

So let`s do this poll style.

React with 👀 for:

sensors:

React with 🚀 for

sensors: ~

React with 🎉 for

sensors: null

For some reasoning/views/perspectives on this; read this thread:
#495 (comment)

[frenck]

Alright implicit null style apparently it is 👍

Updated OP to reflect the discussion in this subthread.

[frenck]

PR finalizing this architectural discussion:

home-assistant/developers.home-assistant#802

[tomlut]

One thing that has been mentioned in the forums a couple of times this week is that target: does not support templating.

So this wont work:

  - service: light.turn_on
    target:
      entity_id: "{{ some_template }}"

It has to be:

  - service: light.turn_on
    data:
      entity_id: "{{ some_template }}"

I this a documentation issue or should I raise a core issue for templating support in target:?

[frenck]

That has been fixed and lands in 2021.3