Skip to content

YAML built-in templating

Basics

YAML has built-in methods to cut the visual clutter in large YAML files.

It does that by the use of so called Anchors and Aliases. On top of that YAML provides Overrides and Extensions to tweak the Anchor functionality.

YAML Anchors and Aliases

Anchors and Aliases are YAML constructions that allow you to reduce repeat syntax and extend existing dictionaries. You can place Anchors (&) on an entity to mark a multi-line section. You can then use an Alias (*) and use that Anchor later in the YAML document to reference that section.

Basic example

Source
1
2
3
4
5
- &flag Apple       # The Anchor
- Beachball
- Cartoon
- Duckface
- *flag             # The Alias

When this list is read by the Home Assistant YAML parser, the value identified by the anchor (Apple) will be filled at the alias when the YAML is composed. The literal anchor (&) and alias (*) are discarded so they don’t appear in the final result.

Result
1
2
3
4
5
- Apple
- Beachball
- Cartoon
- Duckface
- Apple

More complex example

We can also define a dictionary as an Anchor, and re-use the complete dictionary on other locations:

Source
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
definitions: 
  steps:
    # The full step dict is the Anchor
    - step: &build-test
        name: Build and test
        script:
          - mvn package
        artifacts:
          - target/**

pipelines:
  branches:
    develop:
      - step: *build-test   # Re-use 
    master:
      - step: *build-test   # Re-use

When this dictionary is read by the YAML parser, the full dictionary will be filled.

Result
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
definitions: 
  steps:
    # The full step dict is the Anchor
    - step: &build-test
        name: Build and test
        script:
          - mvn package
        artifacts:
          - target/**

pipelines:
  branches:
    develop:
      - step:
          name: Build and test
          script:
            - mvn package
          artifacts:
            - target/**
    master:
      - step:
          name: Build and test
          script:
            - mvn package
          artifacts:
            - target/**

YAML Overrides and Extensions

You can also tweak the Anchor when called by entering <<: before the Alias. Below this, you can write any desired changes. Field/dicts are overridden if the new field/dict has the same name or is added afterward if different.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
definitions: 
  steps:
    - step: &build-test
        name: Build and test
        script:
          - mvn package
        artifacts:
          - target/**

pipelines:
  branches:
    develop:
      - step: *build-test
    master:
      - step: 
          <<: *build-test         # Re-use
          name: Testing on Master # override name field
          ongoing: false          # extension

Home Assistant will issue warnings if using overrides, as it thinks you are defining the same field twice

You can safely ignore those warnings 😄