YAML – Basics

YAML - Basics

YAML (YAML Ain’t Markup Language) is a human-readable data serialization language. It’s often used for configuration files, data exchange between languages, and object persistence. This chapter covers the fundamental rules and components of YAML.

Core Rules for Writing YAML

• Case Sensitive: YAML treats key and Key as different.
• File Extension: YAML files typically use .yaml or .yml as their extension.
• Indentation: Structure is defined by indentation. Crucially, use spaces for indentation, not tabs. Using tabs can lead to parsing errors or inconsistent behavior across different systems and editors.
• Consistent Indentation: The number of spaces per indentation level must be consistent within the same block. Two spaces are a common convention, but any number is fine as long as it’s consistent.

Basic Components of a YAML File

YAML primarily uses three basic types of structures:

1. Mappings (Key-Value Pairs / Dictionaries / Objects)

Mappings represent key-value pairs, similar to dictionaries in Python or objects in JavaScript. Each key is followed by a colon and a space, then its value.

# Block Style Mapping
name: John Smith
age: 33
occupation: Software Engineer

2. Sequences (Lists / Arrays)

Sequences represent ordered lists of items. In block style, each item in a sequence starts with a dash and a space (- ).

# Block Style Sequence
# Favorite movies
- Casablanca
- North by Northwest
- The Man Who Wasn't There

3. Scalars (Strings, Numbers, Booleans)

Scalars are the simple values like strings, numbers, or booleans. Examples: Casablanca (string), 33 (number), true (boolean).

Combining Structures and Inline Formats

YAML allows nesting these structures. You can also use inline (or “flow”) formats for compactness, which look similar to JSON.

# Inline (Flow) Sequence for a shopping list
shopping_list: [milk, groceries, eggs, juice, fruits]

# Inline (Flow) Mapping for a simple object
point: {x: 10, y: 20}

# Combining block and flow styles: A sequence of mappings
users:
  - {name: John Smith, age: 33} # Flow mapping within a block sequence
  - name: Mary Smith            # Block mapping within a block sequence
    age: 27

# A more complex structure
people:
  men: [John Smith, Bill Jones] # Mapping with a flow sequence value
  women:
    - Mary Smith                # Mapping with a block sequence value
    - Susan Williams

Synopsis of YAML Basic Elements

• Comments: Begin with # and extend to the end of the line. They are ignored by the parser.
• Indentation: Whitespace indentation (spaces, not tabs) defines the structure.
• Sequences (Lists): Items are denoted by a leading hyphen and space (- ) in block style, or enclosed in square brackets ([]) and comma-separated in flow style.
• Mappings (Dictionaries): Represented as key-value pairs separated by a colon and space (: ) in block style, or enclosed in curly braces ({}) and comma-separated in flow style.
• Scalars: Plain values (strings, numbers, booleans). Can be unquoted, single-quoted ('...'), or double-quoted ("...").
• Multiple Documents: Documents within a single YAML stream can be separated by three hyphens (---). An optional three dots (...) can mark the end of a document.
• Anchors and Aliases: For reusing data. An anchor (&anchor_name) defines a piece of data, and an alias (*anchor_name) refers to it.
• Tags: Explicitly specify data types using ! or !! (e.g., !!str, !!int). Often inferred.

Common Use Cases

YAML’s readability makes it popular for:

• Configuration files: Docker Compose, Kubernetes manifests, CI/CD pipelines (GitHub Actions, GitLab CI), application settings.
• Data serialization: Storing and transmitting structured data.
• Inter-process messaging: Exchanging data between different software components.

Learning Tip: Indentation is Key

The most common source of errors for beginners is incorrect indentation. Always use a consistent number of spaces for each level (e.g., 2 spaces). Most modern text editors can be configured to convert tabs to spaces automatically and help visualize indentation levels, making it easier to write valid YAML.