YAML Basics

YAML is built with a relatively simple syntax that can represent quite complex data. On this page you’ll find some of the basic syntax that you’ll encounter when using YAML.

Data Structures

At its core YAML utilizes maps, lists, and indentation to structure data. Let’s look at each of those three separately before we combine them together.

Maps

A map is a collection of key->value pairings. You may be familiar with these if you’ve ever worked with Python dictionaries or HashMaps in other languages. Each key must be unique, values can be anything, and ordering does not matter. Let’s look at some examples.

name: Chris
age: 27

This is a simple map that represents a person’s name and age. There are two keys (name and age), and each maps to a particular value. Since ordering does not matter the above map is equivalent to the following one:

age: 27
name: Chris

Maps in YAML are represented by this key: value syntax. A key can be nearly anything as long as all keys are unique and the key does not start with a reserved character  (e.g. !) – name, 34, thing!, and #&*^ are all valid keys (but !thing is not) . You can even use another map as a key!

Lists

A list is a sequence of ordered values. Arrays in many programming languages are implementations of lists. For example, a list of your favorite foods may be:

pizza, burgers, pasta, sushi

In YAML lists are often called sequences and are represented by a combination of dashes (“-”) and newlines. Our list of favorite foods would look like this in YAML:

- pizza
- burgers
- pasta
- sushi

Unlike in maps, ordering matters in YAML lists. A list with the same four foods in a different order is not equivalent to the one above.

Indentation

Indentation is used in YAML to create nesting, or parent/child relationships. This is similar to how scoping works in Python. For example we can define a complex “user” data structure using indentation to neatly organize each field:

user:
  id: 123
  name: Bob
  address:
    line: 123 Main Street
    city: Boston
    state: MA
    zip: 02114

This is a hierarchical structure. user has three attributes: id, name, and address. The name and age attributes each map to simple scalars while address is a full “object” with its own attributes line, city, state, and zip

Putting all three of these together allows us to create complex structures that can represent just about anything. Let’s expand on our user example from above. We can store multiple users by doing something like the following:

users:
  -
    id: 123
    name: Bob
    address:
      line: 123 Main Street
      city: Boston
      state: MA
      zip: 02114
  -
    id: 456
    name: George
    address:
      line: 177 North Avenue NW
      city: Atlanta
      state: GA
      zip: 30313

Starting from the top, we have a map called users that points to a list. Each entry in that list is a map containing three keys (id, name, and address) where address is then itself a map with four keys (line, city, state, and zip).

Data Types

YAML has a few main primitive data types, called scalars. They are strings, numbers, and booleans – you’ve seen examples of them above!

Strings

Like in most languages, strings in YAML are sequences of characters. Unlike most languages though, you don’t necessarily need to enclose strings in quotes. The following is a completely valid string representation:

quote: To be or not to be

There are cases where you will need to use quotes though. Any string that starts with a YAML reserved character (e.g. ! or #) will need to be enclosed by quotes. There are two ways of doing this – single quotes (‘’) or double quotes (“”). Single quotes do not allow for escape sequences, i.e. the string will be interpreted literally. Double quotes will respect escape sequences.

Numbers

Numbers can take many forms. You can use integers (13), floats (13.5), exponentials (1.2e+4), hexadecimals (0xCC), and octals (0o12). You can also represent specific concepts like infinity (.inf).

Covered the YAML Basics?

Feel like you have a good understanding of the YAML Basics? Check out our Language Features page to go further into depth on each topic and see more, or head on over to Common Examples to see some real-world examples of YAML usage. There are also several good resources at yaml.org.