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.
| Aspect | JSON | YAML |
|---|---|---|
| Nesting | Braces / brackets | Indentation |
| Keys | Always double-quoted | Usually unquoted |
| Comments | Not supported | Supported with # |
| Readability for humans | Good, but verbose | Very good |
| Typical use | Web APIs, JS data | Config 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.
| Aspect | YAML | TOML |
|---|---|---|
| Nesting | Indentation | [section.subsection] headers |
| Arrays of objects | Indented list of maps | [[array_of_tables]] repeated headers |
| Comments | Supported with # | Supported with # |
| Whitespace-sensitive | Yes | No |
| Typical use | Config files, CI pipelines | Rust/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
[a, b, c] and {a: 1, b: 2} YAML syntax is supported alongside full block style.[table] and [[array of tables]] headers, quoted/literal strings, numbers with _ separators, and inline tables.Common Use Cases
Frequently Asked Questions
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.
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.
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.
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.
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.
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.