Skip to main content
Hello and welcome to this lesson. In this article we’ll cover what YAML files are and how to use them. If you already know YAML, you can skim this material — later lessons build on these concepts. If you’re new to structured data formats (or only know XML/JSON), these examples and exercises will help you get productive quickly. YAML is a human-friendly format for representing structured data, most commonly used for configuration. Below are three equivalent representations of the same data (a list of servers) shown in XML, JSON, and YAML. Compare them to see how YAML is typically more concise and readable. XML:
JSON:
YAML:
Take a minute to compare these three formats. Next, we’ll examine the YAML syntax and key concepts you’ll use in configuration files and manifests.

​
Basic key-value pair

A YAML mapping (dictionary) stores key-value pairs. Keys and values are separated by a colon followed by a space. Example:

​
Arrays / lists

A YAML sequence (array/list) uses a dash and a space for each element. Example:

​
Dictionaries (mappings)

A mapping groups named properties under a key. Here are nutrition details for two fruits represented as mappings:

​
Indentation matters

YAML uses indentation (spaces) to represent structure. Indentation must be consistent: items at the same level use the same number of spaces. Mixing tabs and spaces or using inconsistent indentation can change structure or cause parser errors. For example, these properties belong to Banana because they share the same indentation level:
If you accidentally indent Fat and Carbs more than Calories, YAML will treat those values as nested under Calories, which is usually invalid and causes parser errors.
Always use consistent spaces for indentation (do not mix tabs and spaces). Two spaces per level is common, but the important part is consistent indentation across the file.

​
Nested structures: lists of mappings and mappings in lists

YAML supports arbitrarily nested structures. You can combine sequences and mappings to represent complex objects. For example, a list of fruits where each element is a mapping containing nutrition properties:
This pattern (a sequence of mappings) is extremely common in configuration files, where each item in a list contains several named properties.

​
When to use a mapping vs a list

Use mappings (dictionaries) to represent a single object with named properties. Use sequences (lists) when representing multiple items of the same type. Example — a single car as a mapping:
Example — multiple cars as a list of mappings:
The table below summarizes the conceptual differences.

​
List of dictionaries (full example)

A longer sequence of object records (list of mappings):

​
Key notes: mappings vs sequences

  • Mappings are unordered collections of key-value pairs; key order is not significant for equivalence.
Example (same data, different order):
  • Sequences are ordered; changing the order changes the sequence:
These two sequences are not identical because the ordering differs.

​
Comments

Any text after a hash (#) on a line is treated as a comment and ignored by YAML parsers. Example:
Incorrect indentation or trying to use the same key for both a scalar value and a mapping will produce parser errors. Keep scalars and mappings separate, and maintain consistent indentation to avoid “mapping values are not allowed here” and similar errors.
That covers the YAML basics you need for the upcoming lessons. Try practicing these concepts with hands-on exercises and real configuration files (for example: Docker Compose, Kubernetes manifests, CI config files). Practicing will help you avoid common pitfalls like indentation mistakes and improper mixing of lists and mappings. Happy learning — practice small examples and build up to real-world manifests.

Watch Video

Practice Lab