JSON vs YAML: Choosing the Right Format for Your Project

JSON and YAML are both formats for serializing structured data — objects, arrays, strings, numbers, and booleans — into a human-readable text representation. They overlap significantly in capability: YAML is a superset of JSON, meaning any valid JSON is also valid YAML. But their design priorities differ sharply, and that difference determines when each format is the right choice.

JSON: Designed for Machines

JSON (JavaScript Object Notation) was formalized by Douglas Crockford in the early 2000s as a simpler alternative to XML for data interchange. Its syntax is derived from JavaScript object literals and is intentionally minimal: curly braces for objects, square brackets for arrays, double quotes for strings, and no trailing commas or comments.

{
  "name": "justconvert",
  "version": "1.0.0",
  "features": ["encoding", "json", "image"],
  "active": true,
  "maxFileSize": null
}

JSON's strictness is a feature, not a limitation. Because the grammar has no ambiguity and no optional syntax, JSON parsers are simple, fast, and consistent across all languages. JSON.parse() in every JavaScript runtime produces identical results for identical input. This predictability makes JSON the correct choice for machine-to-machine communication.

YAML: Designed for Humans

YAML (YAML Ain't Markup Language) was designed to be easy for humans to write and read. It achieves this through indentation-based nesting (no braces), optional quotes for simple strings, and support for comments. The same data structure that takes 10 lines of JSON takes 7 lines of YAML and is easier to edit without accidentally misplacing a comma or bracket.

name: justconvert
version: 1.0.0
features:
  - encoding
  - json
  - image
active: true
maxFileSize: null

YAML also supports features JSON lacks: comments (# this is a comment), anchors for reusing values (&anchor / *alias), multi-line strings (block scalars with | and >), and custom tags for type hints. These features make YAML significantly more expressive for configuration files that humans maintain.

Syntax Comparison Side by Side

• Objects: JSON uses {} with quoted keys; YAML uses indented key: value pairs
• Arrays: JSON uses []; YAML uses - prefix per item
• Strings: JSON requires double quotes; YAML quotes are optional for simple values
• Comments: JSON has none; YAML uses # to end-of-line
• Booleans: JSON uses true/false lowercase; YAML accepts true, True, TRUE, yes, on (in YAML 1.1)
• Null: JSON uses null; YAML accepts null, ~, or empty value
• Multiline strings: JSON requires \n escape sequences; YAML uses literal block (|) or folded (>)

The Norway Problem and Other YAML Pitfalls

YAML's flexibility comes with footguns. The most famous is the Norway Problem: in YAML 1.1, the unquoted string no is parsed as the boolean false. This means a list of country codes that includes NO (Norway's ISO 3166-1 alpha-2 code) silently becomes false. YAML 1.2 fixed this by restricting booleans to lowercase true and false only, but many parsers still use YAML 1.1.

Other YAML pitfalls include: strings that look like numbers (version: 1.10 may parse as the float 1.1), strings containing colons or hashes that must be quoted (url: http://example.com breaks parsing), and the off/on values being treated as booleans. When using YAML for configuration, always quote strings that could be ambiguous.

When to Use JSON

• API responses and request bodies — JSON is the universal API format, natively supported by every HTTP client and server framework
• Data stored in databases — MongoDB, Elasticsearch, DynamoDB, and PostgreSQL's jsonb column all natively store and query JSON
• Configuration parsed by programs — when a machine reads the config, JSON's strict parsing rules eliminate ambiguity
• Browser-native serialization — window.localStorage and IndexedDB store strings; JSON.stringify/parse is the standard serialization layer
• Logs and event streams — line-delimited JSON (NDJSON) is the standard format for structured logs in ELK stack, Datadog, and cloud logging services

When to Use YAML

• CI/CD pipeline configuration — GitHub Actions (.github/workflows/*.yml), GitLab CI (.gitlab-ci.yml), and CircleCI all use YAML because humans write and maintain these files
• Kubernetes manifests — all Kubernetes resources are defined in YAML, chosen for readability and the ability to add descriptive comments
• Docker Compose files — docker-compose.yml defines multi-container applications; YAML's anchor feature allows reusing common service configuration blocks
• Application configuration — Ansible playbooks, Helm charts, and Spring Boot's application.yml all use YAML for human-edited application settings
• Infrastructure as Code — Serverless Framework and AWS SAM both use YAML for function and resource definitions

Converting Between JSON and YAML

Converting JSON to YAML is lossless — every JSON value has a direct YAML equivalent. Converting YAML to JSON loses YAML-specific features: comments are stripped, anchors are expanded to duplicate values, and multi-line strings are collapsed. If your YAML uses anchors for DRY configuration, the JSON equivalent will have repeated identical blocks.

A practical workflow: keep source configuration in YAML (for human editing) and convert to JSON for deployment tooling that requires it. This gives you the readability and commenting benefits of YAML while maintaining JSON compatibility for downstream consumers.

Performance Considerations

JSON parsers are significantly faster than YAML parsers. The simpler grammar means less work to tokenize and parse. For configuration files read once at startup, this is irrelevant. For systems that parse thousands of documents per second — log processors, API gateways, stream processors — always use JSON. The performance gap between JSON and YAML parsers is typically 5–20x.