An Introduction to YAML for Makers

120

2026-08-03 | By Maker.io Staff

Programs often need to store data, like user settings, and exchange it with other tools and services. Numerous formats exist to make representing such data easier, and YAML is one of the most widely used ones. This article introduces the basics of such data formats and shows how YAML is commonly used in practice.

Image of An Introduction to YAML for Makers

Serialization Languages and YAML

YAML is a serialization language, commonly used by developers to store application configuration files. Serialization languages are standardized data formats for representing structured data in a way that different systems can reliably store and parse them. Unlike binary data formats, YAML and other human-readable serialization formats are designed to allow people to also read, understand, and edit the data directly without needing any specialized software.

Common examples of other serialization languages include JSON and XML. Compared to these two, YAML puts a stronger emphasis on readability by reducing visual noise in the files and focusing on the actual data values stored in the file. For this and many other reasons, YAML has been adopted in many programming languages and is even the de facto standard in multiple systems, like Docker Compose, GitHub Actions, CI/CD pipelines, and OpenAPI specifications.

Core YAML Concepts

YAML differentiates three basic node types: scalars, sequences, and mappings. Scalars, which represent a single primitive value with no internal structure, are the most basic unit of data that can be stored. YAML supports strings, numbers, booleans, and null values. What’s interesting and important to remember is that, unlike many other languages, YAML allows using on/off, yes/no, and true/false for boolean values. Each scalar has a name followed by its value, separated by a colon character. The following snippet contains a few examples of scalar values:

Copy Code

name: Ben
age: 28
active: true
admin: no
nickname: null

Sequences in YAML are ordered lists of values. Lists in YAML can mix data types and contain nested lists. However, mixing types is not commonly done in practice to avoid confusion. In YAML, sequences are defined by using a name as the key, then indenting the list underneath it with spaces, and placing each list entry on its own line with a dash in front of it:

Copy Code

flavors:
  - banana
  - apple
  - cherry

Nested sequences can be defined the same way. However, each nested list’s entries have to be indented by another layer:

Copy Code

flavors:
  - fruit:
    - banana
    - apple
    - cherry
  - spices:
    - cinnamon
    - gingerbread
  - specials:
    - chocolate
    - 'caramel fudge'

YAML is a whitespace-sensitive language, meaning that blocks and levels in YAML files are defined by how far they are indented compared to their parent. It’s important to note that YAML only supports whitespaces, not tabs. However, the language is very flexible regarding the number of whitespaces, as long as it’s done consistently. Most YAML files use one, two, or four spaces in practice.

Lastly, mappings are unordered sets of key-value pairs. They represent a set of named values, for example, values that belong to an entity, such as a user. There are no restrictions on a mapping’s length or complexity, and they can contain scalars, lists, and nested mappings. However, each key within a mapping must be unique. Mappings in YAML are defined by writing their name as the key, then indenting the nested content underneath it, and expressing each entry as a key-value pair on its own line, as shown in this example:

Copy Code

user:
  name: Dan
  role: admin
  nicknames:
    - FudgeLord123
    - Admin
  birthday:
    year: 2050
    month: 12
    day: 31

All of the three basic types can be nested inside each other to build more complex structures.

Organizing YAML Documents

Aside from the core syntax to represent data, YAML also defines additional structures to help organize larger and more complex files. Comments let developers add notes to configuration files, provide samples, or temporarily turn off certain keys. YAML comments start with a pound symbol, and everything on the same line following the symbol is ignored when parsing the file:

Copy Code

user:
  # These values belong together to a user entity
  name: Dan
  role: admin
  # You can nest lists inside mappings
  nicknames:
    - FudgeLord123
    - Admin
  # But mappings can also include other mappings!
  birthday:
    year: 2050
    month: 12
    day: 31
  # The next lines will be ignored
  # favoriteIceCreamFlavors:
  #   - chocolate
  #   - peanutButter

Lastly, a single YAML file can contain multiple YAML documents. Such a document is a complete self-contained set of data that can represent something like a single user, a service config, or any other structured entity.

YAML documents are separated by three dashes, which mark the beginning of a new document. The dashes are optional if a file contains only a single document. The end of a document can be marked by three period characters. However, that is optional and rarely used:

Copy Code

name: Alice
role: admin
active: true
---
name: Bob
role: editor
active: false
---
name: Carol
role: viewer
active: true
... # completely optional; rarely used in practice

Strings in YAML

Strings in YAML are worth paying extra attention to to avoid misconceptions and errors. There are multiple ways to write strings in YAML, and the examples so far used all three of them interchangeably:

Copy Code

name: Ben Tester
location: “Utica\nNew York, NY”
picture: ‘C:\Users\ben\nonpublic\profile.png’

Strings that do not start or end with whitespace characters do not need to be put in quotes. The same applies to strings that do not contain any special characters with a reserved function in the language, such as the pound symbol. Strings with special characters, escape sequences, or Unicode must be contained within quotes.

Single quotes can be used to define strings that have special characters, but where escape sequences should be ignored. This can be the case in file paths, for example, where \n should not be interpreted as the newline character. Strings where escape sequences should be respected must be enclosed with double quotation marks.

Multi-line text can be entered using string blocks. YAML distinguishes two basic types: literal block scalars and folded block scalars. Literal block scalars are defined with a pipe symbol, and they represent multi-line strings that preserve line breaks:

Copy Code

text: |
  This is a
  multi-line string

Folded block scalars combine all lines into a single line without preserving line breaks. They are defined using a greater-than symbol:

Copy Code

text: >
  This is a
  folded string

Good Practices for YAML and Common Mistakes

Although YAML is designed to be easy to read, a few small but common mistakes can break files or make them confusing. Sticking to a few good practices can help avoid most of them.

The first is consistent indentation. YAML does not allow tabs for indentation, only whitespace. The number of spaces should also be consistent throughout the document. Most files use one, two, or four spaces per indentation level, and each nested level should increase by the same number.

Next, files should be kept concise, and long files should be split by logical groups. Key names should be consistent and descriptive.

Strings that could be misinterpreted should be escaped. That includes strings containing only numbers or values that could be misread as boolean flags, for example, yes and no. Use double quotes if the string contains escape sequences. Otherwise, use single quotes.

Add comments only where useful and necessary. Do not use them to restate the obvious, and do not leave commented-out blocks of obsolete code in the YAML. Keeping comments focused prevents them from becoming visual clutter.

Summary

YAML is a serialization language for storing data and exchanging it between different services. Unlike binary serialization formats, YAML is a human-readable format that prioritizes readability over conciseness.

The language defines three basic node types: scalars, sequences, and mappings. Scalars represent primitive data, sequences are ordered lists of values, and mappings are key-value sets of elements. These three basic types can be nested inside each other to build more complex structures. YAML defines hierarchy by how far lines are indented. Only whitespaces are allowed, and indentation levels should be kept consistent throughout a file.

Strings that do not start or end with whitespace and do not contain any special characters or escape sequences can be written without quotes. Strings with special characters but without escape sequences should be enclosed in single quotes. All other strings should be enclosed in double quotation marks.

A few good practices include keeping files short, using meaningful key names, escaping strings correctly, and avoiding unnecessary comments.

Have questions or comments? Continue the conversation on TechForum, DigiKey's online community and technical resource.