🔧 TL3 Tools

Configuration files come in two popular text formats, JSON and YAML, and teams argue about which one to standardize on. The formats solve the same problem, storing nested data for an application to read at startup, but they make opposite tradeoffs. JSON is strict and unambiguous; YAML is forgiving and pleasant to write by hand. Choosing well means understanding what each format assumes about its reader.

The deciding question is simple: who reads the file more often, a human or a machine? If humans edit it daily, YAML's readability wins. If machines produce and consume it, JSON's rigidity prevents a whole class of bugs.

What Each Format Brings

JSON is a subset of JavaScript's object syntax: key-value pairs in braces, arrays in brackets, strings in double quotes, and numbers, booleans, and null as first-class values. Every parser in every language implements the same grammar, which is why JSON is the default for APIs and machine-to-machine communication. Its strictness is a feature. A JSON file either parses or it does not, and there is exactly one way to read any valid file.

YAML is a superset of JSON that adds indentation-based structure, comments, and a set of human-friendly conveniences. Instead of braces and brackets, nested data is expressed by indenting deeper levels. That makes YAML read like a document, but it also makes whitespace part of the grammar: a single extra space changes the meaning of the file.

Worked Example: A Database Config in Both Faces

Here is a small database configuration written in YAML:

database:
  host: db.internal
  port: 5432
  name: analytics
  pool:
    max: 20
    idle: 5
  retries: 3

The same configuration in JSON:

{
  "database": {
    "host": "db.internal",
    "port": 5432,
    "name": "analytics",
    "pool": { "max": 20, "idle": 5 },
    "retries": 3
  }
}

Both encode the same data. The YAML version drops the braces, the commas, and most of the quotes, which is exactly why people prefer it for hand-edited files. The JSON version is noisier to look at, but every pair of characters is load-bearing and there is no ambiguity about structure. A YAML to JSON converter can translate between the two whenever you need to hand one off to a tool that only accepts the other.

Where Indentation Bites

YAML's reliance on indentation is its greatest risk. In the example above, pool is nested under database because it is indented two spaces further. If a contributor aligns pool with host, the file still parses, but the pool settings silently become a sibling of the database instead of a property of it. Nothing warns you. Tabs are another classic trap: YAML forbids tabs for indentation, and a file that mixes tabs and spaces will fail or, worse, parse into the wrong shape.

JSON has the same nesting risk, but it fails loudly. A missing comma or brace is a parse error, not a silent restructure. That is the tradeoff in one sentence: YAML fails gently into wrong structure; JSON fails loudly into no structure at all.

Type Inference and the Quote Trap

Both formats infer types from syntax, but YAML infers more aggressively, and that creates surprises. In JSON, "version": "1.4" is a string because it is quoted, and "port": 5432 is a number because it is not. In YAML, unquoted values are auto-detected: port: 5432 becomes a number, retries: 3 becomes a number, and a version like 1.4.0 stays a string because it is not a valid number.

The traps live in the edge cases. A value that looks numeric but must remain text, like a postal code or a part number with leading zeros, needs explicit quotes in YAML or the leading zeros are lost. Strings like yes, no, and null are interpreted as booleans and null in many YAML implementations, an infamous source of bugs. Quoting anything that is not clearly a number or a plain word removes the ambiguity.

Comments, Anchors, and What JSON Lacks

YAML supports # comments, which JSON does not. For a config file maintained by a team, comments are where people record why a setting exists, what value is expected in staging, and which option should not be touched. Losing comments is the most common complaint when a team converts YAML configs to JSON.

YAML also adds anchors and aliases, which let you define a block once and reference it elsewhere in the file, and multi-document streams. These are genuinely useful in complex deployment configs, but they are also the features most likely to confuse a newcomer, and they do not translate to JSON at all. If you use them, you are committed to YAML.

How to Choose

A practical rule: choose YAML when the file is edited by people, is nested more than a level or two, and benefits from comments, such as CI pipelines, Docker Compose files, and application configuration. Choose JSON when the file is generated, consumed by another system, or travels over the network, such as API payloads, tool output, and package manifests.

When a config will be read by both humans and machines, which is most of them, default to YAML for the humans and enforce hygiene with linting: a YAML linter catches indentation errors and type surprises in CI, giving you the readability without the silent-failure risk. When in doubt, JSON. Its constraints are annoying to write and trivial to reason about, and a config that cannot be misread is a config that will not be misparsed.

Trying It Yourself

The YAML to JSON converter on this site converts between the two formats in your browser, with nothing uploaded to a server. Paste the YAML example above and watch it produce the JSON equivalent, then edit the indentation and see how the converter responds. It is the fastest way to build a feel for where the formats agree and where they diverge.