YAML and JSON: what's the difference?

Both YAML and JSON are formats for representing structured data, and they can describe the same information. The key difference is their design goals. JSON was designed to be simple, strict, and easy to parse programmatically. YAML was designed to be human-friendly — easier to read and write by hand, with support for comments and a less cluttered syntax.

YAML is technically a superset of JSON: any valid JSON document is also valid YAML. The reverse is not true — YAML has features (comments, anchors, multi-line strings) that have no JSON equivalent.

Where YAML is used

YAML has become the dominant format for configuration files in the DevOps and cloud-native ecosystem:

• Docker Compose — service definitions, networks, volumes, and environment variables
• Kubernetes — manifests for pods, deployments, services, config maps, and everything else
• GitHub Actions — workflow definitions, job steps, and triggers
• GitLab CI/CD — pipeline configuration
• Ansible — playbooks and role definitions
• Helm charts — Kubernetes package templates
• Jekyll, Hugo — static site front matter

YAML gotchas every developer should know

The Norway Problem (implicit type coercion)

YAML 1.1 — used by many parsers — converts unquoted values that look like booleans:

# YAML 1.1 — these are ALL parsed as booleans, not strings:
- NO      # false
- YES     # true
- ON      # true
- OFF     # false
- True    # true
- False   # false

# Fix: always quote strings that could be misinterpreted
- "NO"
- "YES"

The Norway Problem is named after the ISO 3166 country code NO — configurations with country codes frequently encounter this bug.

Indentation sensitivity

YAML uses indentation to define structure. Mixing tabs and spaces, or getting the indentation level wrong by even one space, produces a different document or a parse error. Always use spaces (never tabs) and be consistent with your indentation depth (2 spaces is standard).

Implicit string vs number coercion

# These values are parsed as numbers without quotes:
version: 1.0          # float
port: 8080            # integer
tag: 1.10             # float (1.1, losing the trailing zero)

# Quote them to preserve as strings:
version: "1.0"
port: "8080"
tag: "1.10"

When to convert YAML to JSON

APIs almost universally expect JSON, not YAML. If you need to send a Kubernetes manifest or a config file to an API endpoint, convert it to JSON first. Many command-line tools also accept JSON more reliably than YAML. Converting YAML to JSON also strips comments and resolves anchors, giving you a clean, unambiguous payload.

When to convert JSON to YAML

JSON API responses and configuration templates are often stored or edited as YAML because YAML is easier to read and annotate with comments. If you receive a JSON response from the Kubernetes API and want to store it as a manifest for version control, converting it to YAML makes it significantly more maintainable.

Example: Docker Compose YAML and its JSON equivalent

# YAML (docker-compose.yml)
services:
  api:
    image: node:20-alpine
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://db:5432/myapp
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret

// JSON equivalent
{
  "services": {
    "api": {
      "image": "node:20-alpine",
      "ports": ["3000:3000"],
      "environment": {
        "DATABASE_URL": "postgres://db:5432/myapp"
      },
      "depends_on": ["db"]
    },
    "db": {
      "image": "postgres:16",
      "environment": {
        "POSTGRES_PASSWORD": "secret"
      }
    }
  }
}

All processing happens in your browser using the js-yaml library. Your configurations never leave your device.