YAML is designed to be readable, but the compact syntax can hide structural changes that would be obvious in JSON. A production review should answer two questions: is the stream valid YAML, and does the chosen parser construct the values the application expects?
Indentation carries structure
The YAML 1.2.2 specification uses indentation to define block scope. A formatter can normalize whitespace, but it cannot infer which parent a mistakenly indented key was intended to have.
Compare these two documents:
service:
name: api
limits:
cpu: "500m"
memory: "512Mi"
service:
name: api
limits:
cpu: "500m"
memory: "512Mi"
Both can be valid, but they describe different mappings. Validation alone cannot identify the intended one. Review the parsed tree or convert to JSON so the nesting becomes explicit.
Treat scalar typing as an application boundary
YAML 1.2 aligned its core schema more closely with JSON than YAML 1.1, but libraries and deployment platforms do not all use the same schema. Values such as yes, on, dates, numbers with leading zeros, and scientific notation deserve attention. Quote identifiers, version strings, durations, and values that must remain text.
This defensive version makes intent visible:
release: "2026-08-04"
featureFlag: "on"
regionCode: "01"
replicas: 3
Do not add quotes mechanically to every scalar. Booleans and numbers should remain typed when the consumer expects those types.
Review anchors and aliases in expanded form
Anchors reduce repetition, but a short alias can change many effective values. Some ecosystems also support merge keys even though merge behavior is not part of the YAML 1.2 core specification. Before approving a configuration with anchors, inspect the fully resolved object produced by the exact library used in production.
Put limits on aliases, nesting depth, and total input size when parsing untrusted YAML. These controls protect the application from documents whose expansion is much larger than their source text.
Preserve multiline intent
Literal blocks using | preserve line breaks, while folded blocks using > fold most line breaks into spaces. Chomping indicators control the final newline. A formatter should not switch these styles unless the resulting string has been compared byte-for-byte where that matters.
Review sequence
- Confirm that spaces—not tab indentation—define block structure.
- Parse with the same YAML version, schema, and library used by the target system.
- Inspect the constructed data tree or a JSON conversion.
- Verify text-like scalars, nulls, booleans, dates, and numeric-looking identifiers.
- Expand aliases and review the effective configuration.
- Compare multiline strings and final newline behavior.
- Run the target platform’s own validation before deployment.