Complete Guide to YAML Validation and Linting
YAML is a human-readable data-serialization language commonly used for configuration files. While its indentation-based syntax is clean, it is notorious for hidden pitfalls. A dedicated YAML validator is essential to enforce structure and schema compliance before deployment.
What is YAML Validation?
YAML validation is the process of checking a YAML document to ensure it is well-formed according to the YAML specification. It goes beyond syntax checking to verify structural correctness, identify duplicate keys, enforce formatting rules, and validate against domain-specific schemas (like Kubernetes or Docker).
Why YAML Validation Matters for DevOps
In modern DevOps, YAML configures CI/CD pipelines, container orchestration, and infrastructure as code. A single indentation error or unquoted boolean can bring down production pipelines. Validation prevents these catastrophic configuration errors early in the development lifecycle.
Common YAML Syntax Errors
The most frequent YAML errors include tab characters instead of spaces, inconsistent indentation levels, unescaped quotes in strings, missing space after a colon or dash, and duplicate dictionary keys. Our validator instantly highlights these issues with exact line numbers.
YAML Indentation Rules
YAML relies on indentation for structure, similar to Python. You must use spaces (not tabs) for indentation. The standard is 2 spaces per indentation level. Misaligned items in a list or inconsistent spacing in nested mappings are the leading causes of parsing failures.
Understanding Anchors and Aliases
YAML allows data reuse through anchors (&) and aliases (*). This reduces duplication in large configurations. However, undefined aliases or complex recursive references can break parsers. Validation ensures all aliases point to correctly defined anchors.
The Norway Problem Explained
In YAML 1.1, unquoted strings like NO, YES, ON, and OFF are parsed as boolean false or true. If you configure a country code as country: NO, parsers interpret it as a boolean. This is known as the "Norway Problem." You must quote these strings (country: "NO").
YAML 1.2 vs 1.1 Key Differences
YAML 1.2 aligns closely with JSON, effectively making JSON a strict subset of YAML 1.2. Crucially, YAML 1.2 resolves the Norway problem by dropping implicit boolean conversions for words like yes/no and on/off, restricting booleans strictly to true and false.
Kubernetes YAML Best Practices
Kubernetes manifests require strict schema adherence. Best practices include consistently defining apiVersion and kind, properly quoting string numbers (like "1.20") to prevent float truncation, explicitly defining namespace scopes, and aligning pod template labels with deployment selectors.
Docker Compose Validation Tips
Docker Compose files are highly structured. Key validation checks include verifying service cross-references in depends_on blocks, ensuring port mappings are correctly typed (often requiring quotes like "8080:80"), and checking valid volume mount declarations and network aliases.
GitHub Actions Workflow Validation
GitHub Actions workflows fail silently if the YAML is invalid. Essential validation includes checking on triggers, ensuring runs-on environment definitions exist, verifying uses action paths, and validating the DAG (Directed Acyclic Graph) of job dependencies defined by the needs keyword.