What is YAML? Learn YAML syntax & yaml vs json differences

YAML is a recursive acronym for Yaml ain't markup language. It is generally considered easier to read than more verbose XML or JSON serialization languages.

Serialization is the process of translating a data structure or object state into a format that can be stored or transmitted and reconstructed later.

YAML is most often used for configuration files of servers and software applications. YAML files have an extension of .yaml or .yml. Yaml official site recommends using .yaml extension whenever possible.

YAML syntax has python like indentation with nesting for representing hierarchical data. YAML is a superset of JSON, so every JSON data is a valid YAML but not vice-versa.

A sample YAML file looks like below.

---
name: John
age: 25
hobbies:
  - swimming
  - dancing
  - programming

YAML is used for config files in AWS, Docker, etc.

YAML syntax

Comments

Unlike JSON, YAML allows having comments in the file. These comments can be inserted using a number sign(#). If # characters appear inside a string, then they are considered number sign # literals.

# This is a comment in yaml
name: John

Strings and numbers

YAML supports various kinds of data types strings, numbers, boolean, arrays or lists, etc. The key-value pairs are separated with a colon followed by a space.

# Object(key-value pairs)
project: XYZ
version: 2.0

It's optional to wrap strings with single or double-quotes. If there are any special characters or punctuation marks like colon(:) or dashes(-) in the strings then wrapping with quotes is recommended.

Tab characters are not allowed in YAML only whitespaces have to be used for indentation.

Booleans

The allowed boolean values are true/false, yes/no, on/off

# Boolean value property
isOpenSource: true # equivalents → yes or on

Nesting key-value pairs

The nesting of the key-value pairs is done by indenting the key-value pairs in the next line after the colon.

# Nested object(key-value pairs)
details:
  name: Server config
  service: abc
  state: started

Arrays or lists

An array sequence starts with a dash(-) followed by a space and the indentation separates from the parent.

# Array of values
technologies:
  - SQL
  - GO
  - Javascript

An array of objects(key-value pairs) can be written similarly just by indenting each key-value pair in reference to the dash(-).

# Array of objects
collaborators:
  - name: John
    age: 25
  - name: James
    age: 26

Multiline strings

A pipe(|) character at the beginning of the string is used to have a string with multi-lines preserved without having to use any escape characters.

# Multiline strings
summary: |
  This is the first line of the string.
  This is the second and line break is preserved.

When a greater than character(>) is used at the beginning of the string then the multi-lines get wrapped by stripping leading indentations and trailing white spaces. This is good for writing the readable lines of strings without the need to preserve the line breaks.

# Folded text
description: >
  This is a very very long text just wrapped
  in multi-lines but all this text is considered
  as a continuous text without any line breaks.

Document separator

YAML allows having multiple documents in a single file by separating them with three hyphens(---).

---
# A yaml document
project: XYZ

YAML vs JSON

The main aim of YAML is to make the data easily readable and understandable. Some of the major differences between YAML and JSON are:

YAML	JSON
1. Easy to read and understand	1. A bit difficult to read and understand
2. Uses nested indentation for hierarchy	2. Uses braces and brackets for hierarchy
3. Comments are allowed	3. No comments are allowed
4. Wrapping strings with quotes is optional	4. Must wrap strings with double quotes
5. Multiple documents are allowed in a single file	5. Only one document per file
6. It's a superset of JSON	6. Every JSON is a valid YAML
7. Mostly used for configuration files	7. Mostly used for transmitting data
8. Python developers like this format	8. Javascript developers like this format

Below is the similar kind of data represented in YAML and JSON formats.

A typical YAML file

--- # YAML example
project: XYZ
version: 2.0
isOpenSource: true
technologies:
  - SQL
  - GO
  - Javascript
collaborators:
  - name: John
    age: 25
  - name: James
    age: 26
details:
  name: Server config
  service: abc
  state: started
summary: |
  This is the first line of the string.
  This is the second and line break is preserved.
description: >
  This is a very very long text just wrapped
  in multi-lines but all this text is considered
  as a continuous text without any line breaks.

The equivalent JSON file

{
    "project": "XYZ",
    "version": 2,
    "isOpenSource": true,
    "technologies": [
        "SQL",
        "GO",
        "Javascript"
    ],
    "collaborators": [
        {
            "name": "John",
            "age": 25
        },
        {
            "name": "James",
            "age": 26
        }
    ],
    "details": {
        "name": "Server config",
        "service": "abc",
        "state": "started"
    },
    "summary": "This is the first line of the string.\nThis is the second and line break is preserved.\n",
    "description": "This is a very very long text just wrapped in multi-lines but all this text is considered as a continuous text without any line breaks\n"
}

YAML also has a few more features like node anchors, references etc. But all the above-discussed features are the essential ones to know in YAML. There are YAML linting tools to validate the YAML files which you can use to validate your files.

That's all about YAML and its comparison with JSON.