YAML – Collections and Structures

YAML - Collections and Document Structures

YAML’s power lies in its ability to represent structured data through collections (sequences and mappings) and to organize these collections within documents. This chapter explores how these elements combine to form complex data structures.

Block Collections

Block collections use indentation to define scope and structure. Each item in a block collection typically begins on a new line.

1. Block Sequences (Lists/Arrays)

Block sequences denote an ordered list of items. Each item is introduced by a dash and a space (- ).

# A sequence of player names (scalars)
players:
  - Mark Joseph
  - James Stephen
  - Ken Griffey

2. Block Mappings (Dictionaries/Objects)

Block mappings represent key-value pairs. Each pair is on its own line, with the key followed by a colon and a space (: ).

# A mapping of player stats (scalars to scalars)
stats:
  hr: 87        # Home runs
  avg: 0.298    # Batting average
  rbi: 149      # Runs Batted In

Nesting Collections

Collections can be nested to create more complex data hierarchies.

Mapping Scalars to Sequences

leagues:
  european:
    - Boston Red Sox
    - Detroit Tigers
    - New York Yankees
  national:
    - New York Mets
    - Chicago Cubs
    - Atlanta Braves

Sequence of Mappings

This is a very common pattern, representing a list of objects.

player_details:
  - name: Mark Joseph
    hr: 87
    avg: 0.278
  - name: James Stephen
    hr: 63
    avg: 0.288

Flow Collections (Brief Recap)

As a reminder, YAML also supports flow (inline) styles for collections, using explicit indicators:

• Flow Sequences: [item1, item2, item3]
• Flow Mappings: {key1: value1, key2: value2}

languages: [PHP, Perl, Python]
coordinates: {x: 10, y: 20, z: 5}

Flow styles are often used for simple collections or when embedding within block structures.

Document Structure

A YAML stream can contain multiple documents. This is useful for concatenating separate YAML files or for grouping related but distinct data sets.

Document Separators

• Start of Document (---): Three hyphens indicate the beginning of a new YAML document within a stream.
• End of Document (...): Three dots optionally mark the end of a document. This is useful for signaling the end of a document before a new one begins, or for stream processing.

# Document 1: Ranking of 1998 home runs
---
- Mark Joseph
- James Stephen
- Ken Griffey
...
# Document 2: Team ranking
---
- Chicago Cubs
- St Louis Cardinals
# End of stream, ... is optional here

Real-world application: Kubernetes configuration files often use --- to separate multiple resource definitions (e.g., a Deployment and a Service) in a single .yaml file.

Complex Mapping Keys

While most mapping keys are simple scalars (strings), YAML allows for complex keys, such as sequences or mappings themselves. To clearly denote a complex key, you can use a question mark followed by a space (? ) before the key.

# Mapping with a sequence as a key
match_dates:
  ? [New York Yankees, Atlanta Braves] # Complex key
  : [2001-07-02, 2001-08-12, 2001-08-14] # Value for the complex key
  ? [Boston Red Sox, Florida Marlins]
  : [2001-07-04, 2001-08-16]

# Another example with more explicit structure
# This indicates the start of a mapping entry where the key itself is structured
? - item1_in_key_sequence
  - item2_in_key_sequence
: value_for_sequence_key

Complex keys are less common but can be powerful for representing certain types of data relationships. However, for simplicity and broader compatibility (especially if converting to JSON, which only allows string keys), scalar keys are generally preferred.

By combining these collection types and structuring them within documents, YAML provides a flexible and readable way to model a wide array of data.