JSON vs YAML: differences and use cases

JSON and YAML are the two most widely used textual serialisation formats for describing structured data: application configuration, API payloads, infrastructure files, Kubernetes manifests, CI/CD pipelines. Both represent the same fundamental structures (objects, lists, scalars) but with different philosophies: JSON favours machine readability and universality, YAML bets on human readability and conciseness. This article compares the two formats point by point to help you choose.

What is JSON?

JSON (JavaScript Object Notation) is a serialisation format introduced by Douglas Crockford in the early 2000s, derived from JavaScript's object literal syntax. Standardised by RFC 8259 and ECMA-404, it is today the pivot format of the web: almost all REST APIs, NoSQL databases and frontend configurations use it.

JSON is built on two structures:

• An ordered collection of key-value pairs (the object, between curly braces)
• An ordered list of values (the array, between square brackets)

Scalar values are string, number, true, false or null. Strings must be surrounded by double quotes. JSON does not support comments.

What is YAML?

YAML (YAML Ain't Markup Language) is a format that appeared in 2001, designed from the start to be human-readable. The current specification is YAML 1.2.2. Its distinctive feature: it uses indentation to express hierarchy, in the manner of Python.

YAML has been a superset of JSON since version 1.2: every valid JSON document is a valid YAML document. But YAML adds a lot: comments, unquoted strings, multi-line strings, anchors and aliases, tags for explicit typing, multiple documents in the same file (---).

Syntax compared

Here is the same structure expressed in both formats.

JSON

{
  "name": "cdrn",
  "version": "1.14",
  "tags": ["seo", "tools", "open-source"],
  "author": {
    "name": "Adrien",
    "email": "contact@example.com"
  },
  "active": true,
  "stars": null
}

YAML

# Configuration projet
name: cdrn
version: "1.14"
tags:
  - seo
  - tools
  - open-source
author:
  name: Adrien
  email: contact@example.com
active: true
stars: null

On the same content, YAML takes roughly the same number of lines but avoids the braces, the brackets, the trailing commas and the quotes on most strings. Comments (# lines) are allowed.

Supported types

JSON knows 6 types: object, array, string, number, boolean, null. No native date, no binary, no explicit integer/float distinction.

YAML 1.2 knows the same types as JSON and adds: ISO 8601 timestamps, binaries (base64-encoded via the !!binary tag), distinct integers and floats, infinity, NaN, and custom types via tags (!!str, !!int, !!float...). YAML 1.1 accepted yes/no/on/off as booleans: a classic pitfall on older parsers.

Performance and ecosystem

JSON is typically 3 to 10 times faster to parse than YAML, and its parsers are available everywhere (built into the runtime of almost every language). YAML libraries are heavier because they handle a richer grammar (anchors, tags, multi-doc).

On the ecosystem side: JSON dominates HTTP APIs, NoSQL databases (MongoDB, CouchDB), the package.json, composer.json and tsconfig.json files. YAML has become the norm for application configuration and infrastructure-as-code: Symfony, Spring Boot, Rails, Docker Compose, Kubernetes, GitHub Actions, GitLab CI, Ansible.

Comparison table

Typical use cases

Choose JSON when

• You are designing a REST API or a webhook endpoint
• You are storing data in a NoSQL database or a cache
• You are exchanging data between frontend and backend
• Parsing performance is critical (high throughput, edge)
• You want a universally supported format with no dependency

Choose YAML when

• You are writing an application configuration edited by hand
• You need comments to document the options
• You are writing Kubernetes, Docker Compose, GitHub Actions or Ansible
• You want to factor out blocks with anchors and aliases
• Readability matters more than processing speed

Recommendation

The simple rule: JSON for machines, YAML for humans. If your file is produced or consumed by a program, pick JSON. If it is written and read by hand, pick YAML. Many ecosystems accept both: Symfony reads YAML, JSON and XML for its configurations, Kubernetes accepts both for its manifests. When in doubt, go with YAML for human-facing configuration and JSON for automated flows.

You can try converting between the two formats with our JSON / YAML converter and quickly format a document with the JSON formatter.

Frequently asked questions