Learn YAML in ten minutes!

What is YAML?

YAML is a digestible data serialization language often used to create configuration files with any programming language.

Designed for human interaction, YAML is a strict superset of JSON, another data serialization language. But because it’s a strict superset, it can do everything that JSON can and more. One major difference is that newlines and indentation actually mean something in YAML instead of JSON, which uses brackets and braces.

How To Write YAML

The basic structure of a YAML file is a map. You might call this a dictionary, hash, or object, depending on your programming language or mood.

Very generally, its keys and values all the way down:

You can use all sorts of scalar types as values: numbers, booleans, and strings (quoted or not). The first line of a config.yml, for example, is usually:

Words in keys can be separated by underscores, dashes, or spaces.

If the value of a key is a multi-line string, you can use either the ‘literal block’ style using the ‘|’ character. This is particularly helpful when defining shell commands:

Note that the leading indentation for the multi-line string will be stripped.

All you have to do to create collections is Use Indentation:

If you have a list of things (like images), you can denote that sequence using dashes:

Note that the second item in the sequence has two keys: image and command. The command key uses a JSON-style sequence because (remember!) YAML is a superset of JSON.


For better understanding, here are some snippets containing both YAML and JSON code so that you can understand how YAML code looks like in JSON.

The above code will translate to JSON as:

The above code will translate to JSON as:

All of the above will translate to JSON as:

All of the above will translate to JSON as:

ISO-Formatted dates can be used, like so:

Sequences allow us to define lists in YAML:

Both of the above sequences will parse to JSON as:

We can use all of the above types to create an object with nested values, like so:

Which will translate to JSON as:

Combining sequences and nested values together we can create a list of objects.

The following are some more complex features that caught my attention and differentiate YAML from JSON.

As you’ve probably already noticed in my prior examples, YAML allows comments starting with #.

Node anchors mark a node for future reference, which allows us to reuse the node. To mark a node we use the & character, and to reference it we use *:

In the following example, we’ll define a list of books and reuse the author data, so we only have to define it once:

The above code will look like this once parsed to JSON:

As we’ve seen in previous examples, YAML autodetects the type of our values, but it’s possible to specify which type we want.
We specify the type by including it before the value preceded by !!.

Here are some examples:

This will translate to JSON as:

Finally, YAML doesn’t allow tab characters, so if you’re using those to indent, have your text editor convert those to spaces. Syntax errors in your YAML can sometimes cause builds to hang, but they’re also easily preventable by running your circle.yml/config.yml through an online validator.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store