Key Points for Designing JSON API Data Contracts
Six things are very hard to change once shipped: response envelopes, error formats, pagination shape, representation of IDs and time, the semantics of null versus absent, and version evolution.
Putting JSON into real systems: how to define API contracts, how to manage configuration and fixtures, how to handle version compatibility, and how to maintain test data.
6 articlesSix things are very hard to change once shipped: response envelopes, error formats, pagination shape, representation of IDs and time, the semantics of null versus absent, and version evolution.
Configuration must be layered and validated; fixtures must be deterministic, readable, and diffable. If these two kinds of files are managed poorly, troubleshooting costs stay high for a long time.
Fifty records become fifty-one and the diff reports fifty-one changes. Covers text-diff false positives, matching arrays by id, jq normalization and applicable patches.
merge=union lets broken JSON through and still reports success. This walks through a key-aware three-way merge driver for JSON, plus three habits that cut conflicts.
Adding a field is not automatically safe. Covers compatibility boundaries, version fields, deprecation windows, dual-write migration, contract tests and canary metrics.
When a validator accepts a document and the downstream service crashes, two parsers have usually disagreed about the same text. This article tests duplicate keys, NUL bytes, invalid UTF-8, NaN and leading zeros against real runtimes, explains how CVE-2026-33948 turned parser disagreement into an attack surface, and shows how to assign a single arbiter to every boundary.