YAML vs JSON: When to Use Each (with Examples)

YAML and JSON: Two Sides of the Same Coin

YAML (YAML Ain't Markup Language) and JSON (JavaScript Object Notation) are both popular data serialization formats. They can represent the same data structures but differ significantly in syntax, readability, and typical use cases. Choosing the right one depends on whether your priority is human readability or machine parsing.

Syntax Comparison

JSON Example

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "debug": false,
    "allowed_origins": ["https://example.com", "https://app.example.com"],
    "database": {
      "url": "postgres://localhost:5432/mydb",
      "pool_size": 10
    }
  }
}

Equivalent YAML

server:
  host: "0.0.0.0"
  port: 8080
  debug: false
  allowed_origins:
    - https://example.com
    - https://app.example.com
  database:
    url: postgres://localhost:5432/mydb
    pool_size: 10

Key differences:

• YAML uses indentation instead of braces and brackets
• YAML supports comments with #
• JSON requires quotes around all keys
• YAML can omit quotes for most string values

When to Use JSON

1. APIs and Data Exchange

JSON is the standard for REST APIs. Every major language has built-in or standard-library JSON parsing:

// Node.js: native JSON support
const data = JSON.parse('{"name": "Alice", "score": 95}');

// Fetching from an API
const response = await fetch('https://api.example.com/users');
const users = await response.json();

2. Package Manifests

package.json, tsconfig.json, and composer.json all use JSON:

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "react": "^19.0.0",
    "next": "^15.0.0"
  }
}

3. Configuration Where Comments Are Not Needed

If your config is generated or rarely edited by hand, JSON's strict syntax prevents ambiguity.

When to Use YAML

1. Docker Compose

# Docker Compose service definition
services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=db
    depends_on:
      - db

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: secret

volumes:
  pgdata:

2. Kubernetes Manifests

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
  labels:
    app: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: myapp:latest
          ports:
            - containerPort: 8080
          resources:
            limits:
              memory: "256Mi"
              cpu: "500m"

3. CI/CD Pipelines

GitHub Actions, GitLab CI, and CircleCI all use YAML:

# .github/workflows/ci.yml
name: CI Pipeline
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

Side-by-Side Comparison

Feature	JSON	YAML
Comments	Not supported	# comments
Readability	Moderate	High
Verbosity	More verbose	More concise
Parsing speed	Faster	Slower
Data types	Strings, numbers, bools, null, arrays, objects	All JSON types + dates, timestamps, multi-line strings
Spec strictness	Very strict	Permissive (can cause bugs)
Multi-document	Not supported	--- separator
Use case	APIs, data exchange	Configuration files

Converting Between YAML and JSON

Python

import json
import yaml

# YAML to JSON
with open('config.yaml') as f:
    data = yaml.safe_load(f)

with open('config.json', 'w') as f:
    json.dump(data, f, indent=2)

# JSON to YAML
with open('config.json') as f:
    data = json.load(f)

with open('config.yaml', 'w') as f:
    yaml.dump(data, f, default_flow_style=False)

Command Line

# Using yq (YAML processor)
yq -o=json config.yaml > config.json

# Using Python one-liner
python3 -c "import sys,yaml,json; json.dump(yaml.safe_load(open(sys.argv[1])),sys.stdout,indent=2)" config.yaml

YAML Gotchas to Watch Out For

Be careful with YAML's implicit typing. These values might surprise you:

# These are all booleans in YAML 1.1!
yes: true
no: false
on: true
off: false

# Norway problem: NO becomes false
countries:
  - GB
  - US
  - NO  # This becomes boolean false!

# Fix: quote the value
countries:
  - GB
  - US
  - "NO"

Convert Instantly with DevToolBox

Need to quickly convert between YAML and JSON? Use the DevToolBox YAML/JSON Converter — paste your data in either format and get instant conversion with syntax validation. No installation needed.