YAML can be tricky to get a hold of at first; after all, its name has changed meaning over time, from Yet Another Markup Language to YAML Ain’t Markup Language.

To understand YAML, it’s useful to explore what a markup language is. In short, a markup language combines a document written in plain text with annotations that describe various parts of that text. HTML is the best-known example, a language that supports online publication, adding links, embedded images, and structure to web pages.

Other common markup languages include XML and SGML; these are strongly associated with HTML, although they have different scopes and uses. There’s also Markdown, a very popular format that, despite its name, is also a markup language.

YAML is not really a markup language, though, as its acronym change reflects. YAML describes itself as a data serialization language, which really just means it’s a syntax for storing data. Think of YAML as less like HTML with data and more like JSON improved.

YAML dates back as far as 2001, but its first full release was in 2004. It’s been revised a handful of times since, with the latest version landing in 2021. Its files typically use one of two extensions: .yml or .yaml.

How is YAML different from JSON?

A bit like JSON with the rough edges sanded down

JSON is YAML’s closest well-known alternative. In fact, YAML is a superset of JSON, so any JSON file is also a valid YAML file. A simple YAML document looks much like JSON:

name:
    first: Jane
    last: Doe
age: 28
role: Engineer

The JSON equivalent of the above is:

{
    "name":
    {
        "first": "Jane",
        "last": "Doe"
    },
    "age": 28,
    "role": "Engineer"
}

At this level, YAML really isn’t that much different, although it’s definitely a bit nicer to read and write—for humans, at least. The language removes all those quotes, brackets, and commas in favor of a structure implied by line breaks and indentation.

YAML uses some constructs that are familiar from Markdown, like a set of rows, each beginning with a hyphen to represent a list:

fruits:
    - Apple
    - Banana
    - Cherry

You can easily combine the syntax for dictionaries (maps) and lists, in whatever hierarchy you need:

YAML also supports multi-line strings, which many JSON users will welcome. The first form, the literal block, preserves line breaks. It’s useful when they convey meaning:

address: |
  1600 Pennsylvania Avenue NW
  Washington, D.C.
  20500

The other type is called a folded block, and it treats line breaks as spaces:

info: >
  Folding allows long lines to be broken
  anywhere a single space character
  separates two non-space characters.

The folded type lets you lay out paragraphs however you want, much the same way that Markdown and HTML do.

Amusingly, the official YAML website presents itself in YAML syntax:

Although it’s clever, it demonstrates that YAML is better at representing data than it is at structuring the contents of web pages!

YAML is often used for configuration files, especially by more modern programs. For example, searching my user config directory for YAML files gives me the following:

Apart from gh, the GitHub command-line client, these are all TUI apps with a modern approach to configuration that differs from more traditional approaches like INI files, scripts, or bespoke formats.

The gh config file demonstrates an excellent use of YAML:

This config file has sensible defaults, blank values acting as templates, and comments to explain each setting. This is a marked improvement on JSON, which does not directly support comments—unless you’re using JSONC.

DevOps tools like Docker and Kubernetes have adopted YAML, at least partly for its ease of readability. The former’s Compose file and the latter’s object spec files both use YAML.

Meanwhile, the yq tool does for YAML what jq does for JSON: it lets you process a YAML file, extracting data from it or updating it.

You can use yq to convert JSON to YAML:

yq -P -oy file.json

You can edit data with it, like this example, which finds an item in an array, then changes it:

yq '(.[] | select(.name == "foo") | .address) = "12 cat st"'

YAML isn’t always a better choice than JSON, which has better interoperability as the more established format. But YAML’s advantages are quite significant, so it’s no surprise that, for configuration and related tasks, it’s often preferred.