Sponsored placement
What Is YAML and Why Formatting Matters
YAML (YAML Ain't Markup Language) is a human-readable data serialization format used extensively in configuration files. Docker Compose files, Kubernetes manifests, GitHub Actions workflows, Ansible playbooks, GitLab CI pipelines, and many other infrastructure tools use YAML as their configuration format. Most CI/CD platforms and container orchestration systems read YAML natively.
YAML is whitespace-sensitive. The indentation level of each line determines the structure of the document. A single wrong indentation — an extra space, a missing space, or a tab character where spaces are expected — can cause the YAML parser to fail or, worse, silently misparse the structure and produce unexpected behavior in your pipeline or deployment.
YAML errors are notoriously difficult to spot visually. A tab character looks identical to multiple spaces in most editors unless whitespace visualization is enabled. A missing space after a colon in a key-value pair changes the key from a string to a scalar. A value indented at three spaces instead of two creates a nesting level that was not intended. This formatter catches the most common of these issues.
- Tab characters in indentation cause a parser error in strict YAML parsers
- Missing space after a colon (key:value instead of key: value) is a common syntax error
- Inconsistent indentation levels create unintended nesting
- Trailing whitespace on lines can cause issues in some YAML implementations
- Duplicate keys at the same level produce undefined behavior across parsers
Common YAML Syntax Errors and How to Fix Them
The most common YAML error is using tabs for indentation. The YAML specification explicitly disallows tabs. Many text editors insert tabs when you press the Tab key unless configured otherwise. Copying YAML from a web page or a tool that mixes tabs and spaces is another common source. This formatter replaces all tab characters with two spaces automatically.
The second most common error is omitting the space after a colon in a key-value pair. In YAML, key: value requires a space (or newline) after the colon for the parser to recognize it as a key-value mapping. Without the space, the entire key:value string is treated as a scalar string rather than a mapping entry. This is a silent error that produces wrong output rather than a parse failure.
Indentation inconsistency is the third category. YAML allows any consistent number of spaces as the indentation unit as long as it is consistent. Two spaces is the most common convention. If a file mixes two-space and four-space indentation, most parsers will fail. This formatter flags lines where the indentation level is not a multiple of two, which catches most inconsistency.
YAML vs JSON — When to Use Each
YAML and JSON are closely related — valid JSON is also valid YAML, since YAML is a superset of JSON. YAML adds comments (lines starting with #), multi-line strings (using | for literal blocks and > for folded scalars), and anchors and aliases for reusing values. These features make YAML preferable for human-authored configuration files where readability and comments matter.
JSON is preferable for machine-generated data, API responses, and cases where a strict, unambiguous format is needed. JSON has no implicit type coercion — strings must be quoted, booleans are true/false, and numbers are numbers. YAML has implicit type detection, which can cause surprises: the value yes, on, and no are parsed as booleans in some YAML versions, and port numbers like 0755 may be interpreted as octal.
Use YAML for CI/CD configuration, Kubernetes manifests, Docker Compose, Ansible, and other infrastructure files where humans write and maintain the configuration. Use JSON for API responses, configuration schemas, package.json, and any configuration that is generated or consumed by machines rather than written by hand.
Why marketers use this tool
- Fix common YAML errors: tabs, missing colon spacing, and inconsistent indentation
- Normalize indentation and trailing whitespace in one click
- Client-side processing — your YAML configuration files and secrets never leave your browser
Frequently Asked Questions
Why is YAML so sensitive to whitespace?
YAML uses indentation to represent data hierarchy, similar to how Python uses indentation to represent code blocks. This design choice makes YAML readable without braces or brackets, but it also means that any change in indentation — even a single space — changes the meaning of the document. The YAML specification made this trade-off deliberately: readability over strictness. This is why YAML is preferred for configuration files that humans write and maintain.
Can I use tabs in YAML?
No. The YAML specification explicitly states that tab characters are not allowed for indentation. Only space characters are valid. If a YAML parser encounters a tab character in indentation, it should raise an error. Some lenient parsers silently convert tabs to spaces, but relying on this behavior is not portable. Always configure your editor to insert spaces when you press the Tab key in YAML files.
Why does my YAML fail in GitHub Actions?
GitHub Actions YAML files fail most commonly because of tab characters in indentation, incorrect indentation levels for nested keys (steps inside jobs inside the jobs key), missing spaces after colons in key-value pairs, or strings that contain special characters (colons, hash signs, brackets) that need to be quoted. GitHub provides error messages with line numbers when a workflow file is invalid. The formatter in this tool can help catch common formatting problems before you push.
What is the difference between YAML and JSON?
JSON uses braces, brackets, colons, and commas to delimit structure. All strings must be in double quotes. There are no comments. YAML uses indentation to delimit structure, does not require quoting for most strings, supports comments with the # character, and supports multi-line strings with | and > block scalars. Valid JSON is also valid YAML (YAML is a superset), but YAML cannot always be converted to JSON because YAML supports features JSON does not, such as comments, anchors, and aliases.
How many spaces should I use for YAML indentation?
Two spaces is the most common and widely recommended YAML indentation convention. Most major tools and style guides use two-space indentation: Kubernetes documentation, GitHub Actions documentation, and Ansible all show two-space examples. The YAML specification does not mandate a specific number as long as it is consistent within the file, but two spaces has become the de facto standard for readability and compatibility.