Intro
YAML and JSON both represent structured data such as settings, lists, and objects. They overlap enough that the same information can often be written in either format, but they make different trade-offs.
YAML tends to favour human-edited configuration. JSON favours a small, predictable interchange format that almost every programming environment can read. The right choice depends on who edits the file and where it travels.
What YAML and JSON have in common
Both formats can represent mappings, sequences, strings, numbers, booleans, and null values. YAML 1.2 was designed to be compatible with JSON as a subset, so many simple JSON documents can also be read as YAML.
Where YAML is useful
- Indentation and uncluttered syntax can make configuration easier for people to edit.
- Comments are useful when a file needs to explain a setting.
- Anchors and tags can express structures that go beyond the portable JSON data model.
- Indentation is significant, so inconsistent spaces can change the structure or cause a parse error.
Where JSON is useful
JSON has a deliberately small grammar and is a common choice for APIs, browser data, and machine-generated files. Its strict quoting and punctuation can be noisy by hand, but that strictness makes it predictable across languages.
Tip: Convert a copy with the YAML ↔ JSON tool, then inspect the result. A converter can change syntax, but it cannot know whether a value was intended to be a string, number, date, or application-specific setting.
Conversion is not always lossless
YAML supports features and typing rules that do not have direct JSON equivalents. Comments, anchors, tags, and some implicit values may disappear or change meaning during conversion. For configuration files, validate the converted output in the application that will read it.
Where conversion loses meaning
YAML can carry comments, anchors, aliases, tags, multiple scalar styles, and implicit typing rules that do not have direct JSON equivalents. Converting YAML to JSON commonly drops comments and turns dates or other tagged values into strings or generic values. Converting JSON to YAML can improve readability but does not make an ambiguous schema correct.
Indentation is syntax in YAML, so tabs, inconsistent nesting, and a misplaced colon can change or invalidate the structure. Quoting matters because values such as yes, no, numbers with leading zeroes, or date-like strings may be interpreted differently across YAML versions and parsers. JSON is more repetitive but has a deliberately smaller data model and stricter interoperability expectations.
Choose by boundary and ownership
Use YAML when humans maintain configuration and the selected parser, schema, and review process are controlled. Use JSON when a service boundary needs predictable generation, broad tooling, or a format with fewer presentation choices. Neither format automatically provides schema validation, secrets management, safe execution, or compatibility between application versions.
Before converting, record the parser/version, expected types, null and empty-value rules, duplicate-key policy, and whether comments are part of the documentation. Format the result, validate it with the target application, and compare a representative nested, empty, quoted, and Unicode example. The YAML ↔ JSON tool is useful for inspection, but production configuration still needs a review and a deployment test.
A side-by-side example
The same simple data might look like this in YAML:
name: Ada
roles:
- admin
- reviewer
and like this in JSON:
{"name":"Ada","roles":["admin","reviewer"]}
YAML is visually lighter, but indentation and scalar rules become part of the syntax. JSON uses more punctuation, but its allowed values and interchange rules are easier for many generators and validators to agree on. Neither example says whether roles is exhaustive, whether order matters, or whether name may be null; those belong in a schema or application contract.
Parser and security considerations
Pin the YAML version and parser where configuration matters. Review aliases, anchors, custom tags, duplicate keys, and implicit typing; do not enable unsafe object construction for untrusted YAML. A parser that turns a date-like scalar or a tagged value into a native object can produce a different result from a JSON conversion that treats it as text.
For configuration, validate after parsing and fail closed when required values are missing. For an API, use a documented JSON schema or equivalent contract, set the content type, and reject unexpected shapes. Formatting or conversion makes differences visible, but it does not validate permissions, secrets, or business rules.
Practical takeaway
Choose the format at the boundary where its trade-offs matter: YAML for controlled human-edited configuration, JSON for predictable interchange. Pin parser expectations, validate types and duplicates, and test conversion with comments, quotes, empty values, and nesting. Readability alone is not compatibility.
FAQ
Is JSON valid YAML?
Most JSON documents are valid YAML 1.2 input because YAML 1.2 includes JSON as a subset, although the behaviour of a particular parser still depends on its supported YAML version and schema.
Should I use YAML for an API?
JSON is usually the safer default for a public API because support is widespread and its data model is intentionally small. YAML can be appropriate when humans are the primary editors or when the API explicitly supports it.
Does converting YAML to JSON preserve comments?
No. JSON has no comment syntax, so comments normally cannot survive a YAML-to-JSON conversion.