2018-03-14 19:44:21 +00:00
.. _yaml_syntax:
2012-03-11 19:34:21 +00:00
YAML Syntax
===========
This page provides a basic overview of correct YAML syntax, which is how Ansible
playbooks (our configuration management language) are expressed.
2013-07-22 22:09:18 +00:00
We use YAML because it is easier for humans to read and write than other common
data formats like XML or JSON. Further, there are libraries available in most
programming languages for working with YAML.
2012-03-11 19:34:21 +00:00
2018-03-14 19:44:21 +00:00
You may also wish to read :ref: `working_with_playbooks` at the same time to see how this
2012-03-11 19:34:21 +00:00
is used in practice.
YAML Basics
-----------
2013-07-22 22:09:18 +00:00
For Ansible, nearly every YAML file starts with a list.
2012-03-13 03:18:54 +00:00
Each item in the list is a list of key/value pairs, commonly
2012-03-11 19:34:21 +00:00
called a "hash" or a "dictionary". So, we need to know how
to write lists and dictionaries in YAML.
2015-11-17 20:05:07 +00:00
There's another small quirk to YAML. All YAML files (regardless of their association with Ansible or not) can optionally
begin with `` --- `` and end with `` ... `` . This is part of the YAML format and indicates the start and end of a document.
2012-03-11 19:34:21 +00:00
2015-11-17 20:05:07 +00:00
All members of a list are lines beginning at the same indentation level starting with a `` "- " `` (a dash and a space)::
2012-03-11 19:34:21 +00:00
---
# A list of tasty fruits
2018-10-25 20:23:47 +00:00
- Apple
- Orange
- Strawberry
- Mango
2015-11-17 20:05:07 +00:00
...
2012-03-11 19:34:21 +00:00
2015-02-05 16:13:33 +00:00
A dictionary is represented in a simple `` key: value `` form (the colon must be followed by a space)::
2012-03-11 19:34:21 +00:00
# An employee record
2016-03-02 14:19:02 +00:00
martin:
2015-11-17 20:05:07 +00:00
name: Martin D'vloper
job: Developer
skill: Elite
2012-03-11 19:34:21 +00:00
2016-02-29 16:04:45 +00:00
More complicated data structures are possible, such as lists of dictionaries, dictionaries whose values are lists or a mix of both::
2016-02-16 16:40:44 +00:00
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
2015-11-17 20:05:07 +00:00
Dictionaries and lists can also be represented in an abbreviated form if you really want to::
2012-03-11 19:34:21 +00:00
---
2016-03-02 14:19:02 +00:00
martin: {name: Martin D'vloper, job: Developer, skill: Elite}
2018-10-25 20:23:47 +00:00
['Apple', 'Orange', 'Strawberry', 'Mango']
2012-03-11 19:34:21 +00:00
2018-02-05 21:32:06 +00:00
These are called "Flow collections".
2012-03-11 19:34:21 +00:00
.. _truthiness:
2015-11-17 20:05:07 +00:00
Ansible doesn't really use these too much, but you can also specify a boolean value (true/false) in several forms::
2012-03-11 19:34:21 +00:00
2012-12-14 10:56:53 +00:00
create_key: yes
needs_agent: no
2012-03-11 19:34:21 +00:00
knows_oop: True
likes_emacs: TRUE
uses_cvs: false
2018-02-05 21:32:06 +00:00
Values can span multiple lines using `` | `` or `` > `` . Spanning multiple lines using a "Literal Block Scalar" `` | `` will include the newlines and any trailing spaces.
Using a "Folded Block Scalar" `` > `` will fold newlines to spaces; it's used to make what would otherwise be a very long line easier to read and edit.
2016-02-24 15:06:21 +00:00
In either case the indentation will be ignored.
Examples are::
2016-02-16 16:40:44 +00:00
include_newlines: |
exactly as you see
will appear these three
lines of poetry
2015-11-17 20:05:07 +00:00
2018-02-05 21:32:06 +00:00
fold_newlines: >
2016-02-24 15:06:21 +00:00
this is really a
single line of text
despite appearances
2018-02-05 21:32:06 +00:00
While in the above `` > `` example all newlines are folded into spaces, there are two ways to enforce a newline to be kept::
fold_some_newlines: >
a
b
c
d
e
f
same_as: "a b\nc d\n e\nf\n"
2015-11-17 20:05:07 +00:00
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::
2012-03-11 19:34:21 +00:00
---
# An employee record
2015-11-17 20:05:07 +00:00
name: Martin D'vloper
2012-03-11 19:34:21 +00:00
job: Developer
skill: Elite
employed: True
foods:
- Apple
- Orange
- Strawberry
- Mango
languages:
2016-02-16 16:40:44 +00:00
perl: Elite
2013-07-22 22:09:18 +00:00
python: Elite
2016-02-16 16:40:44 +00:00
pascal: Lame
education: |
4 GCSEs
3 A-Levels
BSc in the Internet of Things
2012-03-11 19:34:21 +00:00
2015-11-17 20:05:07 +00:00
That's all you really need to know about YAML to start writing `Ansible` playbooks.
2012-03-11 19:34:21 +00:00
2012-10-16 23:03:54 +00:00
Gotchas
-------
2018-02-05 21:32:06 +00:00
While you can put just about anything into an unquoted scalar, there are some exceptions.
2018-10-24 14:55:25 +00:00
A colon followed by a space (or newline) `` ": " `` is an indicator for a mapping.
A space followed by the pound sign `` " #" `` starts a comment.
2018-02-05 21:32:06 +00:00
Because of this, the following is going to result in a YAML syntax error::
2012-10-16 23:03:54 +00:00
foo: somebody said I should put a colon here: so I did
2017-03-03 20:49:03 +00:00
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::
2012-10-16 23:03:54 +00:00
2018-02-05 21:32:06 +00:00
foo: 'somebody said I should put a colon here: so I did'
windows_drive: 'c:'
...and then the colon will be preserved.
Alternatively, you can use double quotes::
2012-10-16 23:03:54 +00:00
foo: "somebody said I should put a colon here: so I did"
2017-03-03 20:49:03 +00:00
windows_drive: "c:"
2012-10-16 23:03:54 +00:00
2018-02-05 21:32:06 +00:00
The difference between single quotes and double quotes is that in double quotes
you can use escapes::
foo: "a \t TAB and a \n NEWLINE"
The list of allowed escapes can be found in the YAML Specification under "Escape Sequences" (YAML 1.1) or "Escape Characters" (YAML 1.2).
2019-01-24 22:09:41 +00:00
The following is invalid YAML:
.. code-block :: text
2018-02-05 21:32:06 +00:00
foo: "an escaped \' single quote"
2012-10-16 23:03:54 +00:00
2013-06-10 01:35:51 +00:00
Further, Ansible uses "{{ var }}" for variables. If a value after a colon starts
2013-07-22 22:09:18 +00:00
with a "{", YAML will think it is a dictionary, so you must quote it, like so::
2013-06-10 01:35:51 +00:00
foo: "{{ variable }}"
2017-03-05 09:27:54 +00:00
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
2018-02-05 21:32:06 +00:00
In addition to `` ' `` and `` " `` there are a number of characters that are special (or reserved) and cannot be used
as 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-space
character 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" }
2015-11-17 20:05:07 +00:00
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::
non_boolean: "yes"
other_string: "False"
2013-06-10 01:35:51 +00:00
2016-11-28 09:58:43 +00:00
YAML converts certain strings into floating-point values, such as the string
`1.0` . If you need to specify a version number (in a requirements.yml file, for
example), you will need to quote the value if it looks like a floating-point
value::
version: "1.0"
2012-03-11 19:34:21 +00:00
.. seealso ::
2018-03-14 19:44:21 +00:00
:ref: `working_with_playbooks`
2012-03-11 19:34:21 +00:00
Learn what playbooks can do and how to write/run them.
`YAMLLint <http://yamllint.com/> `_
YAML Lint (online) helps you debug YAML syntax if you are having problems
2019-01-15 13:53:04 +00:00
`GitHub examples directory <https://github.com/ansible/ansible-examples> `_
2012-03-31 13:29:31 +00:00
Complete playbook files from the github project source
2016-02-16 16:40:44 +00:00
`Wikipedia YAML syntax reference <https://en.wikipedia.org/wiki/YAML> `_
A good guide to YAML syntax
2018-07-21 13:48:47 +00:00
`Mailing List <https://groups.google.com/group/ansible-project> `_
2012-03-31 13:55:37 +00:00
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net> `_
2018-02-05 21:32:06 +00:00
#ansible IRC chat channel and #yaml for YAML specific questions
`YAML 1.1 Specification <http://yaml.org/spec/1.1/> `_
The Specification for YAML 1.1, which PyYAML and libyaml are currently
implementing
2018-07-05 01:54:49 +00:00
`YAML 1.2 Specification <http://yaml.org/spec/1.2/spec.html> `_
2018-02-05 21:32:06 +00:00
For completeness, YAML 1.2 is the successor of 1.1
2012-03-11 19:34:21 +00:00