YAML Tutorial for beginners: Get Started in Minutes


What is YAML?

YAML Ain’t Markup Language (YAML) is a human friendly data serialization standard for all programming languages. It has been gaining popularity over the last years because is much less verbose than other markup languages (for example XML) and is simpler to read and write. That's why it is commonly used to write configuration files, such as docker-compose or kubernetes (k8s) files. It is also used to write log files and to share data between multiple programming languages (these use cases are less frequent than writing configuration files).

Something worth to mention is that YAML is a superset of JSON. That means that you can write JSON inside a YAML file. The good news is that, if you know JSON, you already know something of YAML!


Overview of a simple file

Before starting to learn YAML syntax, let see how a YAML file looks like:

# An employee record
name: John Doe
job: Software Developer
skill: "Senior"
age: 35
start_date: 2019-12-14
employed: True
    - Apple
    - Orange
    - Banana
    - Watermelon
    python: Senior
    java: Senior
    go: Junior

Maybe you are thinking: "Hey dude... what the f... am I reading? It is that readable? How I’ll be able to graduate as an engineer if I can't even understand a simple piece of code! Then, I’ll not be able to find a good job and make a living as a programmer, I’ll never be able to buy a house or even marry with the girl of my dreams!". Or maybe: "Mmmm... I don't understand it.". In my case it was the first expression (or maybe there wasn't too much drama involved...).

If it is the first time you see a YAML file, don't worry! It's really simple. We will be learning each part of the document piece by piece (as Jack the Ripper said). Remember that the file extension used for YAML files is .yaml, but .yml is also allowed.

Lets break down this file into smaller pieces.


Whenever you see the # character that is not first enclosed with ' (single quotes) or " (double quotes), from there up to the end of the line is considered a comment. Comments are completely ignored and has no effect in your programs. They are used to write notes on the file (for documentation purposes) or to temporarily disable options (because the program will consider the line that you have just commented as a comment, and it will ignore it).

# This is a comment

The following example is not a comment (because is enclosed with a quote):

hello: "#John"

This is one of the best features YAML has compared to JSON, because JSON does not allow comments. That's why it has gained popularity as the language to use in configuration files.

Key-Value pairs (Dictionaries)

Key-Value pairs or Dictionaries (also called Maps) are the most basic building blocks in a YAML file. Let's see the following example:

hello: "John"

Dictionaries consist of two parts: a key and a value. In the example above, the key is hello, and the value is John. Remember that the key is always a string, but the value can be any datatype (string, number, dictionary, list, etc).

If you keep struggling with the previous code, maybe looking the following piece of code written in JSON will bring a bit of light (the data expressed in JSON is the same that in the YAML file above):

    "hello": "John"

So, if you want a mnemonic rule, every time you see a key-value pair, add to the key a pair of double quotes (") and surround all the keys that are with the same indentation level with a pair of curly braces {}.

Value types



Strings in YAML can be wrapped with ' (single quotes), " (double quotes), or it can even be unquoted.

'Single quotes'
"Double quotes"

YAML supports many type of numbers, including integers, octal, hexadecimal, float, exponential numbers and infinity.

# Integer

# Float

# Octal

# Hexadecimal

# Exponential

# Infinity

# Minus Infinity

Booleans are expressed with true and false.

YAML uses the ISO-8601 standard to express dates. There are two ways of expressing dates:
# The "complete" date
# Or the simple date

Null values in YAML can be expressed in different ways. These values are: null, Null, NULL, ~, or even leaving an empty space when defining a dictionary.

- this is null: null
- this is also null: Null
- even in upper case is null: NULL
- the tilde also represents null: ~
- if you are so lazy you can leave an empty space:


In general, YAML files contain collections. These collections can be either a sequence (or list) or a mapping of elements (also known as key-value pair). We have already seen key-value pairs, so we will only describe below how lists are written (however, there will be an example of maps just to refresh your memory).


Lists (or sequences) use a dash followed by a space (and then the value that you want to write down):

- Apple
- Banana

Here an example of maps.

joe: happy
john: sad

Reviewing example

Now that you have a clear understanding of YAML syntax, lets review the example given at the beginning of the tutorial.

# An employee record
name: John Doe
job: Software Developer
skill: "Senior"
age: 35
start_date: 2019-12-14
employed: True
    - Apple
    - Orange
    - Banana
    - Watermelon
    python: Senior
    java: Senior
    go: Junior

Bellow you will find the same data but writen in JSON format.

    "name": "John Doe",
    "job": "Software Developer",
    "skill": "Senior",
    "age": 35,
    "start_date": "2019-12-14T00:00:00.000Z",
    "employed": true,
    "favorite_fruits": [
    "languages": {
        "python": "Senior",
        "java": "Senior",
        "go": "Junior"

I hope the tutorial was useful for you :)