YAML vs JSON vs TOML: Configs and Front Matter Compared
November 11, 2026 · 12 min read
YAML vs JSON vs TOML: Which Format to Use for Configs and Front Matter
The YAML vs JSON decision mostly comes down to who edits the file. JSON is strict and comment-free, which suits data that programs exchange. YAML uses indentation and allows comments, which suits config that people edit by hand. TOML sits between them with explicit types. For Markdown front matter, your site generator usually decides.
YAML vs JSON vs TOML at a Glance
The fastest way to compare the three is to write the same data in each. Here's a small site config with a string, a number, a boolean, a list and one nested section.
# Site settings
title: Field Notes
port: 8080
debug: false
tags:
- markdown
- docs
database:
host: localhost
user: admin
YAML marks structure with indentation and dashes. Most strings don't need quotes, and the # line is a comment that parsers ignore. Our YAML format cheat sheet lists the core constructs and what each one parses as.
{
"title": "Field Notes",
"port": 8080,
"debug": false,
"tags": ["markdown", "docs"],
"database": {
"host": "localhost",
"user": "admin"
}
}
The JSON version holds identical data, but every key and string sits in double quotes and braces mark each level. The comment is gone, because JSON has nowhere to put it.
# Site settings
title = "Field Notes"
port = 8080
debug = false
tags = ["markdown", "docs"]
[database]
host = "localhost"
user = "admin"
TOML reads like an INI file with real types. The nested section becomes a [database] table header instead of an indented block. Here's how the three formats stack up on the details that cause real bugs.
| Trait | YAML | JSON | TOML |
|---|---|---|---|
| Structure | Indentation (spaces only) | Braces and brackets | key = value plus [table] headers |
| Comments | # | None | # |
| String quotes | Usually optional | Always double quotes | Always required |
| Null | null, ~ or an empty value | null | No null at all |
| Dates | Depends on the parser | None (use strings) | Native dates and date-times |
| Reuse | Anchors and aliases | None | None |
| Python standard library | None (PyYAML is third-party) | json | tomllib (read-only, 3.11+) |
| Built into JavaScript | None (needs a package) | JSON.parse | None (needs a package) |
| Typical files | CI workflows, compose.yaml, Kubernetes manifests | package.json, API payloads | Cargo.toml, pyproject.toml, hugo.toml |
Read the JSON vs YAML columns together and the pattern is clear. JSON trades readability for zero ambiguity, and YAML trades the other way.
How Do YAML and JSON Differ in Syntax and Comments?
JSON's grammar is tiny. RFC 8259 defines objects, arrays, numbers, strings, true, false and null. Strings use double quotes, trailing commas are invalid, and there's no comment syntax. A JSON text can be any single value, so a bare 42 is a valid document.
For hand-edited config, that missing comment syntax is JSON's biggest drawback. Some tools work around it with variants. VS Code, for example, reads its own settings.json in a JSON with Comments mode that accepts // and /* */. That's the tool being lenient, not JSON changing, so a strict parser still rejects the file.
YAML goes the other way. Nesting comes from indentation, and the spec forbids tab characters there, so you indent with spaces. A # starts a comment, and block scalars let long text span several lines. Our Markdown front matter guide covers the quoting rules that trip people up inside a --- block.
The two formats also overlap. The YAML 1.2.2 spec says version 1.2's primary focus was making YAML a strict superset of JSON. In practice, a 1.2 parser reads ordinary JSON unchanged, which is handy when a tool wants YAML and you already have JSON.
Implicit Typing: Why YAML Turns NO into false
Unquoted YAML values get their type from how they look, and that's where YAML bites. YAML 1.1 treats yes, no, on, off, y and n (in several capitalisations) as booleans. Some widely used parsers still follow 1.1, including PyYAML, which its own site describes as a YAML 1.1 parser.
country: NO
answer: yes
version: 1.10
zip: 02134
We ran this through PyYAML 6.0.3 with yaml.safe_load. The country code for Norway came back as False, answer became True, and version became the float 1.1. The leading zero also broke zip: PyYAML read it as octal and returned 1116.
YAML 1.2 narrowed the rules. Its core schema only treats true and false (with initial or full capitals) as booleans, so NO stays a string. The other two still convert, though. 1.10 is still a float, and a 1.2 parser turns 02134 into the integer 2134. The fix works everywhere: quote anything that must stay text.
country: "NO"
version: "1.10"
zip: "02134"
JSON can't hit this problem, because every string is quoted. TOML can't either. A bare country = NO is a parse error in TOML, not a silent false, which is the behaviour you want. TOML also has native dates, so published = 2026-11-11 is a real date rather than a guess.
Is TOML Better Than YAML?
For flat or lightly nested config that people edit by hand, usually yes. The TOML vs YAML trade-off is explicitness against compactness. TOML ignores indentation, requires quoted strings and has no implicit booleans. Rust's Cargo.toml, Python's pyproject.toml and Hugo's hugo.toml all use it.
TOML's weak spot is depth. Nested sections usually get their own dotted table header, and lists of objects use double brackets.
[[servers]]
name = "alpha"
ip = "10.0.0.1"
[[servers]]
name = "beta"
ip = "10.0.0.2"
[servers.limits]
max_body = "10MB"
Each [[servers]] header starts a new object in the servers array, and [servers.limits] attaches a table to the most recent one. That's precise but easy to misread once a file goes four levels deep. YAML handles the same shape with plain indentation, and deeply nested files such as Kubernetes manifests and CI pipelines use it.
TOML also has no null value. You leave a key out instead, so a field that must be explicitly empty doesn't map cleanly. The TOML v1.1.0 spec is short enough to read in one sitting, which can't be said of YAML.
Our take on YAML vs TOML: we prefer TOML for app config that people edit by hand, and we use YAML only where a tool requires it. Fewer rules means fewer surprises when someone else edits the file.
Front Matter in YAML, TOML or JSON: Which Generators Accept Which
In a Markdown file, the format question is mostly settled by your static site generator. Hugo picks the format from the delimiter. Here's the same metadata in the three formats Hugo accepts in Markdown files.
---
title: Field Notes
date: 2026-11-11
draft: false
---
+++
title = "Field Notes"
date = 2026-11-11
draft = false
+++
{
"title": "Field Notes",
"date": "2026-11-11",
"draft": false
}
The first block is YAML between triple dashes, the second is TOML between +++ lines, and the third is a bare JSON object. The Hugo front matter docs also note that TOML accepts unquoted date and time values. Other generators are pickier.
| Generator | YAML | TOML | JSON | Notes |
|---|---|---|---|---|
| Hugo | Yes, --- | Yes, +++ | Yes, braces | Detects the format from the delimiters |
| Jekyll | Yes | No | Not documented | Front matter must be YAML |
| Eleventy | Yes (default) | Via a custom parser | Yes, ---json | Also supports ---js front matter |
| Astro | Yes | Yes | Not documented | Its Markdown guide lists YAML or TOML |
| Docusaurus | Yes | Via a custom parser | Via a custom parser | Parsed as YAML unless you supply parseFrontMatter |
| MkDocs | Yes | Not documented | Not documented | Also reads MultiMarkdown-style meta-data |
For MkDocs, the site config lives in mkdocs.yml, and our MkDocs Markdown guide walks through it. Obsidian stores note properties as YAML too, so YAML is the safe default when one file has to work in several tools.
If you'd rather not hand-write the block, the front matter generator builds it in YAML, TOML or JSON. It has presets for Hugo, Jekyll, Astro, Docusaurus, Eleventy and Next.js MDX, and it can parse a block you already have. It works on front matter only, not on general config files.
One limitation to know: our editor's preview doesn't render front matter, so check it in your generator's build.
Anchors, Aliases and Safe Loading in YAML
YAML can reuse data inside one file, which JSON and TOML can't. You mark a node with an anchor (&name) and repeat it with an alias (*name).
shared_tags: &tags
- markdown
- docs
blog:
tags: *tags
wiki:
tags: *tags
A parser expands both aliases, so blog.tags and wiki.tags each hold the two-item list. Many files also use the merge key, written <<: *defaults, to copy one mapping's keys into another. That key is defined as a YAML 1.1 type and isn't part of the 1.2 core schema, so check that your parser supports it before relying on it.
That extra power has a cost. PyYAML's documentation warns that yaml.load can construct arbitrary Python objects and isn't safe with untrusted input. Use yaml.safe_load for any file you didn't write. A JSON parser only ever returns plain data, and TOML parsers behave the same way.
The bigger limitation is size. The YAML spec is long, and real parsers disagree on edge cases, especially between 1.1 and 1.2 behaviour. If you need the same file read the same way in Python, Go and JavaScript, JSON is the safer pick.
Is There a YAML Schema? Validating All Three Formats
Yes, but probably not the kind you mean. In the YAML spec, a schema is a set of tags plus rules for resolving untagged values. The spec defines three: failsafe, JSON and core. They decide whether true is a boolean, not whether your config has a port key.
For validation, JSON Schema has become the shared answer for all three formats. SchemaStore describes itself as a catalog of JSON, YAML and TOML schemas, and many editors load it automatically. The Red Hat YAML language server validates YAML against JSON Schema. A comment at the top of a file can point it at one.
# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
name: CI
on: push
With that line in place, an editor running the language server flags unknown keys and wrong types as you type. Load the same file with PyYAML, though, and the on key itself becomes the boolean True, one more YAML 1.1 surprise. On the JSON side, VS Code's built-in support already offers IntelliSense for common files such as package.json.
Which Format Should You Pick for Your Project?
Most of the time, the tool settles YAML vs JSON for you. When it doesn't, match the format to who writes the file.
- Machine-written data and API payloads: JSON. Nearly every language has a mature parser, and there's no ambiguity.
- Files a tool dictates: follow the tool. GitHub Actions workflows and
compose.yamlare YAML,Cargo.tomlandpyproject.tomlare TOML, andpackage.jsonis JSON. - Config people edit by hand: TOML for flat settings, YAML when nesting runs deep.
- Markdown front matter: whatever your generator defaults to, which is usually YAML.
Need to show JSON data inside a Markdown document rather than configure something? Our guide to turning JSON into Markdown tables covers that. Moving an existing file from one format to another is its own task, with its own type pitfalls. Our guide to converting YAML to JSON and back walks through them.
The YAML vs JSON choice gets easier once you stop treating it as a matter of taste. Use JSON for data that programs exchange, TOML for flat config that people edit, and YAML where nesting runs deep or a tool insists. For front matter, start from your generator's default and build the block with the front matter generator, then write the body in the editor.