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, as opposed to JSON, which uses brackets and braces.

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

What is YAML diagram

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.

Read more: