The visible problem may look like one API or tuning value, but reliability is decided by state ownership, resource bounds, and recovery after failure. Unknown JSON fields are often safe, but changing seconds to milliseconds or null meaning silently breaks unchanged types. Schemas document semantics and units.
An API contract includes units, defaults, idempotency, error classes, and version windows—not only field types. Clients distinguish retryable, user-action, and permanent outcomes to avoid duplicate side effects.
Make the implementation decisions explicit
Turn the important choices into durable contracts: validate inputs, assign state ownership, define cleanup, and specify fallback for older peers. Later optimization must not change those semantics.
- Add optional fields with defaults, handle unknown enums, introduce new fields or versions for breaks, and remove old fields only after an observed deprecation cycle.
- Bound every input by size, count, and time, returning a stable actionable error code when a budget is exceeded.
- Ship conservative defaults, server-side ceilings, and a rollout switch instead of trusting browser-provided numbers as resource budgets.
The delivery standard for API Schema Evolution: Semantic Changes Are More Dangerous Than Fields is a usable normal path, convergent failures, bounded resources, and a state users can understand. The result is a production capability that can be explained, degraded safely, and rolled back—not a demo that works once.
Failure paths that are easy to miss
Boundaries turn hidden assumptions into incidents. Weak networks, refresh, concurrency, and capacity need combined coverage because retries can hide each one in isolation.
- A new enum can crash an exhaustive old switch, while reusing a field with reversed meaning makes both versions locally correct but mutually wrong.
- Fixing only the UI leaves queues, locks, or expired credentials for the next operation to inherit and fail again.
- User or task IDs in metric labels create high-cardinality cost and leak unnecessary identity into diagnostics.
How to verify it before release
Observe both endpoints, persisted records, and operational signals during verification. One button state or one successful response cannot prove the complete loop.
- Keep current and historical payloads as consumer contracts and run both version directions with deterministic unknown fields, enums, and omissions.
- Disconnect, change networks, and recover mid-operation; reconcile endpoint state, persistence, and resource counts.
- Cover direct, relayed, weak-network, background-tab, and mobile paths; do not rely on averages or one successful screenshot.
The result must be correct, recoverable, and explainable. If any part depends on refreshing the page or an engineer guessing, the protocol loop remains incomplete.