YAML Formatter

Format and validate YAML instantly in your browser

The YAML formatter validates and beautifies your YAML in real time as you type or paste — no button press needed. It normalises indentation, highlights syntax errors with line numbers and explanations, and provides one-click conversion to JSON. The editor has full syntax highlighting using CSS custom properties that adapt to your system's dark or light mode preference. Everything runs client-side using a JavaScript YAML parser — your config files never leave your device.

YAML (YAML Ain't Markup Language) is used in almost every modern software project: GitHub Actions workflows, Kubernetes manifests, Docker Compose files, Ansible playbooks, Helm charts, CI/CD configurations, and application config files. It's human-readable by design, but its indentation sensitivity and special-character quirks make it surprisingly easy to write invalid YAML that only fails at runtime — when it's too late. A live formatter catches those errors in seconds.

Common YAML errors and how the validator catches them

The most common YAML mistake is using tabs instead of spaces. YAML forbids tab characters in indentation — they look identical to spaces in most text editors but cause immediate parse failures. The validator catches this and tells you exactly which line has the tab. The second most common mistake is unquoted colons in values: `title: Hello: World` is ambiguous — the parser sees a nested key. Quote the value: `title: "Hello: World"`. Third is inconsistent indentation: if a block is indented by 2 spaces in one place and 3 in another, the parser may misread the nesting level.

Other common errors: duplicate keys in the same mapping (technically allowed in YAML 1.1 but illegal in 1.2, and rejected by most parsers); missing spaces after colons (`key:value` is invalid, needs `key: value`); anchors and aliases used incorrectly; and implicit type coercion surprises (the string `yes` becomes a boolean `true` in YAML 1.1 parsers). The validator reports each of these with clear language, not just a raw parser error dump.

YAML to JSON conversion — when and why

JSON and YAML are semantically equivalent data formats (with a few exceptions). YAML is a superset of JSON — valid JSON is also valid YAML. Converting YAML to JSON is useful when working with tools or APIs that accept only JSON, or when you want to use `jq` to query a YAML config file (jq operates on JSON). The "Copy as JSON" button parses your YAML and serialises it to formatted JSON with 2-space indentation.

One important note: YAML comments (lines starting with `#`) are not preserved in the JSON output because JSON has no comment syntax. YAML anchors and aliases are resolved — the JSON shows the final dereferenced values. Multi-document YAML (multiple docs separated by `---`) is converted to a JSON array containing each document as an element. If you need the reverse (JSON to YAML), paste the JSON into this formatter — since JSON is valid YAML, it will parse and reformat it cleanly.

YAML formatter vs yamllint, YAML Lint, and YAML Checker

yamllint is the gold standard CLI tool for YAML linting — thorough, configurable, and used in CI pipelines. But it requires Python, pip, and a terminal, making it inaccessible for quick checks on a team member's machine or in a browser environment. YAML Lint (yamllint.com) is the most popular online alternative but only shows errors — no formatting, no syntax highlighting, no JSON conversion. YAML Checker (yamlchecker.com) formats and validates but has a plain textarea without highlighting and no JSON output. Transform.tools does YAML-to-JSON conversion but no live validation.

This formatter combines all of those capabilities in one place: live validation with error explanations, formatted output with syntax highlighting, one-click JSON conversion, and multi-document support — running entirely in your browser with no backend. It's the fastest path from "is this YAML valid?" to "here's the formatted, error-free version" for developers who prefer not to install tools or sign up for services.

Practical uses — Kubernetes, GitHub Actions, Docker Compose

For Kubernetes users: paste your manifest before applying it with `kubectl apply` to catch syntax errors early. A single indentation mistake in a Pod spec or a Service definition will cause `kubectl` to fail with a cryptic error; catching it here first saves time. For GitHub Actions users: paste your `.github/workflows/*.yml` file to validate before committing. Malformed workflows fail silently (the action just doesn't run) and debugging them in the GitHub UI is slow. For Docker Compose users: validate your `docker-compose.yml` before running `docker compose up` — especially important for multi-service files where a nested service definition error can be hard to spot.

For Ansible users: paste playbooks, inventory files, or variable files to validate YAML structure before running `ansible-playbook`. For Helm chart authors: validate your `values.yaml` or chart templates. For anyone writing CI/CD configuration in YAML (GitLab CI, CircleCI, Bitbucket Pipelines, Travis CI): paste the config and validate before pushing. In all these cases, the cost of an invalid YAML file is a failed build or deployment — catching it here first is always faster.

YAML's origin, philosophy, and the Norway Problem

YAML — a recursive acronym for "YAML Ain't Markup Language" (originally "Yet Another Markup Language" when Clark Evans and Ingy döt Net created it in 2001) — was designed around a single guiding principle: human readability with minimal punctuation. Where XML wrapped content in angle-bracket tags and JSON required quotes around every key, YAML used plain text, indentation, and colons. The result is configs that read almost like prose. YAML 1.2, published in 2009, formalised an important relationship: every valid JSON document is also valid YAML 1.2, making YAML a strict superset of JSON and unifying the two most common serialisation formats in modern software.

That clean design history comes with a cautionary tale known as the Norway Problem. In YAML 1.1 — the version implemented by PyYAML, Ruby's Psych, and most YAML libraries written before 2010 — bare words like yes, no, on, off, true, and false were all silently coerced to booleans. A Kubernetes config that listed Norway's ISO country code as the string NO would be parsed as the boolean false, silently corrupting the configuration. The same trap caught ON (boolean true), off (boolean false), and dozens of other innocent strings. YAML 1.2 fixed this by restricting implicit boolean coercion to exactly true and false — but the fix only applies to parsers that implement 1.2, and a large share of real-world tooling still uses 1.1 under the hood. The safest practice remains quoting any string value that could be mistaken for a boolean.

The Norway Problem is one reason YAML has earned a reputation for surprising developers at scale. Its implicit type system — where 1.0 becomes a float, 0x1F becomes an integer, and 2024-01-01 becomes a date object — makes YAML expressive for humans but treacherous for machines. Understanding the version your parser implements is not optional knowledge; it is the baseline for writing portable configs. The formatter here targets YAML 1.2 semantics, which aligns with Kubernetes, Go's yaml.v3, and Rust's serde-yaml.

YAML security vulnerabilities — why safe parsing matters

YAML's most dangerous feature is rarely mentioned in tutorials: arbitrary code execution during parsing. PyYAML, the dominant Python YAML library, supports custom type constructors via the !! tag syntax. A YAML document containing !!python/object/apply:os.system ["rm -rf /"] will execute that shell command the moment it is parsed with yaml.load() — no user interaction, no confirmation. Loading untrusted YAML with the default loader is functionally equivalent to eval(). The fix is always to use yaml.safe_load(), which disables custom constructors entirely and restricts parsing to standard YAML types. PyYAML has emitted deprecation warnings about this for years, and Python 3.9+ requires an explicit Loader argument to make the choice deliberate — but legacy code using bare yaml.load() is still widespread.

The same class of vulnerability appeared in Ruby's YAML (Psych) and triggered one of the most significant Rails security incidents on record. In January 2013, researcher Charlie Somerville disclosed a YAML deserialization vulnerability in Rails that allowed remote code execution by sending a crafted YAML payload as a request parameter. The Rails mass-assignment vulnerability that made headlines at the time was only part of the story; the YAML deserialisation RCE was the more severe finding. SnakeYAML, the widely-used Java YAML library, has been the source of multiple high-profile CVEs — including CVE-2022-1471, which affected Spring Boot, and was exploited in the wild because applications accepted YAML from user input and passed it directly to the parser. The pattern is consistent: YAML parsers that support type constructors are deserialization gadgets waiting to be triggered.

The practical rules are simple. Never call a YAML parser's unsafe loader on content from any external source — user input, API responses, files uploaded by users, or config pulled from untrusted repositories. Always use the safe loading API (yaml.safe_load() in Python, Psych.safe_load in Ruby, restrict SnakeYAML to SafeConstructor in Java). In a browser environment — which is how this formatter works — the JavaScript YAML parser used here has no concept of host-language object construction, so these attacks do not apply. But any server-side pipeline that processes YAML from external sources should treat that YAML as untrusted input and enforce safe parsing at the library level.

YAML vs JSON vs TOML — choosing the right format

YAML's strengths are real: it supports inline comments (# this is a comment — the only widely-used serialisation format that does), multiline strings with the literal block (|) and folded block (>) styles, anchors and aliases for DRY configurations, and a syntax that reads naturally for nested structures. These properties make it the dominant format in the cloud and container world — Kubernetes, GitHub Actions, GitLab CI, CircleCI, Ansible, and Docker Compose all use YAML as their primary configuration language. The format was designed for humans, and for large configs it lives up to that design.

YAML's weaknesses are equally real. Significant whitespace means an invisible extra space or a tab character changes the parse tree silently. Tabs are forbidden entirely — the spec explicitly prohibits them in indentation, but most editors do not distinguish between a tab and spaces visually. The full YAML specification has 63 context-sensitive grammar rules, making it one of the most complex formats to implement correctly; different parsers produce different results on edge cases. The implicit type system (the Norway Problem, date parsing, octal integer literals) adds another layer of surprise. These weaknesses are why tools like Kustomize, Helm, and CUE exist — they provide abstraction layers over raw Kubernetes YAML precisely because raw YAML at scale becomes a maintenance problem.

JSON is simpler by design: no significant whitespace, no implicit types, a six-token grammar that fits on a page, and universal parser support. Its main limitation is the absence of comments and the verbosity of quoting every key. TOML (Tom's Obvious Minimal Language) targets the configuration file use case directly: explicit types, no indentation-sensitivity, no significant whitespace, and a syntax that is closer to traditional INI files. Rust's Cargo.toml, Python's pyproject.toml, and Hugo's config files use TOML because it is harder to get wrong than YAML and more expressive than JSON for config. The right choice depends on context: YAML for DevOps tooling that already expects it; JSON for APIs and data interchange; TOML for application configuration files where comment support and explicit types matter more than ecosystem momentum.

YAML's advanced features — anchors, multiline strings, and multi-document files

Anchors and aliases are YAML's built-in mechanism for avoiding repetition. An anchor is defined with &name on any node, and an alias reuses that node's value with *name anywhere else in the document. A common pattern in docker-compose.yml is defining a shared environment block once with an anchor and referencing it across multiple service definitions — instead of copy-pasting the same ten environment variables into every service. The merge key (<<: *alias) extends this further: it merges all key-value pairs from the aliased map into the current map, allowing a base service definition to be extended with per-service overrides. This is the closest YAML comes to inheritance, and it is widely used in multi-environment configurations.

Multiline strings in YAML come in two styles that serve different purposes. The literal block style (|) preserves newlines exactly as written — every line break in the source becomes a line break in the parsed string. This is the right choice for embedding shell scripts, SQL queries, or any text where line breaks are semantically significant. The folded block style (>) collapses newlines to spaces (treating the block like a paragraph), while preserving blank lines as paragraph breaks. This suits long prose values — documentation strings, descriptions, error messages — where you want to hard-wrap in the source for readability but deliver a single unbroken string to the consumer. Both styles support a chomping indicator: |- strips the final newline, |+ keeps all trailing newlines, and bare | keeps exactly one.

Multi-document YAML allows multiple independent YAML documents to coexist in a single file, separated by the --- document start marker. The optional ... document end marker closes a document explicitly. Kubernetes makes heavy use of this pattern — a single manifest.yaml file can contain a Deployment, a Service, and a ConfigMap, each separated by ---, applied together with a single kubectl apply -f manifest.yaml. The --- separator also serves as a version boundary in streaming YAML contexts, where a producer may emit an indefinite sequence of documents over a connection and the consumer processes each as it arrives. This formatter supports multi-document files: each document is parsed independently, errors are reported per-document, and the JSON conversion wraps all documents in a top-level array.