Home / Tutorials / YAML vs JSON: A Practical Guide for Developers

Config

YAML vs JSON: A Practical Guide for Developers

2026-06-22 · 18 min read

Compare YAML and JSON: syntax, use cases, tradeoffs, and practical recommendations from real-world experience with APIs, configs, and DevOps.

Introduction: YAML and JSON in the Real World

I work with YAML and JSON every single day. YAML for Kubernetes manifests, GitHub Actions, and Docker Compose. JSON for APIs, data storage, and messages between services.

The question I get all the time is: "When should I use YAML vs JSON?"

The short answer is: **YAML is for humans, JSON is for machines.** But the full answer is more nuanced than that — there are tradeoffs, edge cases, and best practices you need to know.

In this guide, I'll break down the differences with real-world examples, common pitfalls I've seen, and practical recommendations you can apply today.

And remember: You can always convert between them with our JSON to YAML tool! I use it constantly when I need to translate example JSON payloads to YAML config files.

Quick Overview: YAML and JSON at a Glance

Let's start with a high-level comparison to set the stage:

**YAML (YAML Ain't Markup Language)**

- Human-first design — optimized for reading and writing by humans

- Comments are allowed and actively used (huge win for config files!)

- Uses indentation to define structure (like Python)

- Supports more data types and features (anchors, aliases, multi-line strings)

- Can be complex and has many edge cases

- Slower to parse, with more variation between libraries

**JSON (JavaScript Object Notation)**

- Machine-first design — optimized for parsing and data exchange

- No comments allowed (explicit design choice!)

- Uses braces `{}` for objects and brackets `[]` for arrays (like JavaScript)

- Simple, strict, and predictable — few edge cases

- Fast to parse, with consistent behavior across all languages

- The de facto standard for APIs and data exchange

The fundamental difference is in the design philosophy: YAML is about human convenience, JSON is about machine simplicity.

Side-by-Side Example: The Same Data in Both Formats

Let's look at the same data structure in both formats to see the differences clearly:

**JSON:**

{
  "name": "My App",
  "version": "1.0.0",
  "description": "A production-ready web application",
  "features": ["auth", "payments", "search"],
  "debug": true,
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "app_prod"
  },
  "deployment": {
    "replicas": 3,
    "regions": ["us-east-1", "us-west-2"]
  }
}

**YAML:**

# Application Configuration
# Last updated: 2026-06-22
name: My App
version: 1.0.0
description: A production-ready web application
features:
  - auth
  - payments
  - search
debug: true
database:
  host: localhost
  port: 5432
  name: app_prod
deployment:
  replicas: 3
  regions:
    - us-east-1
    - us-west-2

The data structure is identical — these two files represent the exact same thing! But notice the differences:

- YAML has comments at the top explaining what this is

- No quotes around strings (usually)

- Indentation defines structure instead of braces

- Colons instead of commas to separate keys and values

- No need for commas between items at all!

The YAML is more compact and arguably more readable. The JSON is more explicit and less ambiguous.

When to Use YAML: The Human-First Scenarios

YAML shines when humans are editing the file frequently. Here are the scenarios where I almost always choose YAML:

**1. DevOps Configuration and Infrastructure as Code**

- Kubernetes manifests — YAML is the standard here

- GitHub Actions workflows — comments make it easier to understand what each step does

- Docker Compose files — complex setups benefit from comments and readability

- Ansible playbooks, Terraform (though Terraform uses HCL), CircleCI configs — all DevOps YAML!

**2. Application Configuration Files**

- Config files that humans edit directly (e.g., settings.yml, config.yml)

- When you need comments to explain why certain settings are the way they are

- When the config structure gets complex with nested objects

**3. Documentation Examples and Tutorials**

- Showing examples in documentation where humans will read and copy the code

- When you need to add comments explaining parts of the example

**Why YAML wins here:**

- Comments are invaluable for explaining what each section does

- More readable for complex nested structures

- Multi-line strings are much cleaner (great for config files with scripts or templates)

**Real-world example:** I have a Kubernetes manifest with comments explaining why we have 3 replicas (for high availability) and why we chose those specific resource limits. Those comments save me time every time I revisit the file.

When to Use JSON: The Machine-First Scenarios

JSON is the best choice when machines are creating, consuming, or exchanging the data. Here's where I use JSON:

**1. API Requests and Responses**

- This is the big one — JSON is the de facto standard for modern APIs

- Every REST API I work with uses JSON (GraphQL uses JSON too, just with a specific structure)

- Why JSON? Fast, predictable, every language has great support

**2. Configuration Generated by Tools**

- If a tool writes the config (not a human), JSON is safer and simpler

- No need for comments because humans won't edit it directly

- Package.json, tsconfig.json, .babelrc — all JSON because they're usually generated or edited with tools

**3. Data Storage and Message Queues**

- Storing structured data in databases (PostgreSQL JSONB, DynamoDB, etc.)

- Message queues like Kafka, RabbitMQ, SQS — JSON is the common format

- Event logs and structured logging

**4. Anywhere You Need Strict, Predictable Parsing**

- When consistency across languages and environments matters

- When you want the simplest, most widely supported format

**Why JSON wins here:**

- Fast to parse — important for APIs handling high traffic

- Predictable — no ambiguity, fewer edge cases than YAML

- Universal support — every language has great JSON libraries built in

- Simple specification — easy to implement consistently

Common YAML Pitfalls and How to Avoid Them

YAML is great, but it has sharp edges. I've made every one of these mistakes at some point!

**1. Indentation Matters (A Lot)**

YAML uses indentation to define structure, which means wrong indentation changes the structure entirely.

Bad indentation:

database:
  host: localhost
    port: 5432  # Wrong — this is nested under host, not database!

Good indentation:

database:
  host: localhost
  port: 5432  # Correct — same indentation as host

**2. The 'Norway Problem' — Strings That Look Like Other Types**

YAML automatically parses certain strings as other types. This famous example:

countries:
  - GB  # String
  - US  # String
  - NO  # Wait — NO is parsed as FALSE in YAML 1.1!

Oops! Norway becomes `false`. The fix: Quote strings that might be ambiguous:

countries:
  - GB
  - US
  - "NO"  # Now definitely a string

**3. Tab Characters Are Forbidden**

YAML doesn't allow tabs for indentation — only spaces. Use spaces (2 is common, 4 is fine too).

**4. Multi-Line String Confusion**

YAML has multiple ways to write multi-line strings:

key: |
  This preserves newlines
  exactly as written

other: >
  This folds newlines into spaces
  except for the final one

Memorize the difference: `|` preserves newlines, `>` folds them.

**5. Anchors and Aliases Are Cool But Confusing**

YAML lets you reuse parts with anchors and aliases. Powerful, but can make the file hard to read for beginners.

**My rule for YAML:** Keep it simple. Use the features you need, but don't get fancy. The more YAML-specific features you use, the more likely you are to hit edge cases.

Common JSON Pitfalls and How to Avoid Them

JSON is simpler than YAML, but there are still mistakes I see regularly:

**1. Trailing Commas**

This is the #1 JSON mistake, and I still make it sometimes!

Invalid:

{
  "name": "John",
  "age": 30,  # Oops — trailing comma here!
}

Valid:

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

Use our JSON Validator if you're not sure — it will point out the exact line with the error.

**2. Comments Are Not Allowed**

I wish JSON had comments, but it doesn't. That's why YAML is better for config files humans edit.

Don't do this:

{
  "name": "John",  // This comment makes it invalid JSON!
  "age": 30
}

If you need comments, use YAML or JSON5 (a superset that allows comments).

**3. Single Quotes Instead of Double Quotes**

JSON requires double quotes around keys and strings. Single quotes won't work.

**4. Unquoted Keys**

JavaScript allows unquoted keys, but JSON doesn't.

**5. Forgetting to Escape Characters**

Quotes, backslashes, and control characters need escaping inside strings.

**The good news:** Our JSON Validator catches all of these! Just paste your JSON in, and it will tell you exactly what's wrong and where.

What About the In-Between Options?

YAML and JSON aren't the only options! There are alternatives that try to combine the best of both worlds.

**JSON5**

- A superset of JSON that allows comments, trailing commas, single quotes, and more

- Great for config files where you want JSON's simplicity but with comments

- Not as widely supported as plain JSON or YAML

**TOML**

- Tom's Obvious, Minimal Language — designed for config files

- Uses INI-like sections: `[section]` then `key = value`

- Used in Cargo (Rust) and other places

- More explicit than YAML, more human-friendly than JSON

**HCL**

- HashiCorp Configuration Language — used in Terraform

- A nice middle ground between JSON and YAML

**My take:** For most projects, stick with YAML or JSON. They're the most widely supported, have the best tooling, and everyone on your team will already know them. Save the alternatives for when you have a specific reason.