JSON vs YAML: Differences, When to Use Each

JSON vs YAML at a glance

Side-by-side comparison

The same data in both formats:

# YAML
server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - https://example.com
    - https://staging.example.com
  database:
    url: postgres://localhost/mydb
    pool_size: 10

// JSON
{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": [
      "https://example.com",
      "https://staging.example.com"
    ],
    "database": {
      "url": "postgres://localhost/mydb",
      "pool_size": 10
    }
  }
}

Key syntax differences

Comments

YAML supports comments with #. JSON does not. This is the most common reason developers prefer YAML for configuration files.

# YAML — comments work fine
database:
  pool_size: 10   # increase to 20 under heavy load

// JSON — no comments. Workarounds like "_comment" keys are hacks.
{ "pool_size": 10 }

Strings

JSON requires double quotes on all strings. YAML allows bare strings — but some bare values get parsed as booleans or numbers, which causes subtle bugs.

# YAML 1.1 — dangerous bare values
version: 1.0    # number, not string
enabled: yes    # boolean true
country: NO     # boolean false — "The Norway Problem"

# Safe: always quote strings that could be misread
country: "NO"
version: "1.0"

Multiline strings

YAML has native multiline support. JSON requires manual \n escaping.

# YAML literal block (preserves newlines)
message: |
  Line one
  Line two

// JSON
{ "message": "Line one
Line two" }

Null and booleans

# YAML — multiple valid forms
null_value: null
null_value: ~

boolean: true
boolean: false

// JSON — only one valid form each
{ "null_value": null, "boolean": true }

When to use JSON

• APIs and HTTP responses — JSON is the universal language of REST APIs. Every HTTP client and server supports it natively.
• Data interchange between systems — JSON's strictness prevents ambiguity. There's no "Norway problem" in JSON.
• package.json, tsconfig.json, manifest files — The npm, TypeScript, and VS Code ecosystems standardize on JSON.
• When you need a formal spec — JSON has one canonical RFC. YAML has multiple incompatible versions (1.1 vs 1.2).

If you want the same comparison framed from the config-authoring angle, see YAML vs JSON.

When to use YAML

• CI/CD pipelines — GitHub Actions, GitLab CI, CircleCI all use YAML. Comments let you explain complex workflow logic.
• Kubernetes manifests — The entire Kubernetes ecosystem is YAML-based.
• Application config files — Docker Compose, Ansible, Helm charts use YAML. Comments and multiline strings are genuinely useful.
• Human-edited files — When non-developers need to edit a config, YAML's lack of braces and quotes is less intimidating.

YAML gotchas

• The Norway problem — NO, yes, on, off are all booleans in YAML 1.1. Always quote strings that could be misread.
• Indentation is structure — Unlike JSON, whitespace defines nesting. One wrong indent breaks the file. Tabs are not allowed.
• Document separators — --- starts a new YAML document. A Kubernetes file with multiple --- separators is multiple YAML documents in one file.
• Anchors and aliases — YAML supports reusable blocks (&anchor / *alias). Useful but adds complexity JSON doesn't have.

Converting between JSON and YAML

JSON is a valid subset of YAML 1.2 — every valid JSON file is also valid YAML. Converting from JSON to YAML is always safe. Converting YAML to JSON may fail if the YAML uses features JSON doesn't support (comments are lost, anchors must be resolved, multiline strings collapse).

For a tool-oriented workflow, follow the JSON to YAML tutorial.

Frequently asked questions

Can YAML replace JSON in APIs?

Rarely. JSON is the universal default for REST and GraphQL APIs because every HTTP client supports it natively. YAML parsers are not built into browsers or runtimes, so switching to YAML adds dependencies on both ends with no real benefit.

Does YAML support comments but JSON does not?

Yes. YAML uses # for inline comments. JSON has no comment syntax — adding // or # causes a parse error. Comments are the primary reason developers prefer YAML for config files.

What is the Norway problem in YAML?

In YAML 1.1, the bare value NO is parsed as boolean false. Country codes, feature flags, and other short uppercase strings can trigger implicit boolean conversion. Fix it by quoting the value: country: "NO".

Can I convert JSON to YAML without data loss?

Yes. JSON is a valid subset of YAML 1.2, so conversion is always safe in that direction. Going YAML to JSON may lose comments, anchors must be resolved, and multiline strings collapse.

Which is faster to parse: JSON or YAML?

JSON is typically 5–20x faster than YAML because the parser has no type inference, indentation logic, or anchor resolution to perform. For APIs and performance-sensitive paths, always use JSON.

Should I use JSON or YAML for Kubernetes configs?

YAML is the Kubernetes community standard. kubectl accepts both, but all official examples and tooling use YAML. Comments and the --- multi-document separator make YAML practical for hand-authored manifests.