Language Basics

Understanding YAML

YAML is a popular language used to specify software configuration. It provides a simple, clear, human-readable way to represent structured information. Here are a few basic things you will need to learn 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 example below, 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 simple 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"

Nesting 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 example below, 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 Automation script syntax is called the schema.

The Automation 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.

Let's take the automation Struct, for example, 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, etc.
  • 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.

In the description of each Field you'll find important information, including:

  • Required vs 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 need to provide certain information. For instance, a starter Struct can represent a time schedule-based starter, or a device state change-based starter. 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 do not 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 above. 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/F to denote temperature datum.

  • 20.5C
  • 90F
ColorTemperature

Color temperature in Kelvin.

  • 5000K

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

Variables

You can create a variable and assign it with a value of type primitive, an entity, or an array.

Then the variable can be used wherever the same data type is accepted.

Variables are defined in the input Struct.

Input

The input Struct is where you define input variables. Variables are typically used to reference:

  • a device or list of devices, or
  • a value or list of values.

The input Struct contains one or more entries, each of which defines a single input variable.

The key of an input entry field is the input variable name. The input variable name can be used like a global variable elsewhere in the script.

The first Struct in each input entry is metadata, which names and describes the input. The second Struct is selector, which defines which UI component to use when the template is converted to an instance script, when the input values are configured. Each selector defines the data type of the input variable.

In the example input Struct below, light is a variable name created by the script writer:

input:
  light:
    metadata:
      name: light
      description: select light
    selector:
      type: device
      supportedTypes:
      - LIGHT
      - SWITCH

Variables defined in the input block may be used elsewhere in the script, and are referenced by preceding the variable name with a $ like this: $light.

supportedTypes is a list of one or more device types that may be used wherever the light variable is referenced in the script. In this example, the light variable represents a light or switch device. supportedTypes informs the automation script editor which devices to suggest in autocomplete, and which devices to flag as inapplicable.