Language Basics

Understand YAML

YAML is a popular language used to specify software configuration. It provides a clear, human-readable way to represent structured information. Here are a few basic things you need to understand about YAML before you create your first scripted automation. To learn more about YAML in general, see the Version 1.1 specification.

Key-value pairs

YAML documents are basically a collection of key-value pairs. In the following example, the key is name and the value is TV on lights off. Key and value are delimited by a colon followed by a space. Both characters are required for well-formed YAML.

name: TV on lights off

Values

The value associated with a key can be as basic as a string, a number, or a date, or as complex as another collection of key-value pairs.

Strings

If a string value starts with one of the following characters: [, {, ", ' or #, or the string contains : (a colon followed by spaces), it must be quoted.

Both single- and double-quotes are accepted, but the closing quote must match the opening quote.

Correct quoting:

name: 'TV on lights off'

name: "TV on lights off"

Incorrect quoting (mismatched quotes):

name: 'TV on lights off"

Quotes are optional for all other types of strings.

If you need a multi-line string, see the YAML specification section on multi-line scalars.

name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"

Nested key-value pairs

Here the value of the key metadata is a list of two key-value pairs (name and description):

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

Indentation

YAML uses indentation to denote structure. In the previous example, name and description are indented (by two spaces) to denote that these are the children of the key metadata.

Indentation is strict in YAML. A child structure must have deeper indentation than its parent, and same level key-value pairs must have same indentation.

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

Multiple values

If a given key has multiple values, each value is listed in a new line and each line begins followed by a dash and a space. In the following example, there are two lists:

  1. An automation can have multiple starters and hence the first starter begins with a dash and a space.
  2. weekday can have multiple values and hence, each value is further indented and begins with a dash and a space.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Comments

Any text following a # is considered to be a comment and is ignored by the automation engine.

A line beginning with # is a comment.

A comment may appear on the same line as script content, but the # must be preceded by a space.

# This is a comment. It will be ignored.
name: chromecast #This is a TV.

Automation script

The specification for the Automations script syntax is called the schema.

The Automations schema defines a couple of data structures:

  • A single key-value pair is called a Field.
  • A collection of fields defined by the schema is called a Struct.

Struct

The automation scripting language defines several standard 'blocks' or data structures, referred to as Structs.

Take a look at the automation Struct, which defines four fields:

Key Type Description

name

String

Optional.

Name of the automation.

This is not shown to users, it is for developer reference only.

starters

[Starter]

Required.

A list of starters.

condition

Condition

Optional.

Condition.

actions

[Action]

Required.

A list of actions.

The Reference section provides schema definitions for all available Structs.

Key names are unique within a given Struct and are case-sensitive.

Possible value types are:

  • A Primitive type: bool, number, string, time, and so forth.
  • A Struct type: a collection of fields.
  • An Array of the data type. Array is denoted by []. For example, [string] is an array of strings, and [Starter] is an array of Starter Structs.
  • Other special types: Entity, FieldPath.

The description of each Field contains important information, including:

  • Required versus Optional, indicating whether the field is mandatory or if it can be skipped.
  • Field Dependency. Only Optional Fields have Dependencies. This describes the additional checks when using this field, like Use Field B only if Field A is set, or When Field A is used, do not set Field B or Field C.
  • Possible Values. For example, the limited value set of an Enum Field of type string, or a range of numbers that may be used in a Field of type number.

Typed Struct

Some Structs can represent starters based on a time schedule or a device state change. Each type of starter must provide a distinct set of Fields.

# A time schedule starter.
starter:
  type: time.schedule
  at: 10:00

# A device state change starter.
starter:
  type: device.state.OnOff
  device: TV - Living Room
  state: on
  is: true

A starter is a Typed Struct, which is extended by other child Structs in the type Field, such as time.schedule or device.state.OnOff, to provide different functions. The condition and action Structs are also Typed.

Additional fields in the Struct must follow the child Struct (type) specification. For example, when using device.state.OnOff as the type, only the fields specified for that type are valid in that starter Struct.

Array

In YAML, an array of values begins with - (a dash followed by a space). The array can hold multiple Struct values, or multiple Primitive values. But the values in the array must be of the same type.

When the array contains a single item, you may omit the dash and space:

# The starters field accepts an array of Starter Structs.
# This is the standard format.
starters:
- type: time.schedule
  at: sunset
- type: time.schedule
  at: sunrise

# The dash can be omitted if the array only has one item.
# This is also valid.
starters:
  type: time.schedule
  at: sunset

Multidimensional arrays, like [[1, 2], [3, 4]], are not supported in automation scripting. The language parser will automatically flatten a multidimensional array into a single-dimension array, in this case, [1, 2, 3, 4].

# INVALID: multi-dimensional array
- - 1
  - 2
- - 3
  - 4

Primitive

The following primitive data types are supported by the Automations script schema:

Bool
  • true
  • false

Number

Integer or decimal number

String

Plain text

Strings don't need to be quoted except in specific cases.

Date

Month and Day. Format is MM-DD or MM/DD.

  • 09/01
  • 09-01

Time

Time of day. It can be clock time or solar time. For clock time, it can use either AM/PM format or 24H format. Seconds are optional. For solar time, sunrise and sunset are keywords, and may be followed by an offset (in Duration terms).

  • 12:30 am
  • 13:00:01
  • sunrise / sunset
  • sunset+30min / sunset-1hour

DateTime

Year, Month, Day and Time of the Day. Whitespace is required between the Date part and the Time part. Date format is YYYY-MM-DD or YYYY/MM/DD. Time format is same as [Time](#time). Time zone is not supported.

  • 2022/01/01 14:00
  • 2022-12-31 sunrise+30min

Weekday

  • MONDAY (or MON)
  • TUESDAY (or TUE)
  • WEDNESDAY (or WED)
  • THURSDAY (or THU)
  • FRIDAY (or FRI)
  • SATURDAY (or SAT)
  • SUNDAY (or SUN)

Duration

A period of time.

  • 30min
  • 1hour
  • 20sec
  • 1hour10min20sec
ColorHex

A six-digit hexadecimal code that represents a color.

There is no leading #.

  • FFFFFF
  • B5D2A1
  • DFA100
Temperature

Normal temperature data. Always add 'C' or 'F' to the value to denote a temperature measurement.

  • 20.5C
  • 90F
ColorTemperature

Color temperature in Kelvin.

  • 5000K

Color

Colors may be specified in one of three ways - using either the ColorHex or ColorTemperature primitive types, or the compound type SpectrumHSV.

SpectrumHSV

The SpectrumHSV type specifies a color using three numeric fields:

  • Hue corresponds to the color wavelength.
  • Saturation indicates the intensity of the color.
  • Value indicates the relative lightness or darkness of the color.

Dynamic

Sometimes, the data type of a key is not fixed. It can be one of the primitive types, based on the values from other fields.

An example of dynamic data type field is is. The actual type is determined by the values of both the type and state fields.

# The 'is' field accepts a number type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

# The 'is' field accepts a boolean type.
type: device.state.OnOff
device: My TV - Living Room
state: on
is: false

Entity

A special String format to uniquely identify a user-owned entity such device or room.

Device is the most common entity used in Automations. The entity String format is device name - room name.

# The device field accepts a Device Entity type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

FieldPath

A special String format used to locate a piece of data in a data payload. In the following example, currentVolume is the FieldPath for the state field.

# The state field accepts a FieldPath type.
starters:
  type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  is: 5

Other FieldPaths may require multiple levels to get to the required item, and the format differs between starter and action.

Starters use a dot notation, with the entire path in the same field. This is primarily done for comparison purposes in starter logic. For example, to use color temperature as a starter, you would use color.colorTemperature for the state:

starters:
- type: device.state.ColorSetting
  device: My Device - Room Name
  state: color.colorTemperature
  is: 2000K

Actions, however, use nested fields. To change the color of a bulb to blue, instead of color.name and is: blue, you must do:

actions:
- type: device.command.ColorAbsolute
  devices: My Device - Room Name
  color:
    name: blue