YAML and JSON: two formats, one data model
YAML and JSON are both human-readable, text-based data serialization formats. They share the same underlying data model: strings, numbers, booleans, null, arrays, and objects. But they use very different syntax. Most valid JSON is also valid YAML 1.2, though the reverse is not true.
The formats evolved for different contexts:
- JSON was designed for network transmission. It's compact, unambiguous, and parseable by a 50-line parser. Every language has a JSON library. REST APIs, browser
localStorage, and configuration files all use JSON. - YAML was designed for human authoring. It supports comments, multi-line strings, anchors and aliases, and indentation-based nesting. These features make config files far more readable than equivalent JSON.
When to use each format
Use YAML for human-edited configuration files: CI/CD pipelines (GitHub Actions, GitLab CI), Kubernetes manifests, Docker Compose files, Ansible playbooks, and application config files (like Rails' database.yml or Webpack's config.js equivalent). Comments alone make YAML the right choice for configs that need documentation inline.
Use JSON for machine-to-machine data exchange: API responses, localStorage, IndexedDB, and inter-service communication. JSON is faster to parse, less ambiguous (no implicit type coercion, no yes/no for booleans), and has universal tooling support.
YAML's implicit type coercion traps
YAML 1.1 (the version most parsers implement) has some surprising behavior:
yes,no,on,off,true,falseall evaluate as booleans.1.0is a float, not a string.- Strings that look like hex (e.g.,
0xFF) are parsed as integers. - The string
"null"becomesnull, not the string"null".
This means YAML config values often need explicit quoting: status: "off" rather than status: off. The converter handles this automatically when producing YAML output: values that would be misinterpreted are always quoted.
How YAML anchors and aliases are handled
YAML supports anchors (&name) and aliases (*name) to avoid repetition. The converter does not support round-tripping these. When YAML with anchors is converted to JSON and back to YAML, the repeated values will be inlined rather than aliased. This is expected behavior: JSON has no equivalent concept, so the structure is preserved but the optimization is lost.
Multi-line strings in YAML
YAML supports two block scalar styles:
- Literal block (
|): Preserves newlines as-is. Good for embedded scripts or long prose. - Folded block (
>): Folds newlines to spaces, like paragraph text. Good for long single-line strings that you want to wrap for readability in the source file.
Both are converted to regular JSON strings. The | style produces a string with embedded \n characters; the > style produces a single space-separated string.
Practical tips
When generating YAML from JSON for a Kubernetes or Docker Compose config, review the output before committing it. Pay particular attention to boolean and numeric values that came in as JSON strings. The converter quotes strings that would otherwise be misinterpreted, but context-specific validators (like kubectl apply --dry-run) will catch any remaining type mismatches.
For large JSON API responses that you want to inspect in a more readable format, YAML output with proper indentation is often easier to read than indented JSON, because YAML omits all the double quotes and curly braces.