2026-09-13 · 8 min read
- yaml
- configuration
- parsing
A YAML stream can contain multiple documents. An explicit start marker introduces a document, an explicit end marker can close one, and a document may also begin implicitly depending on its position and parser mode.
Many application configuration contracts expect exactly one value even though the YAML parser supports streams. Loading only the first document can silently ignore attacker-controlled or accidentally appended configuration.
Declare cardinality and ordering
For single-document input, require a loader that errors when another document exists. For multi-document input, specify minimum and maximum counts, the meaning of each position or kind, ordering constraints, and whether empty documents are legal.
- Reject trailing documents in single-value APIs.
- Do not treat a null document as an absent document accidentally.
- Keep source ranges and diagnostics per document.
- Define whether directives are allowed and where.
Let the parser recognize markers
Do not split source text on lines that look like three dashes or three dots. Block scalars, quoted content, indentation, comments, directives, and document context determine whether those characters are syntax or data.
Anchors and aliases are document-scoped. Do not create an undocumented cross-document reference or merge layer in application code after parsing.
Validate resources and effective values
Apply duplicate-key rejection, tag restrictions, alias limits, nesting limits, scalar length, total stream size, document count, and schema validation to every document. Bound aggregate work as well as each individual value.
- Validate required and unknown fields per document kind.
- Preserve secret redaction while keeping useful source locations.
- Define overlay precedence outside generic YAML parsing.
- Retain original source when comments or presentation matter.
Build parser-parity fixtures
Use Flashman's YAML-to-JSON tool for non-sensitive individual documents, JSON formatter for effective values, diff for order and conversion, hash for fixture identity, and units converter for limits.
Test implicit and explicit starts, explicit ends, empty and null documents, comments, directives, marker text in block scalars, anchors at boundaries, malformed later documents, duplicate keys, BOM handling, CRLF, resource limits, and every parser version used from CI to production.