Introduction

YAML, previously known as Yet Another Markup Language, but now YAML Ain’t Markup Language, is a human friendly data serialization standard for programming languages.

YAML and JSON, JavaScript Object Notation, are related to each other, where YAML, according to YAML 1.2 specification, is a superset of JSON.

YAML supports using scalars, sequences, and mappings. A scalar is a string, a number, or boolean, a sequence is a list, and a mapping is a key/value pair.

YAML is commonly used by configuration files in open source tools and Ansible, a network automation tool, uses YAML to run its playbooks.

When it comes to YAML syntax, be aware of the following:

  • Indentation matters!
    • Tabs aren’t allowed
    • Normally two spaces used when indenting
  • A single YAML file may contain multiple documents
    • Every document starts with three dashes
  • YAML is case sensitive

Scalars

Scalars are single values. It can be a string, number, or a boolean value. Strings don’t need to be quoted, except for some special cases:

  • The string starts with a special character
    • !#%@&*`?|>{[ or –
  • The string starts or ends with whitespace characters
  • The string contains : or # character sequences
  • The string ends with a colon
  • The value looks like a boolean or number but should be a string

If a value is quoted, it’s interpreted as a string.

Comments are indicated by a #.

Let’s see a basic YAML file using scalars:

---
integer: 7
string: seven
float: 3.14
boolean: true

We can confirm the types of the scalars by using a basic Python script:

# Basic Python script to read from a YAML file

# Import YAML module
import yaml

# Open the daniel.yaml file
with open(r'/home/daniel/YAML/scalar.yaml') as yamlFile:
    # FullLoader parameter converts YAML scalar values to dict in Python
    yamlDict = yaml.load(yamlFile, Loader=yaml.FullLoader)

# Iterate over yamlDict and print each key and value and its type

for key, value in yamlDict.items():
    print("The key %s is of type %s and its value %s is of type %s" % (key, type(key), value, type(value)))

This yields the following output:

[email protected]:~/YAML$ python3 scalar.py 
The key integer is of type <class 'str'> and its value 7 is of type <class 'int'>
The key string is of type <class 'str'> and its value seven is of type <class 'str'>
The key float is of type <class 'str'> and its value 3.14 is of type <class 'float'>
The key boolean is of type <class 'str'> and its value True is of type <class 'bool'>

You need to have PyYAML installed to run the code. Make sure you have a Python environment with PIP so that you can download the package. If you don’t have PIP already, install it:

[email protected]:~/YAML$ sudo apt install python3-pip
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following additional packages will be installed:
<snip>
Do you want to continue? [Y/n] y
[email protected]:~/YAML$ sudo pip3 install pyyaml
Requirement already satisfied: pyyaml in /usr/lib/python3/dist-packages (5.3.1)

Sequences

A sequence is the equivalent of a list in Python. A sequence is identified by the dash and then a space. Below is a simple sequence:

---
favourite_movies:
  - The Silence of the Lambs
  - Seven
  - The Godfather
  - Unce Upon a Time in America
  - The Shawshank Redemption

We can once again use Python to see that this is in fact a list:

[email protected]:~/YAML$ python3 movies.py 
The key favourite_movies is of type <class 'str'> and its value ['The Silence of the Lambs', 'Seven', 'The Godfather', 'Unce Upon a Time in America', 'The Shawshank Redemption'] is of type <class 'list'>

It’s also possible to have nested sequences:

---
favourite_movies:
  -
    - The Silence of the Lambs
    - Seven
  -
    - The Godfather
    - Unce Upon a Time in America

This would then produce two lists:

[email protected]:~/YAML$ python3 movies.py 
The key favourite_movies is of type <class 'str'> and its value [['The Silence of the Lambs', 'Seven'], ['The Godfather', 'Unce Upon a Time in America']] is of type <class 'list'>

Mappings

A mapping is a key/value pair, known as a dictionary in Python. The key is on the left, and on the right is the value. Here is an example of a very basic YAML file:

# Some facts about Daniel
# Document starts with three dashes
---
name: Daniel
hobby: running
blog: lostintransit.se
favourite_movies:
  - The Silence of the Lambs
  - Seven
  - The Godfather
  - Unce Upon a Time in America
  - The Shawshank Redemption
... 

The value of a key can also be a list, as seen here with some of my favorite movies listed. If we run Python on this YAML file, we see the type of each key and value:

[email protected]:~/YAML$ python3 daniel2.py
The key name is of type <class 'str'> and its value Daniel is of type <class 'str'>
The key hobby is of type <class 'str'> and its value running is of type <class 'str'>
The key blog is of type <class 'str'> and its value lostintransit.se is of type <class 'str'>
The key favourite_movies is of type <class 'str'> and its value ['The Silence of the Lambs', 'Seven', 'The Godfather', 'Unce Upon a Time in America', 'The Shawshank Redemption'] is of type <class 'list'>

In some cases, you may have the need for multi-line values. There are two ways of handling that, either using > or using |. With the pipe, the newlines are preserved, while they are not if using greater than symbol.

Here is an example of a login banner in YAML:

---
banner: |
        Unauthorized access to this device
        is not allowed. All attempts to
        login are logged and save. Disconnect
        immediately if you are not authorized
        to use this device.

If we run Python, newlines should be preserved:

[email protected]:~/YAML$ python3 long.py 
{'banner': 'Unauthorized access to this device\nis not allowed. All attempts to\nlogin are logged and save. Disconnect\nimmediately if you are not authorized\nto use this device.\n'}

Now let’s try the other format:

[email protected]:~/YAML$ python3 long.py 
{'banner': 'Unauthorized access to this device is not allowed. All attempts to login are logged and save. Disconnect immediately if you are not authorized to use this device.\n'}

Hopefully this introduction to YAML helps you with your DevAsc studies. I will put some of my study notes in blog format for my own reference, as well as others. Good luck!

DevAsc- Introduction to YAML
Tagged on:         

2 thoughts on “DevAsc- Introduction to YAML

  • June 4, 2020 at 1:16 am
    Permalink

    Hello Daniel,

    Thank you for this article. I am confused about scalars and mapping – a difference not so obviously. If my YAML file consist from:


    one: “1”

    It is mapping or scalar?

    Reply

Leave a Reply to ddib Cancel reply

Your email address will not be published. Required fields are marked *