DEV Community

楊東霖
楊東霖

Posted on • Originally published at devplaybook.cc

JSON vs YAML: Complete Developer Guide

#json #webdev #programming #devtools

JSON and YAML are both data serialization formats. They appear in APIs, configuration files, CI/CD pipelines, Kubernetes manifests, and a dozen other places in modern development. Choosing the wrong one creates friction. Understanding the difference helps you pick the right tool for the job.

This guide covers the key differences, when to use each, common gotchas, and the tools that make working with both formats faster.

The Core Difference

JSON (JavaScript Object Notation) is strict, explicit, and designed for machine-to-machine communication. Every value type is unambiguous. There are no implicit conversions. If something breaks, the error is clear.

YAML (YAML Ain't Markup Language) is designed for human readability. It's less verbose, supports comments, and handles multi-line strings naturally. But it comes with complexity—implicit typing, indentation-sensitive syntax, and a spec that most people don't read in full.

The tradeoff: JSON is safer and more portable. YAML is easier to read and write by hand.

Syntax Comparison

JSON 

{
  "name": "devplaybook",
  "version": "2.0.0",
  "dependencies": {
    "astro": "^4.0.0"
  },
  "active": true,
  "scores": [98, 87, 92],
  "description": null
}
Enter fullscreen mode Exit fullscreen mode

Equivalent YAML 

name: devplaybook
version: "2.0.0"
dependencies:
  astro: "^4.0.0"
active: true
scores:
  - 98
  - 87
  - 92
description: null
Enter fullscreen mode Exit fullscreen mode

The YAML version is shorter and easier to scan. The JSON version is more explicit—you can always tell exactly what type each value is.

YAML Features JSON Doesn't Have

Comments 

# This is a comment
name: devplaybook  # inline comment
Enter fullscreen mode Exit fullscreen mode

JSON has no comment syntax. This alone makes YAML preferable for configuration files that humans maintain.

Multi-line Strings 

description: |
  This is a multi-line
  string that preserves
  newlines.

summary: >
  This is a folded
  string—newlines become
  spaces.
Enter fullscreen mode Exit fullscreen mode

In JSON, multi-line strings require escaped newlines: "line one\nline two".

Anchors and Aliases (Reuse) 

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: api.example.com

staging:
  <<: *defaults
  host: staging.example.com
Enter fullscreen mode Exit fullscreen mode

YAML anchors let you define a block once and reference it elsewhere. JSON has no equivalent—you must duplicate.

JSON's Advantages

Strict Typing

YAML's implicit typing is a source of real bugs. Classic example:

country_code: NO   # Parsed as boolean false in some YAML parsers
version: 1.0       # Parsed as float, not string
port: 8080         # Integer, fine
Enter fullscreen mode Exit fullscreen mode

JSON eliminates this class of bug entirely. "NO" is always a string. 1.0 is always a number.

Universal Support

Every programming language has a JSON parser in its standard library or as a trivially installed package. JSON is the native format of JavaScript and the dominant format of REST APIs.

Predictable Structure

JSON's curly braces and square brackets make structure explicit. You can't accidentally mis-indent a value into the wrong level.

YAML Gotchas to Avoid

Tabs are not allowed for indentation. YAML requires spaces. Mixing tabs and spaces causes parse errors that are hard to spot visually.

The Norway Problem. NO, no, yes, YES, on, off, true, false are all parsed as booleans in YAML 1.1 (the version most parsers use). Wrap these in quotes: country: "NO".

Floating point ambiguity. 1.0, 1e5, and .inf parse as floats. If you need the string "1.0", quote it.

Multiline strings. The | (literal block) and > (folded block) scalars have different behavior with trailing newlines. Test your parser's behavior explicitly.

When to Use JSON

  • APIs. REST APIs almost always use JSON. It's the expected format, and libraries handle it natively.
  • Package files. package.json, composer.json, tsconfig.json—these are maintained by tooling and parsed by machines.
  • When strict types matter. If implicit type coercion could cause bugs, use JSON.
  • When you need streaming parsers. JSON has broader streaming parser support than YAML.

When to Use YAML

  • CI/CD configuration. GitHub Actions, GitLab CI, CircleCI—all use YAML. The comment support and multi-line string handling make pipeline configs readable.
  • Kubernetes manifests. The K8s ecosystem is YAML-first. There's no practical alternative.
  • Helm charts and Ansible. Both are YAML-based.
  • Configuration files humans edit often. Comments, readability, and anchors make YAML preferable when a human touches the file regularly.
  • Docker Compose. docker-compose.yml is standard and benefits from YAML's readability.

Converting Between JSON and YAML

When you need to switch formats—converting a JSON API response to a YAML config, or translating a YAML manifest back to JSON for processing—the JSON to YAML converter handles it instantly in the browser.

Paste in either format, get the other. The converter preserves structure and handles edge cases like nested arrays and null values.

For validating your YAML files before deploying them, the YAML validator catches syntax errors, indentation issues, and type problems before they reach your pipeline.

And when you're working with JSON specifically—formatting it, validating it, exploring its structure—the JSON formatter is the fastest way to go from a raw blob to a readable tree.

Quick Reference

Feature JSON YAML
Comments No Yes
Multi-line strings Escaped only Native (`\
Reuse/anchors No Yes ({% raw %}& / *)
Implicit typing No Yes (can be surprising)
Indentation-sensitive No Yes
Human readability Moderate High
Machine parsing Strict, fast More complex
API standard Yes Rarely
Config files Common Common

The Practical Rule

JSON for data exchange. YAML for configuration.

If a machine writes it and a machine reads it, use JSON. If a developer writes it and reads it—especially if they'll do it often—YAML is usually better.

When you're unsure, consider: will someone need to add a comment to this file? Will it contain multi-line strings? If yes to either, YAML wins. If not, JSON's strictness is probably worth it.

Level Up Your Dev Workflow

Found this useful? Explore DevPlaybook — cheat sheets, tool comparisons, and hands-on guides for modern developers.

🛒 Get the DevToolkit Starter Kit on Gumroad — 40+ browser-based dev tools, source code + deployment guide included.

Top comments (0)