YAML – Character Streams

YAML - Streams and Documents

YAML processes data as a stream of characters, which can be organized into one or more documents. Understanding these concepts is key to working effectively with YAML. Key components include:

• Directives: Instructions for the YAML parser.
• Document Boundary Markers: Indicators for the start and end of documents.
• Documents: Representations of single native data structures.
• Complete Stream: The entire sequence of characters representing YAML content.

This chapter will explore these components in detail.

Directives

Directives are instructions for the YAML parser. They are not part of the data model itself but can influence how the YAML content is interpreted. Directives begin with a percent sign (%) and are typically placed at the beginning of a stream or document.

The most common directive is %YAML, which specifies the version of the YAML specification the document adheres to. For example:

%YAML 1.2
---
# This document conforms to YAML version 1.2
message: "Hello, YAML 1.2!"

If the %YAML directive is omitted, parsers often default to a common version (e.g., YAML 1.2). While other directives like %TAG (for custom tag shorthands) exist, they are for more advanced usage and generally not needed for everyday YAML tasks.

Document Boundary Markers

YAML allows multiple documents within a single file or stream. Documents are separated by document boundary markers. The start of a document is indicated by three hyphens (---). The end of a document can optionally be indicated by three dots (...).

Here’s an example of a stream with multiple documents:

%YAML 1.2
---
document_id: 1
content: "First document in the stream."
...
---
# The %YAML directive is not needed for subsequent documents
# if they conform to the same version.
document_id: 2
content: "Second document."
...
---
document_id: 3
content: "Third document. The '...' end marker is optional for the last document."

The --- marker is essential for separating documents. The ... end marker is particularly useful when streaming documents or when you want to explicitly signal the end of a document before potential comments or other non-YAML content at the end of a file.

Documents

A YAML document represents a single native data structure, such as a mapping (dictionary/object), a sequence (list/array), or a scalar (string, number, boolean). Presentation details like comments, indentation styles, and directives are not part of the deserialized data itself but guide the parser.

Explicit Documents

An explicit document clearly begins with the document start marker (---). It can also optionally end with the document end marker (...). This is common when multiple documents are present in a stream.

---
# This is an explicit document
project_name: "YAML Revamp Project"
version: 2.0
settings:
  darkMode: true
  notifications: enabled
...

When parsed, this YAML would typically result in a data structure equivalent to the following JSON:

{
  "project_name": "YAML Revamp Project",
  "version": 2.0,
  "settings": {
    "darkMode": true,
    "notifications": "enabled"
  }
}

Implicit Documents

An implicit document does not start with the --- marker. This is very common for single-document YAML files, such as configuration files, where the start of the file implies the start of the document.

# This is an implicit document, common for config files
user_preferences:
  theme: dark
  language: en
  notifications:
    email: true
    sms: false

This would be parsed into a data structure equivalent to:

{
  "user_preferences": {
    "theme": "dark",
    "language": "en",
    "notifications": {
      "email": true,
      "sms": false
    }
  }
}

Complete Stream

A YAML stream is the entirety of the YAML content being processed, from start to finish. It can begin with an optional Byte Order Mark (BOM) to indicate character encoding (UTF-8 is highly recommended and widely supported). The stream may then contain directives, followed by one or more documents. Comments can appear almost anywhere and are ignored by the parser, not affecting the final data structure.

An example of a complete stream:

# Optional: Byte Order Mark (not visible in text editors usually)
# Comment at the beginning of the stream
%YAML 1.2
---
message: "Hello from the YAML stream!"
# End of the first document
...
---
# Start of the second document in the same stream
data_points:
  - 10
  - 20
  - 30
# Comments can appear here too

When working with YAML files, you are typically dealing with a single stream that might contain one or more documents. Understanding these structural elements helps in debugging issues and creating well-formed, maintainable YAML. For a comprehensive understanding, the official YAML specification (e.g., version 1.2) is an excellent resource. You can typically find it by searching for ‘YAML 1.2 specification’.