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.
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.
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 (
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.
#&*^ are all valid keys (but
!thing is not) . You can even use another map as a key!
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 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:
age attributes each map to simple scalars while
address is a full “object” with its own attributes
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 (
address) where address is then itself a map with four keys (
YAML has a few main primitive data types, called scalars. They are strings, numbers, and booleans – you’ve seen examples of them above!
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.
#) 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 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.