YAML vs JSON: which format to use on your site, and when to convert
Front matter is YAML, structured data is JSON, and the bugs live where one turns into the other.
By ClaudeGPT Si Newsroom, Editorial team··3 min read
YAML vs JSON comes down to who reads the file: YAML is easier for people to write and comment, JSON is stricter and is what most programs and APIs expect. On a website you usually need both, YAML in the front matter of your pages and JSON in the structured data, and a converter like AyeTab's free YAML and JSON tool moves data between them without uploading it.
The short comparison
| YAML | JSON | |
|---|---|---|
| Structure | Indentation and dashes | Braces, brackets and commas |
| Comments | Yes, with # |
None in the grammar |
| Strings | Quotes often optional | Always double-quoted |
| Typical home | Config files, front matter, CI pipelines | APIs, JSON-LD, app settings read by code |
| Main risk | Whitespace and type guessing | Missing or trailing commas |
The two are closer than they look. The YAML 1.2 revision set out to make YAML a strict superset of JSON, which in practice means a modern YAML parser can read most JSON as it is. Going the other way always needs a conversion.
Where an SEO team meets each format
YAML in the content layer. Static site generators keep page metadata at the top of each file. Jekyll, for example, requires its front matter to be valid YAML between two lines of three dashes. Titles, descriptions, canonical paths and noindex flags often live there.
JSON in the markup. Google recommends JSON-LD for structured data, and JSON-LD is JSON. Article, Product, FAQPage and Organization blocks all end up as a JSON object in a script tag.
So the same facts, a page title or a publish date, often exist once in YAML and once in JSON. When a template builds the JSON-LD from front matter, a YAML quirk can leak straight into your schema.
Where YAML trips up structured data
Three things to check when a schema block built from YAML looks wrong:
- Booleans from plain words. Parsers following YAML 1.1 read
yes,no,onandoffas true or false. A field meant to say "No" becomesfalsein the JSON. - Dates turned into objects. Some YAML libraries read an unquoted date as a date type, and the template then prints it in a format you did not choose. Quote dates you want kept as text.
- Lost comments. Notes left in the YAML do not survive the trip to JSON, so do not rely on them for anything a crawler or a teammate reading the output needs.
A fast way to debug is to paste the front matter into a converter and read the JSON it produces. Braces make the real nesting and value types obvious, and you can compare that against the JSON-LD your page prints.
Which one to pick
Pick YAML for anything people edit often and want to annotate: site config, page front matter, redirect lists kept in a repo. Pick JSON for anything a machine consumes directly: structured data, API payloads, files a build step reads with a JSON parser. If a file must be both easy to edit and strict, keep YAML as the source and generate JSON in the build.
JSON is still the better source format when non-developers edit through a form or CMS that validates input, because there is no whitespace to get wrong.
Converting without sending client files away
Client config and unpublished page data are not things to paste into a random web form. AyeTab parses YAML and JSON locally in the browser, needs no account, is free to use, and keeps working offline once loaded. It is also part of a free Chrome extension that puts the same developer tools on your new tab.
FAQ
Is YAML better than JSON? Neither is better overall. YAML suits files people write and comment; JSON suits data that programs exchange.
Can JSON-LD be written in YAML? The markup on the page has to be JSON. You can store the data in YAML and convert it to JSON when the page is built.
Can a YAML parser read JSON? Usually yes. YAML 1.2 was designed as a superset of JSON.