If you’ve worked with configuration files, APIs, or data serialization, you’ve encountered at least two of these formats. They all represent structured data, but they make very different trade-offs. Here’s a practical guide to help you choose.

Quick overview

Feature	JSON	YAML	TOML
Human readable	Moderate	High	High
Comments	No	Yes	Yes
Spec complexity	Low	High	Low
Trailing commas	No	N/A	No
Multi-line strings	No (use `\n`)	Yes	Yes
Common use	APIs, data exchange	Config, CI/CD	Config (Rust, Go)

JSON: the universal format

JSON (JavaScript Object Notation) is the lingua franca of data exchange. Every programming language can parse it, every API speaks it.

Strengths:

Universally supported
Unambiguous parsing — no surprises
Fast to parse programmatically
Strict spec means consistent behavior

Weaknesses:

No comments (a constant frustration for config files)
Verbose — lots of quotes and braces
No trailing commas (easy source of syntax errors)
No multi-line strings

Best for: API responses, data storage, inter-service communication.

YAML: the human-friendly format

YAML (YAML Ain’t Markup Language) prioritizes human readability with significant whitespace and minimal syntax.

Strengths:

Very readable for simple structures
Supports comments
Multi-line strings with several styles
Anchors and aliases for DRY configs

Weaknesses:

Indentation-sensitive (tabs vs spaces issues)
Implicit typing can cause bugs (yes/no → booleans, 3.10 → float 3.1)
Complex spec with many edge cases
The “Norway problem” (NO parsed as false)

Best for: CI/CD pipelines (GitHub Actions, GitLab CI), Kubernetes manifests, Docker Compose, Ansible.

TOML: the configuration format

TOML (Tom’s Obvious Minimal Language) was designed explicitly for configuration files. It’s the default for Rust (Cargo.toml), Go modules, and Python packaging (pyproject.toml).

Strengths:

Explicit typing (no implicit conversions)
Supports comments
Clear table/section syntax
First-class date/time support
Simple, small spec

Weaknesses:

Deeply nested data becomes awkward
Less tooling than JSON/YAML
Not suitable for data exchange between services

Best for: Application configuration, project metadata files.

Common gotchas

YAML’s implicit typing

# This is a boolean, not a string!
country: NO

# This is a float 3.1, not string "3.10"
version: 3.10

Fix it with explicit quotes: country: "NO", version: "3.10".

JSON’s strictness

{
  "name": "example",
  "version": "1.0",  // ← This comment is invalid JSON
}

JSON doesn’t allow comments or trailing commas. Use JSONC (JSON with Comments) or strip them before parsing.

TOML’s nesting

[servers.alpha]
ip = "10.0.0.1"

[servers.alpha.dc]
name = "eqdc10"

For deeply nested data, TOML gets verbose fast. If your config is more than 3 levels deep, consider JSON or YAML.

Converting between formats

Instead of manually rewriting data from one format to another, you can drop any of these formats into JSON Lens. It auto-detects the format and parses it into the same visual tree — whether your input is JSON, YAML, TOML, XML, or even HTML.

This makes it easy to:

Validate that your YAML config is structurally correct
Explore a TOML file as if it were JSON
Compare the same data in different formats

Bottom line

Use JSON for APIs and data exchange — it’s the safe default
Use YAML for CI/CD and DevOps configs — but be careful with implicit typing
Use TOML for application configuration — especially in Rust/Go/Python ecosystems
When in doubt, pick the format your ecosystem expects