yaml - ghdrako/doc_snipets GitHub Wiki

YAML

• YAML 1.2 Spec
• https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html
• Online YAML Linter (Ruby)
• Online YAML Parser (Python)
• kwalify - YAML schema validator (Ruby)

YAML Syntax Examples

YAML Scalars

Scalar types

a: 1        # integer          
a: 1.234    # float      
b: 'abc'    # string        
b: "abc"                   
b: abc                     
c: false    # boolean type 
d: 2015-04-05   # date type

Enforcing strings

b: !str 2015-04-05

Boolean value

ingress:
  enable: true

YAML Sequences

Simple sequence(list)

servicePorts:
  - 8080
  - 8443

 array:
   - 132
   - 2.434
   - 'abc'

# A list of fruits
- Apple
- Orange
- Banana
- Mango
---

Sequence of sequences

 my_list_of_lists:
   - [1, 2, 3]
   - [4, 5, 6]

list of objects:

deployment:
  env:
    - name: MY_VAR
      value: MY_VALUE
    - name: SERVICE_NAME
      value: MY_SERVICE

env is set to a list of objects containing the name and value fields.

YAML Array

YAML array is a list of similar values nested under a key that’s represented by a name. Each value starts with a hyphen symbol followed by a space.

key1:
  - value 1
  - value 2
  - value 3

YAML Hashes

Dictionaries are mappings that are used to map key-value pairs. In YAML, dictionaries can be represented using flow mapping and block mapping syntaxes.

In a block mapping dictionary, the key and value pairs are represented using a colon syntax.

MyDatabase:
  hostname: localhost
  port: 1234
  username: admin
  password: xxx

In a flow mapping dictionary, the key and value pairs are separated by a comma, and entire pairs are enclosed in {} characters.

MyDatabase: {hostname: localhost ,port: 1234 ,username: admin ,password: xxx}

Nested hash

 my_hash:
   subkey:
     subsubkey1: 5
     subsubkey2: 6
   another:
     somethingelse: 'Important!'

Hash with JSON syntax (mixing is possible)

 my_hash: {nr1: 5, nr2: 6}

YAML HereDoc

Block notation: Newlines become spaces

content:
   Arbitrary free text
   over multiple lines stopping only
   after the indentation changes...

Literal style: Newlines are preserved

content: |
   Arbitrary free text            
   over "multiple lines" stopping 
   after indentation changes...   

• indicator: Keep extra newlines after the block

content: |+                      
   Arbitrary free text with newlines after

• indicator: remove extra newlines after block

content: |-
   Arbitrary free text without newlines after it

folded style: folded newlines are preserved

 content: >
   Arbitrary free text
   over "multiple lines" stopping
   after indentation changes...

Note that YAML heredocs are the way to escape special characters:

 code: 
    url: "https://example.com"        # sub key "url" with value 'https://...'

 code: |-                             # versus key "code" having value 'url: "https://..."'
    url: "https://example.com"

There is a good online previewer for the different heredoc modes: https://yaml-multiline.info/ Multiple Documents

A YAML file can have multiple documents, this is why every document needs to start with a — line

 ---
 content: doc1
 ---
 content: doc2

This also means YAML parsers might return multiple documents! Content References (Aliases)

 ---
 values:
   - &ref Something to reuse
   - *ref      # Literal "Something to reuse" is inserted here!

Merging Keys

Imaging some default properties for a hash like these

 default_settings:
   install:
     dir: /usr/local
     owner: root
   config:
     enabled: false

Use them in another hash using “«: *reference”

 # Derive settings for 'my_app' from default and change install::owner
 # and add further setting "group: my_group"
 
 my_app_settings:
   <<: *default_settings
   install:
     owner: my_user
     group: my_group

Complex Mapping

 ---                              
 ? - key                          
 :                                
   - value                        

Note: key and value can be multiple, complex structures that you could not realize with the hash syntax!