The same data, two formats
JSON and YAML represent identical data. Here is the same config object in both formats:
JSON
{
"name": "my-app",
"version": "1.0.0",
"port": 3000,
"debug": false,
"tags": ["web", "api"],
"database": {
"host": "localhost",
"port": 5432
}
}YAML
name: my-app version: 1.0.0 port: 3000 debug: false tags: - web - api database: host: localhost port: 5432
YAML is visually lighter: no quotes on keys, no braces, no commas. JSON is more explicit: every string is quoted, every structure is delimited.
Feature comparison
| Aspect | JSON | YAML |
|---|---|---|
| Comments | Not supported | # Supported |
| Strings | Always quoted | Quotes optional |
| Indentation | Braces and brackets | Significant whitespace |
| Multi-line strings | Escape sequences (\n) | Block scalars (| or >) |
| Trailing commas | Not allowed | N/A |
| File size | Larger (more punctuation) | Smaller (cleaner syntax) |
| Parsing speed | Faster | Slower |
| Browser support | Native (JSON.parse) | Requires a library |
When to use each
Use JSON when
- ‣APIs and HTTP responses: JSON is the universal language of REST APIs.
- ‣Browser environments: JSON.parse and JSON.stringify are built into every browser.
- ‣Data interchange between services: less ambiguity, more predictable parsing.
- ‣When the consumer is a machine, not a human.
Use YAML when
- ‣Config files: Docker Compose, Kubernetes manifests, GitHub Actions, Ansible.
- ‣When humans write and maintain the file directly.
- ‣When you need comments to explain values.
- ‣When readability matters more than parsing speed.
YAML pitfalls to know
YAML's flexibility comes at a cost. These are the mistakes that catch developers off guard:
The Norway problem
In many YAML parsers, the bare value NO is interpreted as a boolean false. So a country code list with NO (Norway) silently becomes false. Always quote values that could be misread as booleans: "NO", "yes", "on", "off", "true", "false".
Indentation errors
YAML uses indentation to define structure. Tabs are not allowed: only spaces. A single extra or missing space can silently change the meaning of a document or cause a parse error.
Implicit type coercion
3.0 is parsed as a float, 3 as an integer, and "3" as a string. This can cause type mismatches when a string "3" is expected but a number 3 is received. Use explicit quotes when the type matters.
JSON is valid YAML
YAML is a superset of JSON. Any valid JSON document is also valid YAML. This means you can gradually add YAML features (like comments) to a JSON file without breaking YAML parsers.
Frequently asked questions
Can I convert between JSON and YAML without data loss?
Almost always yes, with one exception: YAML supports comments and JSON does not. When converting YAML to JSON, all comments are lost. Converting JSON to YAML is lossless. Our YAML to JSON Converter handles the conversion instantly in your browser.
Why does Kubernetes use YAML instead of JSON?
Kubernetes manifests are written and maintained by humans, often with many fields. YAML is more readable, supports comments for documentation, and is less cluttered without braces and quotes everywhere. JSON would be valid too (Kubernetes accepts both) but YAML won the convention battle.
Is YAML faster to parse than JSON?
No. JSON is significantly faster to parse. YAML's flexible syntax (implicit types, multiple string styles, anchors) requires a more complex parser. For high-throughput data pipelines or APIs, JSON is the better choice.
What is a YAML anchor?
Anchors (&) and aliases (*) let you define a value once and reuse it elsewhere in the document. For example: defaults: &defaults timeout: 30 then later production: <<: *defaults timeout: 60. This reduces repetition in complex config files. JSON has no equivalent feature.
Should I use .yml or .yaml as the file extension?
Both are valid and widely accepted. The official YAML specification recommends .yaml. In practice, .yml is common because early tools and platforms preferred shorter extensions. Most tools accept either. Pick one and stay consistent across your project.