JSON YAML — Cheat Sheet

Tags: json, yaml, serialization, api, configuration, devops

Level: intermediate

TL;DR: JSON is the strict, ubiquitous standard for web APIs; YAML is the human-friendly superset optimized for configuration files, supporting comments and references.

Key concepts

JSON syntax derives from JavaScript object literals and requires double quotes for keys and strings.

YAML uses whitespace indentation to define document hierarchy instead of braces and brackets.

Standard JSON specification explicitly forbids comments, whereas YAML supports # comments natively.

YAML 1.2 is theoretically a superset of JSON; valid JSON documents parse as valid YAML.

JSON supports six data types: string, number, object, array, boolean, and null.

YAML natively supports complex types including dates, timestamps, multi-line blocks, and sets.

YAML anchors (&) and aliases (*) allow reusable definitions and DRY configurations.

JSON parsing is deterministic, native in browsers, and significantly faster than YAML parsing.

YAML allows optional quoting of strings, inferring data types based on unquoted tokens.

Typical questions and ready answers

Q: When do you choose JSON over YAML in a project architecture?R: I pick JSON for web API payloads, service-to-service communication, and high-throughput serialization due to strict schemas, fast parsing, and native browser support. I pick YAML for configuration files like Kubernetes manifests, CI/CD pipelines, and local tooling configs where human readability, comments, and anchors are required.

Q: What is the Norway problem in YAML?R: In YAML 1.1, unquoted strings like NO (the country code for Norway), YES, TRUE, or FALSE are automatically coerced into booleans. If a country code is left unquoted, NO parses as false. I solve this by explicitly quoting country codes or adopting YAML 1.2 parsers.

Q: Can JSON handle circular references or reusability like YAML?R: JSON cannot handle cyclic graphs natively without custom application schemas or external references like JSON Schema $ref. YAML natively supports graph serialization, anchors (&), and aliases (*), allowing repeated blocks and cyclic references.

Pitfalls and common mistakes

Mixing tabs and spaces in YAML produces syntax errors; YAML strictly forbids tabs for indentation.

Keys or strings wrapped in single quotes in JSON cause parsing failures; only double quotes are valid.

Trailing commas in objects or arrays break strict JSON parsers.

Relying on auto-type conversion in YAML can convert unquoted version strings like 2.10 to numeric 2.1.

Large multi-line strings in JSON require escaped newlines (\n), reducing human readability compared to YAML | and >.

YAML parsing is vulnerable to arbitrary code execution exploits (e.g., PyYAML yaml.load() without SafeLoader).

Snippets and commands

{
  "name": "service-config",
  "port": 8080,
  "enabled": true,
  "endpoints": [
    "/healthz",
    "/metrics"
  ]
}

YAML

# Equivalent YAML representation with reusable anchor
defaults: &base_service
  port: 8080
  enabled: true

service:
  <<: *base_service
  name: "service-config"
  description: >
    Folded multi-line string
    replaces newlines with spaces.
  raw_log: |
    Preserved line 1
    Preserved line 2
  endpoints:
    - /healthz
    - /metrics

Bash

# Validate and format JSON via jq
cat data.json | jq .

# Convert YAML to JSON via yq
yq -o=json eval file.yaml

To review

[ ] Multi-line string modifiers in YAML: | (literal/newlines preserved) versus > (folded/spaces).

[ ] Chomp operators in YAML: strip (-) and keep (+) whitespace at EOF.

[ ] Python safe loading practices using yaml.safe_load() instead of yaml.load().

[ ] JSON Schema validation standards and draft specifications.

[x] Basic serialization between JavaScript objects and JSON strings using JSON.stringify() and JSON.parse().

Jarvis Interviews
Jarvis