YAML Syntax

Styles

YAML syntax 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
• 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)

Mappings, the colon-space combination that marks it as a mapping

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

Also known as:

• Lists, arrays or collections
• Denoted with a dash - and space
• Can be combined with mappings:
  • mapping of sequences
  • sequence of mapping
  • list of maps

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
<source lang=yaml>
roles: [ web, dns, "" ]

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

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
• the ability to assign local tags to that indicator, using eg. ! WAW
• the ability to change how the YAML parser reads certain scalars when processing the YAML, using eg.!!str>code>

, then we assign some local tags with !, before finally learning how to use the !! indicator to change the data type of a scalar.

• 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
• used to change a data type

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 - Sequence
• map - Map
• str - String
• int - Integer
• float - Floating-point decimal
• null - Null
• binary - Binary code
• omap - Ordered map
• set - Unordered set