1.. _yaml_syntax:
2
3
4YAML Syntax
5===========
6
7This page provides a basic overview of correct YAML syntax, which is how Ansible
8playbooks (our configuration management language) are expressed.
9
10We use YAML because it is easier for humans to read and write than other common
11data formats like XML or JSON.  Further, there are libraries available in most
12programming languages for working with YAML.
13
14You may also wish to read :ref:`working_with_playbooks` at the same time to see how this
15is used in practice.
16
17
18YAML Basics
19-----------
20
21For Ansible, nearly every YAML file starts with a list.
22Each item in the list is a list of key/value pairs, commonly
23called a "hash" or a "dictionary".  So, we need to know how
24to write lists and dictionaries in YAML.
25
26There's another small quirk to YAML.  All YAML files (regardless of their association with Ansible or not) can optionally
27begin with ``---`` and end with ``...``.  This is part of the YAML format and indicates the start and end of a document.
28
29All members of a list are lines beginning at the same indentation level starting with a ``"- "`` (a dash and a space)::
30
31    ---
32    # A list of tasty fruits
33    - Apple
34    - Orange
35    - Strawberry
36    - Mango
37    ...
38
39A dictionary is represented in a simple ``key: value`` form (the colon must be followed by a space)::
40
41    # An employee record
42    martin:
43      name: Martin D'vloper
44      job: Developer
45      skill: Elite
46
47More complicated data structures are possible, such as lists of dictionaries, dictionaries whose values are lists or a mix of both::
48
49    # Employee records
50    - martin:
51        name: Martin D'vloper
52        job: Developer
53        skills:
54          - python
55          - perl
56          - pascal
57    - tabitha:
58        name: Tabitha Bitumen
59        job: Developer
60        skills:
61          - lisp
62          - fortran
63          - erlang
64
65Dictionaries and lists can also be represented in an abbreviated form if you really want to::
66
67    ---
68    martin: {name: Martin D'vloper, job: Developer, skill: Elite}
69    ['Apple', 'Orange', 'Strawberry', 'Mango']
70
71These are called "Flow collections".
72
73.. _truthiness:
74
75Ansible doesn't really use these too much, but you can also specify a boolean value (true/false) in several forms::
76
77    create_key: yes
78    needs_agent: no
79    knows_oop: True
80    likes_emacs: TRUE
81    uses_cvs: false
82
83Use lowercase 'true' or 'false' for boolean values in dictionaries if you want to be compatible with default yamllint options.
84
85Values can span multiple lines using ``|`` or ``>``.  Spanning multiple lines using a "Literal Block Scalar" ``|`` will include the newlines and any trailing spaces.
86Using 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.
87In either case the indentation will be ignored.
88Examples are::
89
90    include_newlines: |
91                exactly as you see
92                will appear these three
93                lines of poetry
94
95    fold_newlines: >
96                this is really a
97                single line of text
98                despite appearances
99
100While in the above ``>`` example all newlines are folded into spaces, there are two ways to enforce a newline to be kept::
101
102    fold_some_newlines: >
103        a
104        b
105
106        c
107        d
108          e
109        f
110    same_as: "a b\nc d\n  e\nf\n"
111
112Let's combine what we learned so far in an arbitrary YAML example.
113This really has nothing to do with Ansible, but will give you a feel for the format::
114
115    ---
116    # An employee record
117    name: Martin D'vloper
118    job: Developer
119    skill: Elite
120    employed: True
121    foods:
122      - Apple
123      - Orange
124      - Strawberry
125      - Mango
126    languages:
127      perl: Elite
128      python: Elite
129      pascal: Lame
130    education: |
131      4 GCSEs
132      3 A-Levels
133      BSc in the Internet of Things
134
135That's all you really need to know about YAML to start writing `Ansible` playbooks.
136
137Gotchas
138-------
139
140While you can put just about anything into an unquoted scalar, there are some exceptions.
141A colon followed by a space (or newline) ``": "`` is an indicator for a mapping.
142A space followed by the pound sign ``" #"`` starts a comment.
143
144Because of this, the following is going to result in a YAML syntax error::
145
146    foo: somebody said I should put a colon here: so I did
147
148    windows_drive: c:
149
150...but this will work::
151
152    windows_path: c:\windows
153
154You will want to quote hash values using colons followed by a space or the end of the line::
155
156    foo: 'somebody said I should put a colon here: so I did'
157
158    windows_drive: 'c:'
159
160...and then the colon will be preserved.
161
162Alternatively, you can use double quotes::
163
164    foo: "somebody said I should put a colon here: so I did"
165
166    windows_drive: "c:"
167
168The difference between single quotes and double quotes is that in double quotes
169you can use escapes::
170
171    foo: "a \t TAB and a \n NEWLINE"
172
173The list of allowed escapes can be found in the YAML Specification under "Escape Sequences" (YAML 1.1) or "Escape Characters" (YAML 1.2).
174
175The following is invalid YAML:
176
177.. code-block:: text
178
179    foo: "an escaped \' single quote"
180
181
182Further, Ansible uses "{{ var }}" for variables.  If a value after a colon starts
183with a "{", YAML will think it is a dictionary, so you must quote it, like so::
184
185    foo: "{{ variable }}"
186
187If 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::
188
189    foo: "{{ variable }}/additional/string/literal"
190    foo2: "{{ variable }}\\backslashes\\are\\also\\special\\characters"
191    foo3: "even if it's just a string literal it must all be quoted"
192
193Not valid::
194
195    foo: "E:\\path\\"rest\\of\\path
196
197In addition to ``'`` and ``"`` there are a number of characters that are special (or reserved) and cannot be used
198as the first character of an unquoted scalar: ``[] {} > | * & ! % # ` @ ,``.
199
200You should also be aware of ``? : -``. In YAML, they are allowed at the beginning of a string if a non-space
201character follows, but YAML processor implementations differ, so it's better to use quotes.
202
203In Flow Collections, the rules are a bit more strict::
204
205    a scalar in block mapping: this } is [ all , valid
206
207    flow mapping: { key: "you { should [ use , quotes here" }
208
209Boolean conversion is helpful, but this can be a problem when you want a literal `yes` or other boolean values as a string.
210In these cases just use quotes::
211
212    non_boolean: "yes"
213    other_string: "False"
214
215
216YAML converts certain strings into floating-point values, such as the string
217`1.0`. If you need to specify a version number (in a requirements.yml file, for
218example), you will need to quote the value if it looks like a floating-point
219value::
220
221  version: "1.0"
222
223
224.. seealso::
225
226   :ref:`working_with_playbooks`
227       Learn what playbooks can do and how to write/run them.
228   `YAMLLint <http://yamllint.com/>`_
229       YAML Lint (online) helps you debug YAML syntax if you are having problems
230   `GitHub examples directory <https://github.com/ansible/ansible-examples>`_
231       Complete playbook files from the github project source
232   `Wikipedia YAML syntax reference <https://en.wikipedia.org/wiki/YAML>`_
233       A good guide to YAML syntax
234   `Mailing List <https://groups.google.com/group/ansible-project>`_
235       Questions? Help? Ideas?  Stop by the list on Google Groups
236   `irc.libera.chat <https://libera.chat/>`_
237       #ansible IRC chat channel
238   `irc.libera.chat <https://libera.chat/>`_
239       #yaml for YAML specific questions
240   `YAML 1.1 Specification <https://yaml.org/spec/1.1/>`_
241       The Specification for YAML 1.1, which PyYAML and libyaml are currently
242       implementing
243   `YAML 1.2 Specification <https://yaml.org/spec/1.2/spec.html>`_
244       For completeness, YAML 1.2 is the successor of 1.1
245