> [!CAUTION] > **Important:** All household members can see when these Routines run. Routines are for convenience only, not safety- or security-critical use cases. Do not create Routines that could result in injury or harm if they fail to start or stop. Routines can depend on working internet, Wi-Fi, and service availability from both Google and the third parties who manufacture the devices included in Routines. Routines may not always work, and Google is not responsible for any harm or losses incurred as a result of any failed Routines. ## Understand YAML [YAML](https://yaml.org/) 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](https://yaml.org/spec/1.1/). ### 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. ```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: ```yaml name: 'TV on lights off' name: "TV on lights off" ``` Incorrect quoting (mismatched quotes): ```yaml 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](https://yaml.org/spec/1.1/#id858081). ```yaml 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`): ```yaml 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. ```yaml 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. ```yaml 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*. ```yaml # 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](https://developers.home.google.com/automations/schema/basics.md.txt#string)* | Optional. Name of the automation. This is not shown to users, it is for developer reference only. | | `starters` | *\[[Starter](https://developers.home.google.com/automations/schema/reference/standard/starter.md.txt)\]* | Required. A list of starters. | | `condition` | *[Condition](https://developers.home.google.com/automations/schema/reference/standard/condition.md.txt)* | Optional. Condition. | | `actions` | *\[[Action](https://developers.home.google.com/automations/schema/reference/standard/action.md.txt)\]* | Required. A list of actions. | The [Reference](https://developers.home.google.com/automations/schema.md.txt) 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. ```yaml # 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](https://developers.home.google.com/automations/schema/reference/entity/sht_device/on_off_state) 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: ```yaml # 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]`. ```yaml # 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](https://developers.home.google.com/automations/schema/basics.md.txt#strings). | | 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`
| | User | A user's email address. | ### Color Colors may be specified in one of three ways - using either the [ColorHex](https://developers.home.google.com/automations/schema/basics.md.txt#colorhex) or [ColorTemperature](https://developers.home.google.com/automations/schema/basics.md.txt#colortemperature) primitive types, or the compound type [SpectrumHSV](https://developers.home.google.com/automations/schema/basics.md.txt#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. ```yaml # The 'is' field accepts a number type. type: device.state.Volume device: My TV - Living Room state: currentVolume is: 1 ``` ```yaml # 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`. ```yaml # 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. ```yaml # 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: ```yaml 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: ```yaml actions: - type: device.command.ColorAbsolute devices: My Device - Room Name color: name: blue ```