YAML Syntax
Jump to navigation
Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
Styles
Block style | Flow style |
---|---|
Human frendly, less compact | An extension of JSON, foldinf long lines, tags and anchors |
host: host-1 datacenter: #mapping location: Poland #key-value mapping indentention cabinet: 11 roles: #list - web - dns |
host: "host-1" datacentrer: { location: Poland , cabinet: 11 } roles: [ web , dns ] # {} kv mapping # [] list (array) |
Characters
- Printable Unicode
- Unsupported symbols
- C0/C1 blocks
- Exceptions: Tab, Line Feed, Carrage Return, Delete, Next line
- Surrogates
- C0/C1 blocks
- Encoding: UTF-8, 16, 32
- To be JSON compatibile must be UTF-32
Mappings
Mappings are also known as:
- assosiative arrays
- hash tables
- kv pairs
- collection (YAML specific term, that groups things indented at the same level)
Block style | Flow style |
---|---|
host: host-1 datacenter: location: Poland cabinet: 11 # cabinet: 12 #the same keys are not allowed |
host: host-1 datacentre: { location: Poland, cabinet: 11 } |
Sequences (list)
Also known as:
- Lists, dictionary, arrays or collections
- Denoted with a dash - and space
- Can be combined with mappings:
- mapping of sequences
- sequence of mapping
- list of maps
Sequence
host: host-1 # sequence/list of mappings - datacenter: location: Poland cabinet: 11 roles: # sequence - web - dns - "" #blank lines are not allowed, thus double-quotes are required
Flow style sequence
roles: [ web, dns, "" ]
Examples of lists and maps
Sequences are lists
- Item 1 - Item 2
Mappings are key-value pairs
key1: value1 key2: value2
A sequence of mappings:
- key1: value1 key2: value2
A mapping of mappings:
overallkey: key1: value1 key2: value2
Scalars
Scalar is a string, number of boolean with whitespace permitted.
--- host: host-1 datacenter: location: "Poland\n" # double-quotes allow escape sequences, "\n" - will be read as new-line cabinet: '11' # change a number into string single or double-quotes roles: - web - dns - "" #blank lines are not allowed, thus double-quotes are required comments: | # pipe (multiline scalar) it preserves newlines Comment 1 note of the required indent Comment 2 comments_other: > # right chevron (folded scalar) does not preserve new lines, but helps with code readibility # converts newlines /spacing into single space. Other_comment is that indent is still needed Another comment. <tab><tab> item-1 this preserves new lines to create a list <tab><tab> item-2
Block Scalars - control multiline string
Check ^^ link above.
Structures
YAML allows for multiple directive/documents in one file. The document/directive starts with ---
but it's often optional for single directive files. Ansible requires it but not Salt. The delimiters are reuired for multi-directive files.
--- host: host-1 datacenter: location: Poland --- host: host-2 datacenter: Location: Spain ... # (optinal) mark end of directive/collection without cloasing the data stream
Comments
# Valid comment1 - must be a space in between '# comment --- host: host-1 # Inline: valid comment2, comments in the middle are not allowed datacenter: # Inline comment3, all inline comments come at the end of line # <- any empty lines are read as comments too location: Poland --- host: host-2 datacenter: Location: Spain ... #(optimal) mark end of directive/collection without closing the data stream
Tags
Tags provide us with three functions:
- ability to assign a universal resource indicator (URI)
- the ability to assign local tags to that indicator, using eg.
! WAW
- change how the YAML parser reads certain scalars when processing the YAML, using eg.
!!str
(!!) indicator to change the data type of a scalar, used to change a data type - a custom URI (Universal Resource Indicator). These can be used with PyYAML or other YAML APIs by exposing resources
- to set local tags - reference only within local directive/file
Syntax
# assign a URI header %TAG ! tag:hostsdata:warsaw: # syntax: '%TAG ! tag:reference:path' # can use also prefix eg '!foo' but '!' is enough
Local tags
# Warsaw DataCentre %TAG ! tag:hostsdata:warsaw: # assign a URI header by creating a local-tag-reference-path host: warsaw-1 datacentre: location: !WAW Warsaw # create a local-tag-reference (assign local tags to URI) cab: !!str 11 # changed number to string # Reference 'location by calling the tag: tag:hostsdata:warsaw:WAW
Default data types:
seq
- Sequencemap
- Mapstr
- Stringint
- Integerfloat
- Floating-point decimalnull
- Nullbinary
- Binary codeomap
- Ordered mapset
- Unordered set
Anchors
Anchors allow to reuse data across a YAML file.
&
define an anchor by prefix to assign some data a name, you can reuse the name to reassign new values and used itm in different place of the file- use the
*
to reference data with that name to call it repeatedly throughout the file
--- host: waw-1 datacenter: location: &WAW Warsaw # set an anchor cabinet: !!str 11 roles: &ROLES # &ROLES it's also accepted in newline, as long there is a space after a ':' - web - db --- host: krk-2 datacentre: location: *WAW # reference the anchor, this pull also the comment cabinet: !!str 12 roles: *ROLES # when the file is parsed, data will be pulled from # &ROLES anchor
Override example
--- master_cipher: &master_cipher alias: "default.master" plain: "password1" passhash: "aaaaaaaaaaaa==" slave_cipher: &slave_cipher alias: "default.slave" plain: "password2" passhash: "bbbbbbbbbbbb==" cipher: - << : *master_cipher # '<<' part of syntax, points where data structure will be inserted (anchored) - << : *master_cipher # 'master_cipher' data structure will be expanded here, where alias: "default.master.common" # 'alias' value will get overriden - << : *slave_cipher # 'slave_cipher' data structure will be expanded here alias: "default.slave.common" # 'alias' value will get overriden
Gotchas
--- country: yes: 49.7 # this is boolean as it's YAML recognized world, fix by "yes" nah: 50.1
References
- create DRY -> non-DRY YAML
- Yaml anchors Quite random find
- yaml-multiline
- How do I break a string in YAML over multiple lines?
- The yaml document from hell ruudvanasseldonk.com