YAML – Syntax Primitives

YAML - Core Syntax Concepts

Understanding YAML’s syntax primitives helps in writing valid and effective YAML documents. This chapter delves into key structural and formatting rules that govern how YAML is parsed and interpreted.

Fundamental Structural Concepts

1. Indentation

Indentation is how YAML defines nesting and structure. It must be done with spaces, not tabs. The number of spaces for an indentation level must be consistent within a given block, though different blocks can have different indentation levels (e.g., a parent uses 2 spaces, a child might use 4, but all siblings at one level must use the same). More indentation means a deeper level of nesting.

2. Context: Block vs. Flow Styles

YAML content can be written in two main contexts:

• Block Styles: Use indentation to denote structure. This is often preferred for readability with complex data (e.g., multi-line strings, nested mappings/sequences).
• Flow Styles: Use explicit indicators like {} for mappings and [] for sequences, similar to JSON. Flow styles are more compact and often used for simple data or when embedding small collections.

3. Scalar Styles

Scalar content (strings, numbers, booleans) can be presented in several styles: plain (unquoted), single-quoted, double-quoted, literal block (|), and folded block (>). Each has different rules for handling whitespace, newlines, and special characters (covered in detail in ‘Scalars and Tags’).

4. Chomping: Controlling Newlines in Block Scalars

Chomping controls how final newlines are handled in block scalars (both literal | and folded >). It’s specified by adding an indicator (- or +) after the style character:

• Clip (default, no indicator or just | or >): A single trailing newline is kept if present in the content; otherwise, no newline is added. Multiple trailing newlines are reduced to one.
• Strip (|- or >-): All trailing newlines are removed. The scalar value will not end with a newline.
• Keep (|+ or >+): All trailing newlines from the block are preserved in the scalar’s value.

Example of Chomping Effects:

# Input YAML
clip_example: |
  Line 1
  Line 2

strip_example: |-
  Line 1
  Line 2

keep_example: |+
  Line 1
  Line 2

Parsed String Values (represented with \n for newline):

// For clip_example (assuming content ends with one newline):
// "Line 1\nLine 2\n"

// For strip_example:
// "Line 1\nLine 2"

// For keep_example (assuming content ends with two newlines):
// "Line 1\nLine 2\n\n"

Indentation Spaces

As emphasized, indentation uses spaces to define structure. The amount of leading whitespace determines an item’s nesting level relative to its parent. Tab characters are forbidden for indentation.

# YAML document
level1_key:
  level2_key: # Indented relative to level1_key
    level3_value: "Nested deep"
  another_level2_key: "Sibling to level2_key"
another_level1_key: "Sibling to level1_key"

Equivalent JSON structure:

{
  "level1_key": {
    "level2_key": {
      "level3_value": "Nested deep"
    },
    "another_level2_key": "Sibling to level2_key"
  },
  "another_level1_key": "Sibling to level1_key"
}

Separation Spaces

YAML uses spaces to separate tokens, for example, between a key and its value (key: value), or after a sequence indicator (- item). While multiple spaces can be used, one is usually sufficient. These separation spaces are generally not part of the content, unlike indentation spaces which define structure.

# Correct separation
key1: value1
- item1

# Also valid, but less common
key2   :    value2
-    item2

Line Folding in Plain Scalars

Plain (unquoted) scalars can span multiple lines. YAML’s line folding rules generally convert single newlines within a plain scalar into a space. A blank line (two newlines) is typically preserved as a single newline, effectively creating a paragraph break. This allows for writing readable long strings without explicit line break characters like \n.

folded_plain_scalar:
  This is a long sentence
  that continues on the next line.
  It will be parsed as a single line of text.

  This new paragraph, started after a blank line,
  will also be parsed with a newline character preceding it.

Parsed string value for folded_plain_scalar:

"This is a long sentence that continues on the next line. It will be parsed as a single line of text.\nThis new paragraph, started after a blank line, will also be parsed with a newline character preceding it."

This behavior is distinct from literal block scalars (|) which preserve all newlines, and folded block scalars (>) which offer more explicit control over folding and paragraph breaks.

Tip: Using a YAML linter or validator integrated into your editor can help catch common syntax errors related to indentation, spacing, and special characters, ensuring your YAML is well-formed.