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.