JSON vs YAML for APIs
May 24, 2026 · 14 min read
YAML wins hearts in Kubernetes manifests and docker-compose files because comments and indentation feel natural to humans. JSON wins HTTP APIs because every client library parses it, caches love it, and debuggers display it without ambiguity - most of the time.
Problems appear when teams use YAML for public request bodies or treat JSON config as editable by hand without validation. This guide draws a bright line: YAML for human-authored static config, JSON for machine-to-machine messages - plus safe conversion when you must bridge both.
Different jobs
Use YAML when non-developers edit deployment config, when comments document intent inline, and when files live in Git reviewed by humans. Use JSON for REST/GraphQL responses, webhook payloads, message queues, and browser storage where parsers must be strict and fast.
OpenAPI documents are often YAML in repos but many gateways consume JSON equally well. Pick one source format and generate the other in CI to avoid two sources of truth.
YAML gotchas
YAML 1.1 may interpret unquoted yes/no as booleans and 0x10 as hex. Indentation defines structure - a tab in the wrong column breaks parsing silently in large files. Always run yamllint and schema validation in CI.
Anchors and aliases (& / *) deduplicate config but confuse diff tools. For APIs, never expose YAML features clients cannot reproduce in JSON.
# YAML config (human-friendly)
server:
port: 8080
tls: true
# Equivalent JSON for the same data
{ "server": { "port": 8080, "tls": true } }JSON on the wire
HTTP Content-Type: application/json is the default contract. Compression (gzip, brotli) handles size; JSON itself stays verbose but predictable. Version APIs with explicit schema evolution rather than switching wire formats per client.
GraphQL responses are JSON. gRPC uses protobuf on the wire but often surfaces JSON in gateways and debug tools. JSON’s ubiquity keeps it the debugging format even when production uses binary encodings elsewhere.
Converting safely
YAML → JSON conversion should happen in a controlled build step, not ad hoc in production.request handlers. Watch for loss of comment metadata (expected) and type coercion (dangerous). JSON → YAML is useful for generating starter configs from machine output - review indentation and quoting afterward.
Large integers and timestamps should use explicit string formats in both worlds. A YAML timestamp type may become an ISO string in JSON; document the rule.
Team policy template
Adopt a short RFC: public APIs accept and return JSON only; internal Helm/K8s stays YAML; CI converts and validates; editors must not send YAML bodies to public endpoints. Store JSON Schema for any JSON file humans edit.
When onboarding, show one worked example of each format side by side. Developers stop debating preferences when policy is boring and automated.
FAQ
- Should public APIs accept YAML?
- Generally no. Stick to JSON (or documented binary formats). YAML’s flexibility creates interoperability bugs.
- Why does my YAML boolean become a string in JSON?
- Quoting and YAML version affect typing. Quote values intentionally and validate with a schema after conversion.
- Is JSON a subset of YAML?
- Most JSON documents are valid YAML 1.2, but do not rely on that for security parsing - use the correct parser per format.
- Can OpenAPI be JSON instead of YAML?
- Yes. Many teams author YAML and publish JSON artifacts from CI for tools that prefer JSON.