2026-09-13 · 6 min read · Rahul Chitturi
- yaml
- configuration
- parsing
YAML can contain a stream of zero or more documents separated by marker lines. A loader that expects one document may reject trailing content, silently return only the first value, or expose a collection that application code never validates.
Separator-looking text inside a quoted or block scalar is content, while directives and explicit end markers have stream-level meaning.
Choose a single- or multi-document contract
If a configuration accepts exactly one document, use a parser mode that rejects additional documents. If streams are supported, define document count, ordering, allowed empty documents, schemas, and whether directives may change between documents.
- Do not split YAML with a line regular expression.
- Keep source locations per document.
- Reject duplicate keys inside every mapping.
- Apply alias and size limits across the stream.
Validate each effective document
Parse with one maintained YAML implementation, then validate every document against the schema assigned to its position or declared kind. Do not merge documents implicitly unless precedence and deletion semantics are part of the application contract.
When converting to JSON for inspection, remember that comments, anchors, tags, and document boundaries can be lost. Preserve the original YAML as the authoritative review artifact.
Test harmless stream fixtures
Use YAML-to-JSON on synthetic individual documents, JSON formatter for effective values, diff for document ordering, and hash for public fixture identity.
Test implicit and explicit starts, explicit ends, empty documents, directives, markers in block scalars, comments, anchors across boundaries, duplicate keys, malformed later documents, byte-order marks, and parser upgrades.