We make a number of assumptions about our users. One of those assumptions is that they already know how to read/write YAML. But maybe you know nothing about this! That’s completely fine. This post walks through what YAML is and how you should write it.

What Is YAML?

YAML is an acronym that stands for “YAML Ain’t Markup Language”. This sort of recursive wordplay is extremely common and oh so clever, but tells us little about what YAML actually is.

Fortunately, a more helpful description is on the official site:

YAML is a human friendly data serialization standard for all programming languages.

It’s somewhat amusing that the descriptor “human friendly” even exists. Somehow humans managed to make enough things that weren’t friendly for other humans that we now have something that can proudly announce that it’s not “human hostile”.

Anyway, YAML is a data serialization language designed for human interaction. It’s 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, as opposed to JSON, which uses brackets and braces.

The format lends itself to specifying configuration, which is how we use it at CircleCI.

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, it’s keys and values all the way down:

key: value

YAML Example: Scalar Types

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:

version: 2

Words in keys can be separated by underscores, dashes, or spaces. At CircleCI, we use underscores.

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:

command: |
    if [ "${CIRCLE_BRANCH}" == "master" ];
      then ansible-playbook site.yml -i production;
    fi

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

YAML Example: Collection Types

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

environment:
    TEST_REPORTS: /tmp/test-reports

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

docker:
    - image: ubuntu:14.04
    - image: mongo:2.6.8
      command: [mongod, --smallfiles]
    - image: postgres:9.4.1

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.

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 CircleCI builds to hang, but they’re also easily preventable by running your circle.yml/config.yml through an online validator.

Further Reading

The content in this guide should be all you need to comfortably write a config file for CircleCI. YAML does support additional features, which you can read about on the official site or the less intimidating (but less exhaustive) Learn X in Y minutes.

Want to learn more, or have additional YAML topics you’d like to see here? Bother me on Twitter: @alek_sharma