JSON vs YAML: Practical Differences

YAML and JSON often show up together in the same kind of context: configuration files, infrastructure definitions (Docker Compose, Kubernetes, CI/CD), and data exchange between tools. In fact, every valid JSON is also valid YAML (YAML is a superset of JSON), but in practice the two syntaxes feel quite different to write and read.

Comparing the syntax

The same data in both formats:

JSON:

{
  "name": "Ana",
  "age": 30,
  "hobbies": ["reading", "running"]
}

YAML:

name: Ana
age: 30
hobbies:
  - reading
  - running

The most visible difference: YAML uses indentation and line breaks to define structure, instead of braces, brackets, and commas. This makes YAML more readable for humans in large files, but also more sensitive to spacing errors, since indentation carries structural meaning (similar to Python in that regard).

Why YAML is so common in configuration

YAML became popular mainly in infrastructure and DevOps tools: Docker Compose, Kubernetes, GitHub Actions, Ansible, among others. The main reason is readability: configuration files tend to be written and reviewed by humans frequently (not just generated/consumed by code), and the syntax without braces/brackets looks cleaner in files with heavily nested structure.

# docker-compose.yml
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - ENVIRONMENT=production

Features YAML has that JSON doesn’t

Comments

# This is a comment
name: Ana

Unlike JSON, YAML supports comments natively, which is quite useful in configuration files where you want to document decisions or temporarily disable an option.

Multiple documents in one file

---
name: Ana
---
name: John

--- separates multiple YAML documents within the same file, something JSON has no native way to represent (you’d need to use an array).

References and anchors

defaults: &defaults
  timeout: 30
  retries: 3

service_a:
  <<: *defaults
  name: service-a

service_b:
  <<: *defaults
  name: service-b

YAML lets you define a reusable block (an anchor, marked with &) and reference it elsewhere (with * and <<), avoiding repetition. This doesn’t exist in JSON.

Where JSON still wins

Parsing and performance

JSON is computationally simpler to parse, which makes it faster and more predictable for systems exchanging large volumes of data (like APIs). JSON’s simpler grammar also means less ambiguity when interpreting the content.

Sensitivity to spacing

YAML’s reliance on indentation is a double-edged sword: it looks great when it’s right, but one extra or missing space can completely change the document’s structure, silently, without an obvious error. JSON, relying on explicit delimiters ({}, []), is more resistant to this kind of subtle mistake.

Universal compatibility in APIs

Practically every REST API uses JSON as its default format. YAML rarely shows up as a data exchange format between systems over a network, being used mostly for local configuration files.

An interesting detail: YAML accepts JSON

As mentioned earlier, every valid JSON is also valid YAML. This means that, technically, you can write a .yaml file using 100% JSON syntax and it’ll work fine with any YAML parser.

{"name": "Ana", "age": 30}

This isn’t common in practice (it would lose YAML’s readability advantage), but it’s useful to know, especially when converting between the two formats.

Quick summary

	JSON	YAML
Syntax	Braces, brackets, commas	Indentation, no delimiters
Comments	Not supported	Supported
Readability in large files	Lower	Higher
Sensitivity to spacing	Low	High
Most common use	APIs, data exchange between systems	Local configuration, infrastructure

Which one should you use?

For data exchange between systems (APIs, for example), JSON remains the standard choice. For configuration files that humans will read and edit frequently (Docker Compose, CI/CD pipelines), YAML tends to be more comfortable, as long as you pay attention to indentation.

If you need to validate a JSON (or confirm that a YAML converted to JSON came out correctly), JSON Validator helps you spot syntax problems quickly.