YAML Syntax

We use YAML because it is easier for humans to read and write than other commondata formats like XML or JSON. Further, there are libraries available in mostprogramming languages for working with YAML.

You may also wish to read Working With Playbooks at the same time to see how thisis used in practice.

For Ansible, nearly every YAML file starts with a list.Each item in the list is a list of key/value pairs, commonlycalled a “hash” or a “dictionary”. So, we need to know howto write lists and dictionaries in YAML.

There’s another small quirk to YAML. All YAML files (regardless of their association with Ansible or not) can optionallybegin with and end with …. This is part of the YAML format and indicates the start and end of a document.

All members of a list are lines beginning at the same indentation level starting with a "- " (a dash and a space):

A dictionary is represented in a simple key: value form (the colon must be followed by a space):

# An employee record
martin:
    name: Martin D'vloper
    job: Developer
    skill: Elite

More complicated data structures are possible, such as lists of dictionaries, dictionaries whose values are lists or a mix of both:

# Employee records
-  martin:
    name: Martin D'vloper
    job: Developer
    skills:
      - python
      - perl
      - pascal
-  tabitha:
    name: Tabitha Bitumen
    job: Developer
    skills:
      - lisp
      - fortran
      - erlang

Dictionaries and lists can also be represented in an abbreviated form if you really want to:

---
martin: {name: Martin D'vloper, job: Developer, skill: Elite}
fruits: ['Apple', 'Orange', 'Strawberry', 'Mango']

These are called “Flow collections”.

Ansible doesn’t really use these too much, but you can also specify a boolean value (true/false) in several forms:

create_key: yes
needs_agent: no
knows_oop: True
likes_emacs: TRUE
uses_cvs: false

            exactly as you see
            will appear these three
            lines of poetry
 
fold_newlines: >
            this is really a
            single line of text
            despite appearances

While in the above > example all newlines are folded into spaces, there are two ways to enforce a newline to be kept:

Let’s combine what we learned so far in an arbitrary YAML example.This really has nothing to do with Ansible, but will give you a feel for the format:

---
# An employee record
name: Martin D'vloper
job: Developer
skill: Elite
employed: True
foods:
    - Apple
    - Orange
    - Strawberry
    - Mango
languages:
    perl: Elite
    python: Elite
    pascal: Lame
education: |
    4 GCSEs
    3 A-Levels
    BSc in the Internet of Things

That’s all you really need to know about YAML to start writing Ansible playbooks.

Gotchas

While you can put just about anything into an unquoted scalar, there are some exceptions.A colon followed by a space (or newline) : # starts a comment.

Because of this, the following is going to result in a YAML syntax error:

foo: somebody said I should put a colon here: so I did
 
windows_drive: c:

…but this will work:

windows_path: c:\windows

You will want to quote hash values using colons followed by a space or the end of the line:

 
windows_drive: 'c:'

…and then the colon will be preserved.

Alternatively, you can use double quotes:

foo: "somebody said I should put a colon here: so I did"
 
windows_drive: "c:"

The difference between single quotes and double quotes is that in double quotesyou can use escapes:

The following is invalid YAML:

foo: "an escaped \' single quote"

Further, Ansible uses “{{ var }}” for variables. If a value after a colon startswith a “{“, YAML will think it is a dictionary, so you must quote it, like so:

foo: "{{ variable }}"

If your value starts with a quote the entire value must be quoted, not just part of it. Here are some additional examples of how to properly quote things:

foo: "{{ variable }}/additional/string/literal"
foo2: "{{ variable }}\\backslashes\\are\\also\\special\\characters"
foo3: "even if it's just a string literal it must all be quoted"

Not valid:

foo: "E:\\path\\"rest\\of\\path

In addition to ' and " there are a number of characters that are special (or reserved) and cannot be usedas the first character of an unquoted scalar: [] {} > | * & ! % # ` @ ,.

You should also be aware of ? : -. In YAML, they are allowed at the beginning of a string if a non-spacecharacter follows, but YAML processor implementations differ, so it’s better to use quotes.

In Flow Collections, the rules are a bit more strict:

a scalar in block mapping: this } is [ all , valid
 
flow mapping: { key: "you { should [ use , quotes here" }

Boolean conversion is helpful, but this can be a problem when you want a literal yes or other boolean values as a string.In these cases just use quotes:

YAML converts certain strings into floating-point values, such as the string1.0. If you need to specify a version number (in a requirements.yml file, forexample), you will need to quote the value if it looks like a floating-pointvalue:

version: "1.0"

YAML Syntax

YAML Syntax

Gotchas

ansible IRC chat channel and #yaml for YAML specific questions