YAML – Indentation and Separation

YAML - Indentation and String Representation

Indentation is fundamental to YAML’s structure, defining nesting and relationships between elements. Additionally, YAML offers flexible ways to represent strings. This chapter covers these critical aspects.

YAML Indentation

YAML uses spaces for indentation. Tabs are strictly forbidden as they can cause ambiguity due to varying tab widths across systems. The number of spaces for indentation is not fixed, but consistency within a given block is key.

• Defining Structure: Indentation indicates nesting. An indented block is part of the preceding, less indented item.
• Block Collections: Items in a block sequence (list) must share the same indentation level for their leading hyphen (-). Key-value pairs in a block mapping must also align.
• Flow Collections: Flow collections ({} for mappings, [] for sequences) are not indentation-sensitive for their internal elements but must be indented appropriately relative to their containing block.

A common practice is to use 2 or 4 spaces per indentation level.

Example of Indentation

The following invoice example demonstrates complex indentation to define its structure:

invoice: 34843
date: 2001-01-23
bill-to: &id001
  given: Chris
  family: Dumars
  address:
    lines: |
      458 Walkman Dr.
      Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to: *id001 # Using an alias
product:
  - sku: BL394D
    quantity: 4
    description: Basketball
    price: 450.00
  - sku: BL4438H
    quantity: 1
    description: Super Hoop
    price: 2392.00
tax: 251.42
total: 4443.52
comments: >
  Late afternoon is best.
  Backup contact is Nancy Billsmer @ 338-4338.

Incorrect indentation is one of the most common sources of errors in YAML files. Using a YAML-aware editor or linter can help catch these issues.

String Representation

YAML offers several ways to represent scalar strings:

• Plain (Unquoted) Scalars: If a string doesn’t start with special characters (like {, [, -, #, &, *, !, |, >, ', ", %, @, ```) and doesn’t contain problematic characters like : or # (colon-space or hash-space that are not part of a comment), it can often be written without quotes. Example: key: This is a plain string.
• Single-Quoted Scalars ('): Useful when you need to include special characters literally. Within single quotes, a literal single quote is represented by two adjacent single quotes (''). No other escaping is performed. Example: message: 'It''s a beautiful day!'.
• Double-Quoted Scalars ("): Allow for C-style escape sequences (e.g., \n for newline, \t for tab, \\ for backslash, \" for double quote). If an escaped newline (\ followed by a newline) occurs in a double-quoted string, it is typically folded into a space or removed, depending on the context. Example: alert: "File not found.\nPlease check the path.".
• Block Scalars: For multi-line strings, use literal style (|) or folded style (>), as discussed in a separate chapter.

Example: Using Strings in Nested Structures

This example shows various strings within a nested mapping, common in configuration files like internationalization (i18n) setups:

errors:
  messages:
    already_confirmed: "was already confirmed, please try signing in"
    confirmation_period_expired: "needs to be confirmed within %{period}, please request a new one"
    expired: 'has expired, please request a new one'
    not_found: 'not found'
    not_locked: "was not locked"
    not_saved:
      one: "1 error prohibited this %{resource} from being saved:"
      other: "%{count} errors prohibited this %{resource} from being saved:"

Choosing the right string style depends on the content of the string and readability preferences. Plain scalars are often preferred for simplicity when possible.