Why does YAML require spaces instead of tabs?

YAML uses indentation to determine structure — unlike JSON's explicit brackets, YAML infers nesting from the number of leading spaces. Because tab characters have variable display width (a tab might appear as 2, 4, or 8 spaces depending on the editor settings) but are a single character to the parser, they create ambiguity — should one tab represent one indentation level or several? To avoid this ambiguity, the YAML spec simply forbids tabs for indentation. Tabs are allowed inside quoted string values but never for structuring.

How do I fix "mapping values are not allowed here" errors?

This is YAML's most common error message and almost always means you have an indentation error. A mapping value (the part after the colon in key: value) has been placed at the wrong indentation level or is missing a space after the colon. YAML requires exactly one space after the colon in a mapping — "key:value" is a string, not a mapping. Our validator flags the exact line with a fix suggestion showing the correct indentation for that nesting level.

Can YAML do everything JSON can?

YAML is a superset of JSON (in YAML 1.2). Anything you can express in JSON, you can express in YAML — plus comments, anchors and aliases, multi-line strings, explicit data types via tags, and more readable syntax without brackets. The trade-off is parser complexity: YAML parsers are larger, slower, and have more edge cases than JSON parsers. For machine-to-machine communication (APIs), JSON is usually better because it is simpler, faster, and universally supported. For human-maintained configuration, YAML is usually better because it is more readable and supports comments.

What are YAML tags and when do I need them?

YAML tags (!!str, !!int, !!float, !!null, !!timestamp, etc.) explicitly specify a value's data type, overriding YAML's automatic type inference. For example, !!str 123 forces the number to be treated as the string "123" rather than the integer 123. Tags are rarely needed in practice because YAML's type inference handles common cases correctly, but they are useful for: (1) forcing a value to be a string when it could be misinterpreted (e.g., version numbers like 1.10 being parsed as float 1.1); (2) custom types in frameworks that extend YAML.

How do I validate large Kubernetes or Docker Compose YAML files?

Paste your manifest into our formatter for instant syntax validation. For semantic validation (checking that your Kubernetes manifest uses valid API versions, required fields are present, and selectors match labels), pair our formatter with: `kubectl apply --dry-run=client -f manifest.yaml` (Kubernetes) or `docker compose config` (Docker Compose), both of which validate the structure without actually deploying. Our validator catches syntax errors, duplicate keys, and indentation issues before those tools even see the file.

Developer Tools2026-05-10

YAML Formatter: Format, Validate, and Beautify YAML Online

Q: What is the difference between YAML 1.1 and YAML 1.2?

YAML 1.2 (released 2009) is the current specification and makes two key changes from YAML 1.1: (1) it aligns YAML with JSON as a subset — any valid JSON document is also a valid YAML 1.2 document (in YAML 1.1, JSON is a subset but with some edge-case incompatibilities); (2) it removes the ambiguous boolean values — in YAML 1.2, only "true" and "false" (case-insensitive) are booleans, while YAML 1.1 also treated "yes", "no", "on", "off" as booleans. Most tools (Kubernetes, Ansible, Docker Compose) use YAML 1.1-compatible parsers with the broader boolean set.

YAML (YAML Ain't Markup Language) has become the configuration format of choice for the cloud-native ecosystem — Kubernetes manifests, Docker Compose files, Ansible playbooks, GitHub Actions workflows, and CI/CD pipelines are all written in YAML. Its human-friendly syntax (no brackets, no quotes required for simple strings, comments allowed) makes it more readable than JSON for configuration, but its reliance on indentation to define structure makes it uniquely error-prone. A single tab character where two spaces are expected, or a misaligned key at the wrong nesting level, can silently change the semantics of an entire configuration — or produce a cryptic parse error at line 47 for a problem that actually occurred at line 12. Our YAML formatter beautifies messy YAML with consistent 2-space indentation, validates syntax with precise error locations and plain-English explanations, and converts between YAML and JSON bidirectionally. It detects common pitfalls — tabs used for indentation (YAML forbids tabs), inconsistent indentation within the same document, duplicate keys (which YAML silently overwrites), and the Norway problem (unquoted country codes like 'NO' being interpreted as the boolean false). The tool handles multi-document YAML files (separated by ---) and supports the YAML 1.2 specification with anchors, aliases, tags, and multi-line string styles. All processing runs in your browser — your Kubernetes secrets, deployment configs, and CI/CD credentials never leave your machine.

code

YAML Formatter

Free · No registration

Try this tool for free →open_in_new

Step-by-Step Guide

Paste, Type, or Upload YAML

Paste your YAML into the editor or upload a .yaml / .yml file. The editor includes syntax highlighting for scalars, keys, sequences, and anchors. Multi-document YAML (documents separated by three hyphens ---) is detected and each document is formatted independently. The tool even handles YAML embedded in string fields (e.g., CloudFormation templates) by extracting and formatting the embedded YAML.

Format and Validate

Click "Format" to beautify the YAML with consistent 2-space indentation, proper quoting (adding quotes where needed for ambiguous values), and normalized anchor/alias references. The validator runs automatically and flags: tab characters (exact line and column), inconsistent indentation, duplicate mapping keys, and values that might be misinterpreted due to YAML's implicit type coercion. Each error links to the editor location with a fix suggestion.

Convert to JSON or Download

Use the "Convert to JSON" button to generate the equivalent JSON from your YAML — useful when a tool or API requires JSON input but you prefer writing configuration in YAML. The reverse ("Convert from JSON") is also available. Download the formatted YAML as a .yaml file, copy it to clipboard, or view the parsed data structure as an interactive tree.

Tips & Best Practices

check_circle

YAML 1.2 (2009) resolved the most notorious YAML gotcha: in YAML 1.1, unquoted "yes", "no", "on", "off", "true", and "false" are interpreted as booleans. Country codes like "NO" (Norway) and "YES" become boolean false and true — a bug so common it is called "the Norway problem." YAML 1.2 only recognizes "true" and "false" (case-insensitive) as booleans. Our formatter detects ambiguous values and recommends quoting them.

check_circle

The golden rule of YAML indentation: use 2 spaces per nesting level, never tabs. YAML 1.2 explicitly forbids tab characters for indentation (tabs have no indentation value — they appear as 0 in the parser's column counter). If you copy YAML from a source that converted spaces to tabs (some chat applications, web forms, or PDFs), the validator will flag every tab with its exact position.

check_circle

YAML anchors (&) and aliases (*) let you define a value once and reference it multiple times in the same document. For example: `defaults: &defaults timeout: 30 retries: 3` defines an anchor, and `service_a: <<: *defaults` merges those defaults into service_a. This is widely used in Docker Compose to share common configuration across services and in Kubernetes to reduce repetition in large manifests.

check_circle

Multi-line strings in YAML have two styles: the literal block scalar (|), which preserves line breaks — use this for shell scripts, SQL queries, or any content where line breaks matter; and the folded block scalar (>), which folds newlines into spaces (like HTML does) — use this for long paragraphs, descriptions, or text that should reflow. Override the default trailing-newline behavior with |- (strip trailing newline) or |+ (keep trailing newlines, including extra ones).

check_circle

YAML's support for comments (# comment) is the single biggest advantage over JSON for configuration files. Comments let you document why a value was chosen, link to Jira tickets, mark TODOs, and explain non-obvious settings — all without breaking the parser. JSON and JSON5 workarounds (like "__comment": "explanation") are hacks; in YAML, comments are first-class.

check_circle

The YAML merge key (<<) is a special mapping key that merges the keys from one mapping into another. It is part of the YAML 1.1 spec and widely supported though not in YAML 1.2 core. Docker Compose heavily uses the merge key with anchors to define service templates. However, the merge key has known edge cases with nested mappings — be explicit about deep merge vs shallow merge expectations.

check_circle

Validate YAML files in CI/CD before deployment. A malformed YAML that passes local testing but fails in CI wastes developer time. Add a YAML lint step to your pipeline: `yamllint .` or `python -c "import yaml; yaml.safe_load(open('config.yaml'))"`. Our online validator now integrates with GitHub Actions — add a badge to your repo that shows the validation status of your YAML configs.

check_circle

When debugging Kubernetes pods that fail to start with a cryptic "error converting YAML to JSON," the problem is almost always a YAML formatting error in your manifest. Our formatter catches indentation errors, duplicate keys (the last value wins silently in YAML — a common cause of mysteriously ignored settings), and fields placed at the wrong nesting level. Format your manifest, then reapply with kubectl.

Frequently Asked Questions

YAML 1.2 (released 2009) is the current specification and makes two key changes from YAML 1.1: (1) it aligns YAML with JSON as a subset — any valid JSON document is also a valid YAML 1.2 document (in YAML 1.1, JSON is a subset but with some edge-case incompatibilities); (2) it removes the ambiguous boolean values — in YAML 1.2, only "true" and "false" (case-insensitive) are booleans, while YAML 1.1 also treated "yes", "no", "on", "off" as booleans. Most tools (Kubernetes, Ansible, Docker Compose) use YAML 1.1-compatible parsers with the broader boolean set.

YAML's readability comes at a price — a single indentation mistake can break an entire deployment. Our formatter and validator catches those mistakes instantly, with human-readable error messages and exact line numbers. Whether you are writing Kubernetes manifests, Docker Compose files, or CI/CD pipelines, format and validate your YAML for free, right in your browser.

Try this tool for free →open_in_new