Introducing YAML

YAML (YAML Ain’t Markup Language) is a data serialization language. It was designed to be human-friendly. It organizes data into a readable structure with a simple notation. YAML is based on key-value pairs, indentation, and few punctuations such as colon (:) and hyphens (-).

YAML includes three representations: scalars, sequences and mappings. Among scalars are strings, numbers, and boolean data types. The sequences are similar to lists and arrays in programming languages. The mappings are hashes and dictionaries.

YAML resembles JSON notation. The YAML specification 1.2 states that YAML is a superset of JSON, which means, a JSON file is a valid YAML file.

YAML has many applications. It is mainly used in configuration files, log files, and data sharing between applications.

YAML uses key-value format. The key-value pair specified as: key: value. Here, the colon should be followed by a space.

Comments

In YAML, a comment starts with a hash followed by a space. It can be located anywhere in the YAML file. The interpreter of the YAML file ignores everything after the hash until the end of the line.

# Comments start with a hash and a space

Data types

YAML includes the basic data types such as strings, number, boolean and date and time.

Strings

Strings can be wrapped in single quotes, double quotes or without quotes.

# string without quotes
description: This is a description

# string with single and double quotes
name: 'John Smith'
Title: "The downtown store"

# strings with escape characters must use double quotes
screen: "This is a monitor \n of computer"

# strings with special characters must use single or double quotes
password: ': { } [ ] , & * # ? | - < > = ! % @ `'

Strings can be written on multiple lines:

The symbol '>' replaces newlines and indentation with spaces. Hence, long texts are easier to read.
The symbol '|' preserves newlines and trailing spaces.

content: >
    content one
    content two

text: |
    text one
    text two

Numbers

Numbers include integers and floats.

# Integers
count: 13

# Floats
price: 1.45
delta: 1.231e-10

# strings
number: '12'
max: '1.4'

Boolean

Boolean can take true and false values. These values can be in lower or upper case. Although, other values are allowed such as yes, no, on and off, the values true and false are recommended.

is-valid: true
published: false

# string
fallacy: 'true'

Date and time

Date and time follow the ISO standard format.

date-of-birth: 2001-12-31
arrival-date: 2020-07-15 06:03:21

Empty scalars

Empty scalar are keys without a value or with a null value.

price:
discount: null

Indentation

Indentation allows structuring of data. These indentations use white spaces instead of tabs. In sequences and mappings, all items should be indented with the same number of spaces.

Sequences (Lists or Arrays)

Sequences are list of values. List items are ordered based on their insertion.

Items of a list are written on separate lines, they must begin with a hyphen followed by a space, and should have the same indentation.

fruits:
    - banana
    - apple
    - orange

Using the inline notation, the items are enclosed between square brackets and separated by commas.

vegetables: [carrot, potato, tomato]

Mappings (Dictionaries or Hashes)

A mapping, or a dictionary, is a set of key: value pairs. Each pair is written on separate line. The colon after the key must be followed by a space.

name:
    first-name: John
    last-name: Doe

Dictionaries may be also represented using the inline style. The key-value pair are enclosed between curly braces and separated by commas.

name: {first-name: John, last-name: Doe}

Mixed objects

YAML may have nested dictionaries.

car:
    engine:
        speed: 200
        cylinder: 2.6
    body:
        doors: 4
        Lights: neon

The equivalent of above example in JSON is:

{
  "car": {
    "engine": {
      "speed": 200,
      "cylinder": 2.6
    },
    "body": {
      "doors": 4,
      "Lights": "neon"
    }
  }
}

List of dictionaries:

- book: 
    title: C++
    publisher: Pearson
- book: 
    title: C#
    publisher: Wiley