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