YAML Formatter & Validator

The YAML Specification

YAML (YAML Ain't Markup Language) is a human-friendly data serialization standard defined at yaml.org. Its central goal is readability: indentation replaces brackets, bare words replace quoted strings, and comments are permitted anywhere. YAML 1.1 shipped with most existing tools including Kubernetes, Docker Compose, Ansible, and Ruby on Rails. YAML 1.2, published in 2009, cleaned up a number of corner cases — most notably the boolean strings problem — but adoption of 1.2 has been slow; many parsers, including js-yaml in its default mode, remain closer to 1.1 behavior.

A YAML document describes a graph of nodes. There are three kinds of node: scalars (strings, numbers, booleans, null), sequences (ordered lists), and mappings (key–value pairs). Collections can use either block style — one item per line, indented under the parent key — or flow style, which looks exactly like JSON with curly braces and square brackets. The two styles can be freely mixed: a block mapping can contain a flow sequence, and vice versa. The --- token marks the start of a new document within the same file; ... optionally marks the end.

Scalar types are resolved automatically unless you wrap them in quotes. A bare 42 is an integer; 3.14 is a float; true and false are booleans; a tilde ~ or the word null becomes a null value. Multi-line strings use either the literal block scalar (|), which preserves newlines exactly, or the folded block scalar (>), which collapses newlines into spaces — useful for long prose that you want to keep readable in source but compact in the parsed output.

YAML vs JSON vs TOML

All three formats serialize structured data, but they are optimized for different contexts.

JSON is the universal lingua franca for web APIs — every runtime has a native parser and the format is unambiguous. YAML trades that simplicity for human ergonomics: the same Docker Compose file that would require careful bracket balancing in JSON reads naturally as YAML. TOML is the youngest of the three and has found a niche in tooling configuration (Cargo.toml for Rust, pyproject.toml for Python) because its section headers map very naturally onto nested tables without requiring significant indentation discipline.

Anchors and Aliases

YAML's anchor-and-alias mechanism lets you define a value once and reference it multiple times — essentially an inline constant system that JSON and TOML lack entirely. You mark a node with an anchor using an ampersand (&anchor-name) and then reference it elsewhere with an asterisk (*anchor-name). The parser replaces the alias with a deep copy of the anchored node at load time.

A common real-world pattern is a shared base configuration for Kubernetes deployments:

The << merge key is a YAML 1.1 extension supported by most tools — it merges all keys from the aliased mapping into the current one, with explicit keys taking precedence. This lets you DRY up repetitive configuration blocks without any templating language. Be aware that circular aliases are technically invalid and will cause most parsers to fail or loop.

Multi-Document YAML

A single YAML file can contain multiple independent documents separated by a --- line. This is used extensively in Kubernetes, where an entire application stack — Deployment, Service, ConfigMap, Ingress — can live in one file and be applied with a single kubectl apply -f stack.yaml. Each document is parsed independently: anchors defined in one document are not visible in the next.

When you use this tool's To JSON action on a multi-document file, the output is a JSON array where each element corresponds to one YAML document — the same shape that jsyaml.loadAll() returns natively. This is useful if a CI script needs to inspect manifest values using jq, which speaks only JSON.

Common Mistakes

The Tab Character

YAML specification section 6.5 explicitly prohibits tab characters as indentation — only space characters (U+0020) are allowed. This is the single most common YAML parse error, especially for developers coming from Makefiles or Go template files where tabs are structurally significant. Editors configured to insert tabs on the Tab key will silently produce invalid YAML. This formatter auto-detects and replaces tabs before parsing and reports when it has done so.

The Norway Problem

In YAML 1.1 (the version most tools implement), a set of bare words are automatically coerced to booleans: y, yes, Yes, YES, n, no, No, NO, true, false, on, off, and their case variants. The "Norway problem" refers to a famous incident where a YAML configuration map of ISO 3166-1 country codes broke because the key NO (Norway) was silently parsed as false instead of the string "NO". The same issue affects ON (Ontario, Canada) and any config value like enabled: yes where a boolean is intended but could equally be a string in a different context. YAML 1.2 reduced the boolean set to just true and false, but most parsers haven't fully migrated. Always quote values you intend as strings: country: "NO", enabled: "yes".

Indentation Inconsistency

YAML does not require a specific number of spaces per level — you can use 2, 4, or any consistent number — but you must be consistent within a block. Mixing 2-space and 4-space indentation within the same mapping will produce a parse error. The safest practice is to configure your editor to use 2 spaces for YAML files and stick to it.

Bare Colons in Values

A bare colon followed by a space (: ) always starts a new key–value pair in YAML. If your value contains a colon followed by a space — a URL, a time, an error message — you must quote the value: url: "https://example.com: 8080" or use a block scalar.

Worked Examples

Example 1 — Fixing a Kubernetes manifest with tab indentation. A developer copies a manifest from a Stack Overflow answer into their editor. The editor auto-converts leading tabs to spaces everywhere except inside the command list, which was pasted from a terminal. Running kubectl apply throws "yaml: line 14: found character that cannot start any token" — YAML's way of saying "unexpected tab". Pasting into this formatter auto-replaces the tab and the fix is applied transparently before re-parsing.

Example 2 — Converting Docker Compose to JSON for a CI script. A GitHub Actions workflow needs to extract the image name from docker-compose.yml to tag a build artifact. The workflow runs in a minimal Alpine container that has jq but not a YAML parser. Pasting the Compose file here and clicking To JSON produces a JSON object that jq '.services.api.image' can query directly, without installing any extra tools.

Example 3 — Detecting the Norway Problem. A configuration file maps country codes to VAT rates: NO: 0.25. The formatter raises a warning about bare boolean-like values. Quoting the key to "NO": 0.25 (or in YAML block style 'NO': 0.25) ensures the parser treats it as the string NO regardless of YAML version.

Frequently Asked Questions

Can one YAML file contain multiple documents? Yes. Separate them with a --- line. This is standard practice for Kubernetes manifests and some CI pipeline definitions. This tool handles multi-document files in all three modes (Format, To JSON, Minify).

How do I convert YAML to JSON? Use the To JSON button. The parsed YAML graph is serialized as formatted JSON. For a single-document file you get a JSON object or array; for a multi-document file you get a JSON array of documents.

Why does my YAML fail with "found character that cannot start any token"? This almost always means a tab character in the indentation. YAML 1.2 section 6.5 explicitly forbids tabs as indentation. Use the Format button — this tool auto-replaces tabs and reports the fix.

Are yes/no/on/off booleans or strings? In YAML 1.1 (the widely-deployed version) they are booleans. In YAML 1.2 only true/false are booleans. When in doubt, quote the value: answer: "yes" is always the string "yes" in any YAML version.

What file extensions should I use for YAML? Both .yml and .yaml are correct. The YAML FAQ recommends .yaml as the canonical extension, but .yml is more common in practice (Docker Compose, GitHub Actions). Many tools accept both; a few tools (notably older Ruby on Rails conventions) default to .yml.

Related Calculators

Working with JSON payloads? JSON Formatter & Validator parses, formats, and minifies JSON with depth and key-count stats. Need to decode a JWT token from a YAML-configured auth service? JWT Decoder splits and decodes JSON Web Tokens client-side. Building regex patterns for log parsing? The Regex Tester lets you test patterns against live input. Browse the full Developer Tools category for more.

Disclaimer

This tool is provided for educational and informational purposes only. All YAML parsing and conversion runs entirely in your browser using the js-yaml library — no data is transmitted to any server. While we strive for accuracy, users should verify results independently, particularly when dealing with YAML 1.1 vs 1.2 boolean coercion edge cases. We are not responsible for any errors, omissions, or damages arising from the use of this tool.