Skip to main content
If you’re already comfortable with YAML, you can skip this section. If not, this concise primer will help you read and write YAML for tools like Docker Compose, Kubernetes manifests, CI pipelines, and many configuration files.
YAML (YAML Ain’t Markup Language) is a human-readable data-serialization format commonly used for configuration and data exchange. It is often more concise than XML and easier to scan than JSON because it uses indentation and minimal punctuation. Below are side-by-side examples that show the same data rendered in XML, JSON, and YAML so you can compare readability and verbosity. XML:
JSON:
YAML:
Take a moment to compare these formats — YAML uses less punctuation and often reads more naturally, especially for nested configuration. Quick table — when to use each format:

​
Simple key-value pairs

At its simplest, YAML represents key-value pairs with the syntax key: value. Remember to include a space after the colon.

​
Lists (arrays)

Lists are built using a dash (-) under a key. Each dash indicates an element in the sequence.

​
Dictionaries (mappings)

Mappings (dictionaries) group related properties under a key. Indentation determines nesting; maintain consistent indentation (commonly two spaces per level). Do not mix tabs and spaces. Correct example:
Incorrect indentation example (this will produce a parser error because Fat and Carbs are incorrectly nested under Calories):
If indentation is wrong, parsers typically emit an error such as:
Indentation matters. Do not mix tabs and spaces. Choose a consistent number of spaces per nesting level (two is common) and stick to it to avoid parser errors.

​
Complex nesting: lists of dictionaries

YAML supports arbitrary nesting: lists can contain dictionaries, and dictionaries can contain lists. Here is a list where each element is a dictionary describing a fruit:

​
Dictionary vs list — when to use which

Use mappings (dictionaries) to represent the properties of a single object. Use lists (arrays) to represent a sequence of objects of the same type.
A slide titled "Dictionary vs List of Dictionaries" with a simple car illustration. Four labeled boxes around the car show attributes: Color — Blue; Model — Corvette; Price — $20,000; Transmission — Manual.
Examples — single object, list of strings, and list of objects: A simple dictionary for a single car:
If you only need to store names for multiple cars (strings), use a list of strings:
If you want full details for each car, use a list of dictionaries (each item is a dictionary):

​
Order: dictionaries vs lists

  • Mappings (dictionaries) are unordered collections of key-value pairs. The order of keys typically does not matter:
is equivalent to:
  • Lists (arrays) are ordered collections. The order of items matters:
is not the same as:

​
Comments

Lines beginning with # are treated as comments and ignored by parsers:

​
Summary

YAML is a readable, widely used format for configuration. Remember:
  • Use key: value for mappings.
  • Use - for list items.
  • Maintain consistent indentation (no tabs).
  • Choose mappings vs lists based on whether data is unordered key/value pairs or an ordered sequence.
  • Use comments starting with #.
That’s the YAML primer. You’re now ready to proceed to the exercises.

Watch Video

Practice Lab