Choose the configuration format supported by the receiving application. JSON has a smaller syntax and no standard comments. YAML supports comments and more data features, but indentation and scalar resolution need care. Validate the parsed values, not only the appearance of the file.
The shared subset has limits
YAML 1.2 is designed for JSON compatibility. YAML also supports features outside JSON's data model, such as tags, aliases, and more general mapping keys. Conversion can lose these features or their meaning.
Parser versions and schemas affect scalar interpretation. A value that looks like a string can become another type. JSON parsers can also differ in duplicate-key and numeric-precision behavior.
See the YAML 1.2.2 specification and RFC 8259. Check the parser used by the actual application.
Where JSON Wins
JSON is the right choice when machines are the primary audience and strictness matters.
JSON's strengths:
- Broad library support. JSON parsers exist for many languages. Check number precision and duplicate-key handling.
- Small syntax. Fewer syntax features make the format convenient to validate, but valid syntax can still contain wrong values.
- Data exchange. It is the default format for APIs and inter-system communication.
- Formatting flexibility. Whitespace between tokens does not define nesting. Whitespace inside a string remains part of its value.
JSON's weakness as a config format: no comments. The JSON spec has no comment syntax, so you cannot annotate a config file — a real limitation when humans maintain it. It is also noisier to hand-edit, with required quotes and commas.
Where YAML Wins
YAML is the right choice when humans edit the file regularly and readability matters.
YAML's strengths:
- Readability. Indentation-based structure is easy to scan; no brace-matching.
- Comments. YAML supports
#comments — essential for explaining config to the next person. - Less punctuation. No quotes around most strings, no commas, no braces.
- Multi-line strings. Cleaner handling of long text values than JSON.
YAML's weakness: whitespace sensitivity. Indentation is the structure, and YAML forbids tab characters for indentation entirely. An editor that inserts a tab, or an inconsistent indent width, produces an invalid file that often looks fine. YAML can be broken in subtle ways JSON cannot.
The Decision Table
| Question | Use JSON | Use YAML |
|---|---|---|
| Is it an API payload or data exchange? | Yes | — |
| Is it a config file humans edit often? | — | Yes |
| Do you need comments in the file? | — | Yes |
| Does a machine generate and consume it? | Yes | — |
| Does the receiver require JSON? | Yes | — |
| Is readability the priority? | — | Yes |
A common real-world pattern: JSON for data, YAML for config. APIs speak JSON; the CI/CD pipeline, the container setup, and the app's settings file are YAML so humans can read and comment them.
Check indentation and scalar types
YAML uses indentation for block structure and does not permit tabs for that indentation. A different indent can change the structure or cause an error. Consistent editor settings help, but they do not validate the intended values.
Use the YAML Validator for an initial syntax check. Then inspect values that resemble booleans, dates, numbers, or nulls. Quote values that must remain strings according to the destination's rules.
A YAML-to-JSON round trip can remove comments and YAML-specific features. Do not use it as an automatic repair on your only source copy. The config conversion review checklist explains a safer comparison process.
Tools Used in This Guide
- YAML Validator — Validate YAML syntax and catch indentation errors
- JSON to YAML Converter — Convert between JSON and YAML
- JSON Formatter — Validate and pretty-print JSON
- JSON to XML Converter — Convert JSON data into XML
Frequently asked questions
Should I convert every configuration file to YAML?
No. Use the format and schema supported by the application. Human readability does not compensate for an unsupported input format.
Can YAML represent more than JSON?
Yes. YAML includes features such as tags, aliases, and broader mapping keys. They need a conversion policy when the target is JSON.
Is valid JSON always interpreted identically?
Do not assume it. Duplicate keys and large numbers can expose parser differences. Use the destination's validation rules.
Does standard JSON allow comments?
No. Some related formats add comments, but that does not make them valid standard JSON.
Does YAML syntax validation prove correct configuration?
No. A valid file can contain the wrong types or keys. Validate the application's schema and behavior too.
Can conversion remove comments?
Yes. JSON has no standard comment field. Keep the original annotated file when converting YAML.
Next Steps
- Read the YAML validator guide for a full walkthrough
- Validate your config with the YAML Validator
- Convert formats with the JSON to YAML Converter
- Read the JSON conversion cheat sheet for more format choices
