YAML Specification

YAML (YAML Ain’t Markup Language) is a human-friendly, Unicode-based data serialization language. It is designed to represent native data structures from agile programming languages (like Python, Ruby, and JavaScript) using three basic primitives:

• Mappings: Key-value pairs (hashes/dictionaries).
• Sequences: Ordered lists (arrays/lists).
• Scalars: Individual data values (strings, numbers, etc.).

YAML is commonly used for configuration files, log files, interprocess messaging, and object persistence.

YAML provides three flow scalar styles, each offering a different trade-off between readability and expressive power:

1. Double-Quoted (`"..."): Most expressive. Supports arbitrary strings via escape sequences. Best for strings containing special characters or requiring specific control characters (like tabs or newlines).
2. Single-Quoted ('...'): Moderate expressiveness. Supports printable characters. Escaping is limited to doubling single quotes ('').
3. Plain (unquoted): Most readable, least expressive. No escaping allowed. Highly sensitive to context and restricted by character combinations (like : or #).

The spec/1.2.2/ directory contains the raw source files (Markdown, YAML, and LaTeX) used to generate the published YAML 1.2.2 specification.

Key files include:

• spec.md: The primary YAML specification source file currently under development.
• links.yaml: A file used to manage internal link references to keep the main specification file clean.
• src/: Contains LaTeX source files for generating specification diagram images.
• ext/: Contains supplemental documentation including:
  • changes.md: Specification changes.
  • errata.md: Specification errata.
  • glossary.md: Specification glossary.
  • resources.md: External community and web resources.
  • team.md: Information about the YAML language development team.

YAML (YAML Ain't Markup Language) is a human-friendly, Unicode-based data serialization language designed to represent native data structures of dynamic programming languages. It is used for configuration, messaging, object persistence, and data auditing.

Its primary design goals, in decreasing priority, are:

1. Human readability.
2. Portability between programming languages.
3. Matching native data structures of dynamic languages.
4. Providing a consistent model for generic tools.
5. Supporting one-pass processing.
6. Expressiveness and extensibility.
7. Ease of implementation and use.

Every node in a YAML representation belongs to one of three kinds:

• Scalar: An opaque datum represented as zero or more Unicode characters.
• Sequence: An ordered series of zero or more nodes. Sequences can contain duplicate nodes or even contain themselves (cycles).
• Mapping: An unordered set of key: value node pairs.
  • Constraint: Each key in a mapping must be unique.
  • Flexibility: Keys can be any arbitrary node, and the same node can be used as a value for multiple keys.

Note: For theoretical and practical purposes, sequences can be viewed as mappings with integer keys starting at zero.

A YAML stream can contain multiple independent documents. There are three primary types of documents:

1. Bare Documents: Contain only content without any directives or markers. The first non-comment line must not start with a % character. Nodes are indented as if they have a parent at -1 spaces.
2. Explicit Documents: Begin with a directives end marker (---) but contain no directives. These can be completely empty.
3. Directives Documents: Begin with directives (e.g., %YAML 1.2) followed by a directives end marker (---).

Documents can be separated by markers to ensure unambiguous parsing, especially when content lines might otherwise look like directives.

# Bare Document
Key: Value

# Explicit Document
---
{ matches %: 20 }
...

# Directives Document
%YAML 1.2
---
!!str "Document"
...

Block scalars allow multi-line text blocks. They use specific indicators:

• | (Literal style): Preserves newlines.
• > (Folded style): Replaces newlines with spaces.

Node properties (like tags) can span multiple lines and must be indented by at least one more space than the parent block collection.

literal: |
  value
folded: >
  value

YAML allows tokens to be separated by multi-line (possibly empty) comments. This is useful for organizing large structures.

Constraints

• Implicit Keys: These are restricted to a single line and cannot be separated by multi-line comments.
• Indentation: Even if separation comments are not restricted by indentation, any structures following these comments must be properly indented to maintain valid YAML syntax.

{
  first: Sammy,
  last: Sosa
}:
# Statistics:
  hr: 65
  avg: 0.278