YAML

Two formats, overlapping jobs

JSON (JavaScript Object Notation) and YAML (YAML Ain’t Markup Language) both represent structured data: nested objects, lists, strings, numbers, and booleans. They appear in APIs, configuration files, CI pipelines, Kubernetes manifests, and documentation examples. Choosing between them is less about which is “better” and more about who edits the file, which tools consume it, and how strict you need parsing to be.

If you already have JSON and want to inspect it as YAML indentation, try converting with JSON to YAML.

JSON in brief

JSON grew out of JavaScript object literal syntax and became a language-agnostic interchange format. A JSON document is built from:

• Objects: { "key": "value" }
• Arrays: [1, 2, 3]
• Strings in double quotes
• Numbers
• true, false, and null

Notable constraints: no comments, no trailing commas in standard JSON, keys must be strings, and strings use a limited escape syntax. Those constraints make parsers simple and strict—valuable for machines exchanging data.

Pretty-printed JSON is readable for small documents. Large configs with deep nesting become noisy because of braces, brackets, and quoted keys on every line.

YAML in brief

YAML emphasizes human editing. Structure is mostly conveyed by indentation rather than braces. Features include:

• Comments starting with #
• Unquoted strings in many cases
• Anchors and aliases for reuse
• Multiple document streams separated by ---
• Explicit type tags in advanced usage

A small mapping looks like:

service:
  name: api
  replicas: 3
  ports:
    - 8080
    - 8443

The same structure in JSON repeats punctuation and quotes. For operators editing manifests daily, YAML’s brevity is attractive.

Data model overlap

At the core, both formats can express trees of maps and sequences with scalar leaves. Round-tripping is often possible for the common subset: objects, arrays, strings, numbers, booleans, and null.

Differences appear at the edges:

• YAML can produce non-string keys; JSON cannot.
• YAML has more ways to write strings (literal blocks, folded blocks).
• YAML’s “Norway problem” and other implicit typing quirks can turn unquoted NO, on, or version-like tokens into booleans or numbers depending on the YAML version and parser.
• JSON numbers are straightforward; YAML may parse large integers or timestamps specially in some loaders.

When interoperability matters, prefer quoting strings that look like booleans, numbers, or dates in YAML, or generate YAML from a typed structure rather than hand-editing ambiguous scalars.

Comments and documentation

JSON has no standard comments. Teams sometimes abuse "_comment" fields, which pollute schemas. YAML’s # comments document intent next to the data—why a replica count is 3, which team owns a label—without changing the information model.

If your primary audience is machines (APIs, browser fetch bodies), JSON’s lack of comments is rarely a problem. If humans maintain the file for months, YAML comments reduce tribal knowledge loss.

Tooling and ecosystem

JSON strengths

• Ubiquitous parsers in every mainstream language
• First-class browser support (JSON.parse / JSON.stringify)
• Schema ecosystems (JSON Schema) widely adopted
• Line-oriented diffs that, while brace-heavy, are familiar
• Streaming parsers for large payloads

YAML strengths

• Dominant in DevOps (Kubernetes, Ansible, many CI systems)
• Merges and anchors (powerful, sometimes overused)
• Multi-document files for bundling related resources
• Friendlier for lightly nested configuration

YAML risks

• Spec complexity (YAML 1.1 vs 1.2 differences)
• Indentation errors that are hard to see
• Features (custom tags, merge keys) that reduce portability
• Accidental code execution in unsafe loaders historically—always use safe load APIs

Performance and size

For wire protocols, JSON is usually smaller to parse in optimized native libraries and avoids indentation overhead. Compressed JSON and YAML converge in size. For configuration that is read occasionally and edited often, parse speed is rarely the bottleneck; human error rate is.

Binary cousins (MessagePack, CBOR, Protobuf) outperform both when throughput dominates. They are not drop-in human formats.

Conversion strategies

Converting JSON → YAML is typically loss-free for the common subset and useful for readability reviews. Converting YAML → JSON may lose comments, anchors, and non-JSON types. Treat conversion as a projection, not a perfect archive of authoring intent.

Workflow tips:

1. Keep a single source of truth (often JSON Schema or a typed language model).
2. Generate the format each consumer needs.
3. If humans must edit YAML, validate against a schema on every change.
4. Avoid hand-maintaining two copies of the same document.

Tool Plaza’s from-json converter helps you preview how a JSON payload looks with indentation-based syntax.

When to choose JSON

• Public HTTP APIs and webhook bodies
• Browser and mobile clients
• Strict machine interchange with minimal ambiguity
• Logging structured events to aggregators that expect JSON lines
• Embedding in languages where JSON literals map cleanly to native types

When to choose YAML

• Deployment and infrastructure manifests edited by people
• Config files that benefit from comments
• Ecosystems that already standardize on YAML
• Documents where indentation clarity beats brace matching for your team

Hybrid approaches

Some projects store canonical JSON in version control and generate YAML for a specific tool. Others accept YAML input, normalize to an internal AST, and emit JSON for APIs. Both work if the pipeline is automated and tested.

Be cautious with “JSON5” or “JSONC” (JSON with comments) extensions: they improve ergonomics but are not universal. Document the dialect if you adopt one.

Editing and review hygiene

• Use editors that highlight indentation and trailing spaces for YAML.
• Fail CI on invalid syntax before merge.
• Prefer 2-space indentation consistently in YAML teams.
• Keep lines reasonably short; huge inline strings belong in literal blocks or external files.
• Do not paste secrets into either format in public repos—use secret managers and references.

Summary

JSON is the strict, ubiquitous interchange format; YAML is the comment-friendly configuration dialect with richer—and riskier—syntax. They share a nested data model for everyday maps and lists. Pick JSON for APIs and machines, YAML for human-operated infra files, and convert deliberately when you need both views of the same structure.