YAML Formatting Guide#

This document outlines some basic formatting guidelines which may be useful for those who are new to YAML.

Single-Line or Multi-Line#

When writing an action, you can either use single-line or multi-line syntax.

  # Multi-Line Example
- !registryValue:
  path: 'HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System'
  value: 'dontdisplaylastusername'
  type: REG_DWORD
  data: '1'

  # Single-Line Example
- !registryValue: {path: 'HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System', value: 'dontdisplaylastusername', type: REG_DWORD, data: '1'}

Both are valid options, and will function the same. However, if you have a large amount of actions, it usually makes the most sense to go with single-line syntax.

There are some occassions where multi-line makes more sense, particularly if you have a lot of properties attached:

- !run:
  exeDir: true
  exe: "firefox-setup.exe"
  weight: 70
  option: "software"
  cpuArch: "x64"

In this example, we have many properties attached, including option and weight. Merging it into a single line would make it harder to distinguish between each property.

Double or Single Quotes#

YAML allows for two ways of quoting text, either with double quotes or single quotes.

Using double quotes means that certain characters such as \ are interpreted differently, which will cause errors if they are not escaped. For 99% of use cases, this functionality is useless, and can cause confusion.

  # Backslashes must be escaped
- !registryKey:
  path: "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System"

  # Backslashes do not have to be escaped
- !registryKey:
  path: 'HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System'

We strongly recommend using single quotes, as doing so causes the text to be interpreted literally. Just make sure to double up on any more single-quotes inside.