YAML, JSON & TOML Converter

The Complete YAML, JSON & TOML Guide

How YAML, JSON, and TOML differ, the indentation rules that trip people up, and how live conversion between all three works.

Open YAML ⇆ JSON ⇆ TOML Converter

YAML vs. JSON

YAML and JSON both describe the same underlying data model - nested maps, lists, and scalar values - but they look very different on the page. JSON uses explicit braces {}, brackets [], commas, and quoted keys, which makes it easy for machines to parse unambiguously and easy to embed in a single line. YAML instead relies on indentation and line breaks to express nesting, with far less punctuation, which many people find easier to read and hand-edit - at the cost of being more sensitive to whitespace mistakes.

AspectJSONYAML
NestingBraces / bracketsIndentation
KeysAlways double-quotedUsually unquoted
CommentsNot supportedSupported with #
Readability for humansGood, but verboseVery good
Typical useWeb APIs, JS dataConfig files, CI pipelines

Indentation Rules That Trip People Up

Because YAML uses whitespace to mean something, a few rules matter a lot more than they would in JSON:

  • Every sibling must line up exactly. If one key in a map is indented 2 spaces and the next sibling key is indented 3 or 4, the parser can no longer tell they belong to the same level - this is the single most common source of "inconsistent indentation" errors.
  • Tabs are not allowed. A tab's visual width isn't fixed across editors, so YAML disallows tabs for indentation entirely - use spaces, with 2 spaces per level being the most common convention.
  • List items align with their key. A list under a key is usually indented at least as much as the key that introduces it, and every item in that list must share the same indentation.

This converter's parser reads YAML by tracking the indentation width of each line to build the nested structure, and reports the specific line number where indentation stops lining up rather than guessing.

What About TOML?

TOML (Tom's Obvious, Minimal Language) takes a third approach: explicit [section] headers and plain key = value lines, designed specifically to be unambiguous to both read and parse - no indentation sensitivity like YAML, no bracket-nesting like JSON. It's the default config format for tools like Cargo (Rust), Poetry (Python), and Hugo.

AspectYAMLTOML
NestingIndentation[section.subsection] headers
Arrays of objectsIndented list of maps[[array_of_tables]] repeated headers
CommentsSupported with #Supported with #
Whitespace-sensitiveYesNo
Typical useConfig files, CI pipelinesRust/Python project manifests, app configs

Structurally, TOML's nested tables map onto the same "maps and lists" data model as YAML and JSON, so converting between all three is just a matter of routing through one shared in-memory representation - see Supported Syntax below for exactly which TOML features this converter handles.

Supported Syntax

Nested Maps & ListsDeeply nested key/value maps and block sequences, including lists of maps, all driven by indentation.
Scalar TypesPlain, single-quoted, and double-quoted strings, integers, floats, true/false, and null/~.
Inline Flow CollectionsCompact [a, b, c] and {a: 1, b: 2} YAML syntax is supported alongside full block style.
TOML Tables & ArraysBare/quoted keys, dotted keys, [table] and [[array of tables]] headers, quoted/literal strings, numbers with _ separators, and inline tables.
Out of ScopeYAML anchors/aliases and custom tags; TOML multi-line triple-quoted strings, dates/times, and hex/octal/binary numbers.

Common Use Cases

Container & CI ConfigsConvert a Docker Compose, Kubernetes, or GitHub Actions YAML file to JSON to validate or process it programmatically.
API PayloadsTurn a YAML config into the JSON body an API expects, or a JSON response into readable YAML for a config file.
Learning Either FormatSee the same data in both syntaxes side by side to build intuition for how YAML's indentation maps to JSON's braces.

Frequently Asked Questions

Why does TOML use repeated [[table]] headers instead of nested indentation for arrays of objects?

TOML is designed to avoid whitespace sensitivity entirely, so instead of relying on indentation level to imply nesting the way YAML does, an array of tables repeats the same [[section]] header once for every item in the array. It's more verbose than an indented list of maps, but it keeps every table's boundaries syntactically explicit in the text itself rather than implied by how far a line happens to be indented.

Why is there no direct YAML-to-TOML conversion code path?

All three formats route through the same parsed, JSON-like value internally - YAML and TOML are each parsed into that shared structure and then serialized back out into whichever format you need. A YAML-to-TOML conversion is really two hops (YAML to the shared structure, then the shared structure to TOML) rather than one dedicated algorithm, which keeps the converter down to three parsers and three serializers instead of needing a unique routine for every possible pair of formats.

Why do TOML's underscore-separated numbers like 1_000_000 need special handling?

TOML allows underscores as visual digit separators in integers and floats purely for readability, so 1_000_000 is easier to scan than 1000000. The underscores aren't part of the numeric value itself, though - a compliant parser has to strip them out before treating the digits as a number, and only permits them between digits, not at the start, end, or doubled up.

Why does YAML care so much about indentation?

YAML uses indentation instead of braces and brackets to represent nesting, so the number of leading spaces on a line is meaningful structure, not just formatting. Every sibling key or list item at the same level must use exactly the same indentation width, or the parser can no longer tell where one level ends and another begins.

Why can't I use tabs to indent YAML?

The YAML specification disallows tab characters for indentation because a tab's visual width isn't fixed - different editors and terminals render it differently, which would make indentation-based nesting ambiguous. Use spaces (2 per level is the common convention) instead.

Why does the converter point to a specific line number instead of just saying the syntax is invalid?

A precise, line-numbered error lets you jump straight to the actual problem in a large config file instead of manually scanning every line looking for a stray character or misplaced indent. The parser tracks its position as it reads through the text, so it can report exactly where parsing failed - an inconsistent YAML indentation level, a JSON syntax error, or the specific TOML value or table header that didn't parse - rather than a generic "invalid input" message.

Open YAML ⇆ JSON ⇆ TOML Converter