JSON and YAML best practices

The problem JSON solves

JSON was born as a subset of JavaScript designed so that machines and humans could exchange structured data without ambiguity. Its grammar is deliberately tiny: objects, arrays, strings, numbers, booleans and null. That simplicity is its biggest strength — every serious language ships a strict parser, and the format leaves no room for interpretation. HTTP APIs, structured storage and service-to-service messaging live comfortably in JSON precisely for that.

The price is rigidity: no comments, no trailing commas, no internal references. For humans editing a file by hand, JSON can be awkward. For machines, it is ideal.

The problem YAML solves

YAML assumes the user is human. It allows # comments, groups by indentation instead of braces, lets you skip quotes in many cases and adds anchor/alias references so you can reuse fragments within the same document. That is why it dominates long, hand-edited configs: Kubernetes, GitHub Actions, docker-compose, Ansible.

The price is flexibility: the same flexibility that makes YAML pleasant to edit also enables subtle bugs. Automatic boolean coercion in YAML 1.1, anchors shared across branches, silent type changes when quoting style varies — all are common production bug sources.

When to pick JSON or YAML

A heuristic that holds in roughly 90 % of cases: if a machine will consume the file without a human routinely editing it, pick JSON. If a human will edit it (a developer, a DevOps engineer, an operator), pick YAML.

• HTTP API payloads: JSON.
• Kubernetes / Compose / Actions config: YAML.
• Test results, coverage, structured logs: JSON.
• Long documents with inline annotations: YAML.
• Key-value storage in Redis or similar: serialized JSON.

Common JSON mistakes

• Trailing comma: strict parsers reject {"a": 1,}.
• Comments: // or /* */ break the parser.
• Unquoted keys: {a: 1} is not JSON, it is JavaScript.
• Single quotes: JSON only accepts double quotes.
• Duplicate keys: the parser keeps the last value and silently drops the first.
• NaN or Infinity: not valid JSON either. Serialize as string or as null and document the contract.

Common YAML mistakes

• Inconsistent indentation: two spaces in one section and four in another breaks the document.
• Tabs mixed with spaces: never use tabs in YAML.
• Implicit booleans (YAML 1.1): yes, no, on, off, y, n become booleans silently.
• Version-like values: 1.0 is parsed as a float. Quote it: "1.0".
• Strings containing a colon: `host: foo:bar` may break parsing; quote it.
• Empty lists written wrong: a key followed by nothing instead of [] or {} can be interpreted as null.

Big numbers and precision

JSON has no integer type. Most parsers represent every number as an IEEE 754 double-precision float, which limits exact integers to 2^53 − 1 (9,007,199,254,740,991). Any larger integer silently loses precision: Twitter timestamps, Snowflake IDs, primary keys in large relational databases. If your system uses IDs beyond that range, serialize the fields as strings at the source. That is the only guaranteed way to preserve precision across parsers.

YAML 1.1 vs 1.2 and boolean traps

YAML 1.2 (2009) fixed several problems from YAML 1.1 (2005), but many parsers in use still follow the 1.1 spec. The most dangerous difference is boolean coercion: in 1.1 the strings yes, no, on, off, y, n become booleans automatically; in 1.2, only true and false do. That means a field like country: NO (where NO is the ISO code for Norway) silently becomes false. The defence is to always quote values that can be misread: country: "NO".

Anchors and aliases

YAML lets you define a fragment with &anchor and reuse it with *anchor. It is useful to reduce duplication in long files, but it introduces risks: the alias shares the same reference, so mutating a field in one branch affects every other branch unless the parser deep-clones. YAML → JSON converters generally expand anchors, multiplying file size. If your pipeline converts YAML to JSON before storing it, measure the post-expansion size.

Validate before deploy

The golden rule: any YAML or JSON heading to production is validated before it is applied. In Kubernetes, kubectl apply --dry-run=client does it locally; GitHub Actions has act to validate workflows without pushing. For structured JSON, a JSON Schema with AJV catches not only syntax errors but also type and range inconsistencies. Doing it in CI (not in the operator's browser) prevents silent incidents.

Why client-side validation matters

When a developer pastes a secret, an API key or a token into an online validator, those bytes can end up in logs, intermediate caches or the provider's database. It is a real leak, not theoretical: any service that receives your input processes it on its infrastructure. ToolsOps processes input entirely in your browser — the JavaScript that your browser executes is the only code that ever sees the bytes. For work where the input is sensitive, that contract is the difference between validating and leaking.

When you finish reading, jump back to the JSON and YAML hub to use the validator or the converter with the cheat sheet at hand.