Appendix · YAML

YAML Basics

Indentation, lists vs maps, anchors - the YAML pitfalls that bite ESPHome users.

YAML is whitespace-sensitive. Almost every ESPHome compile error comes from indentation or list/map confusion. This page covers the four traps that catch most newcomers.

1. Indentation: spaces only, two at a time

✓ Correct

yaml

wifi:
  ssid: "MyNet"
  password: "shhhh"

api:
  encryption:
    key: !secret api_key

✗ Broken

yaml

wifi:
ssid: "MyNet"          # ❌ same level as wifi
   password: "shhhh"   # ❌ 3 spaces, inconsistent

api:
  encryption:
   key: !secret api_key  # ❌ 3 spaces under encryption

Never use tabs. ESPHome will refuse to parse a YAML with tabs. Configure your editor to insert 2 spaces.

2. Lists vs Maps

A leading - creates a list item. ESPHome blocks like sensor:, switch:, binary_sensor: are lists - multiple items, each with a platform:. Blocks like wifi:, api:, esphome: are maps - single key/value collection.

yaml

# A LIST (sequence) - items prefixed with -
sensor:
  - platform: dht
    pin: GPIO15
  - platform: bmp280_i2c
    address: 0x76

# A MAP (mapping) - key: value pairs
wifi:
  ssid: "MyNet"
  password: "shhhh"

3. Substitutions and anchors

ESPHome adds substitutions: on top of standard YAML - string templating with ${'#39;}{name} syntax. For repeated chunks of config, use raw YAML anchors (&name / *name).

yaml

# Define an anchor with &
substitutions:
  device_name: living-room

# Reference it with $
esphome:
  name: ${device_name}

# YAML anchors for repeated chunks
.shared_font: &big_font
  text_font: montserrat_28
  align: CENTER

lvgl:
  pages:
    - widgets:
        - label:
            text: "Hi"
            <<: *big_font
        - label:
            text: "Bye"
            <<: *big_font

4. When to quote strings

yaml

# Numbers don’t need quotes
update_interval: 30s

# Strings with special characters NEED quotes
ssid: "My!Network#42"

# Yes/No/On/Off without quotes are booleans
hidden: true              # boolean
hidden: "true"            # string

# Leading zeros lose meaning unquoted
phone: 0123456789         # ❌ becomes octal/integer
phone: "0123456789"       # ✓ string

Quote anything that looks ambiguous: leading zeros, special characters (!, #, @), words that could be booleans (yes, no, on, off).