YAML

What is YAML?

YAML (short for “YAML Ain’t Markup Language”) is a text format for structured data, such as configuration files and API descriptions.
It represents the same kinds of data as JSON: objects, lists, strings, numbers, booleans, and null.
YAML uses indentation and line breaks where JSON uses braces, brackets, and commas. Long files are easier to read and write by hand as a result.
YAML files use the .yaml or .yml extension.
In this course, you write your OpenAPI specification in YAML.

YAML Syntax

Each rule below comes with a short example. The examples describe planets, like the rest of the course material.

Key-Value Pairs

A key-value pair is a key, a colon, a space, and a value.

name: Earth
radius: 6371
habitable: true

The space after the colon is required. YAML reads name:Earth as a single string, not as a key and a value.

Data Types

YAML decides the type of a value from the way it is written.

name: Earth          # string
radius: 6371         # number
gravity: 9.81        # number
habitable: true      # boolean
discovered_by: null  # null

Strings and Quotes

Most strings need no quotes, even when they contain spaces. Quotes are needed when YAML would otherwise read the value as something else.

Written as	YAML reads it as
`system: Solar System`	The string `Solar System`
`status: 200`	The number 200
`status: '200'`	The string `200`
`answer: true`	The boolean true
`answer: 'true'`	The string `true`
`version: 1.0`	The number 1.0
`version: 1.0.0`	The string `1.0.0`
`path: #/planets`	An empty value, because `#` starts a comment
`title: Planets: A Guide`	An error, because of the second colon

Single quotes and double quotes both work. Put quotes around a value in these cases:

The value looks like a number, true, false, or null, but you need a string.
The value contains a # or a colon followed by a space.

Nested Objects

To put an object inside another object, indent its keys under the parent key.

planet:
  name: Earth
  atmosphere:
    has_atmosphere: true
    main_gas: Nitrogen

Lists

Each list item goes on its own line and starts with a hyphen and a space.

moons:
  - Phobos
  - Deimos

A short list can also go on one line, as in JSON. An empty list is written [].

moons: [Phobos, Deimos]
rings: []

Lists of Objects

The hyphen starts a new item. The other keys of the item line up with the first key, not with the hyphen.

planets:
  - name: Earth
    habitable: true
  - name: Mars
    habitable: false

Multi-Line Text

A | after the colon starts a block of text that continues on the indented lines below it. The line breaks are kept.

description: |
  Returns a paginated list of planets.
  Results can be filtered by solar system.

Comments

A comment starts with # and runs to the end of the line. YAML ignores it.

# Planets in the Solar System
name: Earth  # the third planet

YAML Compared with JSON

YAML and JSON describe the same data in different notations.

Feature	JSON	YAML
Objects	Curly braces `{}`	Indentation
Lists	Square brackets `[]`	One hyphen per item
Separator between items	Comma	Line break
Quotes around keys	Required	Not needed
Quotes around strings	Required	Needed only in special cases
Comments	Not allowed	Start with `#`
Multi-line text	`\n` inside the string	A `\|` block
Use in this course	Request and response bodies	OpenAPI specification files

The two files below contain the same data.

# A planet and its moons
name: Mars
radius: 3390
habitable: false
atmosphere:
  has_atmosphere: true
  main_gas: Carbon Dioxide
moons:
  - name: Phobos
    radius: 11.3
  - name: Deimos
    radius: 6.2

{
  "name": "Mars",
  "radius": 3390,
  "habitable": false,
  "atmosphere": {
    "has_atmosphere": true,
    "main_gas": "Carbon Dioxide"
  },
  "moons": [
    { "name": "Phobos", "radius": 11.3 },
    { "name": "Deimos", "radius": 6.2 }
  ]
}

The YAML version has no braces, brackets, commas, or quotes, and it can carry a comment. The JSON version states its structure explicitly, so a wrong indentation cannot change its meaning.

Common Mistakes

Tabs instead of spaces: YAML rejects a file that is indented with tabs. Set your editor to insert spaces.
No space after the colon: name:Earth is a string, not a key-value pair.
Inconsistent indentation: Keys of the same object must start in the same column.
Unquoted special values: '200' and '#/components/schemas/Planet' need their quotes.
Misaligned list items: The keys of one list item must line up with each other.

The last mistake is the hardest to spot:

# Wrong: description does not line up with url
servers:
  - url: https://api.example.com/v1
  description: Production server

# Correct
servers:
  - url: https://api.example.com/v1
    description: Production server

Resources for Further Learning

YAML Specification ↗ - Official documentation.