JSON vs YAML is not a taste argument about curly braces. JSON is a single, strict grammar that JSON.parse implements in every browser. YAML is a family of documents: comments, anchors, aliases, tags, merge keys, block scalars, and multi-document streams. Many “YAML files” in the wild are JSON. Many others are not.
If you treat them as the same format, you will paste an anchor into a JSON parser and call the parser broken. Or you will paste JSON into a YAML tool and assume every YAML feature round-trips. Neither is true.
A JSON value is an object, array, string, number, boolean, or null. Keys and strings use double quotes. Comments are illegal. Trailing commas are illegal. There is one document per parse. After a successful parse, two implementations that follow the same rules agree on types.
That is why APIs, browser tools, and wp_json_encode consumers default to JSON. The JSON Validator answers whether the string parsed. The JSON Formatter only rewrites whitespace after that parse. Those jobs do not exist in the same shape for “any YAML file.”
YAML is nicer to type for configuration: you can write comments, drop most quotes, and indent maps and lists. The cost is that two YAML parsers can disagree, and a file that looks obvious can include features you did not notice: an alias that copies a node, a tag that changes a type, a <<: merge, or a second document after ---.
JSON to YAML is easy when the input is JSON: emit block maps and lists. YAML to JSON is only safe for JSON itself and a documented block subset. Anchors, tags, merge keys, tabs, | / > scalars, and --- streams should be rejected, not ignored. The JSON to YAML Converter on this site follows that rule.
Comments are the feature people want from YAML. They are also the first thing a JSON parser rejects. If your team needs comments in a file that must also be JSON, you do not have one format. You have JSONC in the editor and a strip step before parse — or you keep YAML and accept a narrower runtime.
Anchors and aliases are not comments. They are graph structure. A converter that turned foo: &x 1 into the string "&x 1" would be lying. Rejection is the honest failure.
On YAML input, yes / no / on / off are often booleans. JSON to YAML should emit true / false / null. That is a type decision, not decoration.
Use JSON when machines write and read the file and you need one parse. Use YAML when humans edit configuration and you have agreed which subset is legal. Do not store application data that must round-trip through a browser as “whatever YAML the editor saved.”
If you already have JSON, converting to block YAML is presentation. If you already have YAML that depends on merge keys, stay in a real YAML processor. This article will not make that file into JSON without losing meaning. If the consumer is a spreadsheet, that is a different comparison: JSON vs CSV.
JSON vs YAML is a trade of strictness for editability. JSON wins when the document is data. YAML wins when the document is annotated config and the unsupported features are named. A converter that lists what it refuses is more useful than one that silently drops an anchor and calls the result equivalent.
Indent in YAML is part of the document. A tab is not a space. A converter that accepts tabs will disagree with one that does not. JSON does not have that fight: insignificant whitespace is not structure. If your team cannot agree on YAML indent, the file is already costing more than the comments saved.
Round-trip JSON → YAML → JSON is the reliability target for objects, arrays, strings, numbers, booleans, and null. If that loop fails, prefer JSON for the stored artifact. Pretty YAML in git is not a reason to lose a type on the way back.
JSON is valid YAML 1.2. The reverse is not true. A YAML file with comments or anchors is not JSON.
If it documents a block subset, anchors, tags, merge keys, tabs, block scalars, and --- documents are errors. That is safer than ignoring them.
On many YAML inputs, yes. JSON has no yes token. A JSON-to-YAML emitter should write true and false.
Most public HTTP APIs should use JSON. YAML is a config and markup convenience, not a stricter interchange.
