2026-07-22 · 6 min read · Rahul Chitturi
- json
- schema
- api
JSON schema drift often starts as a harmless extra field. A frontend sends metadata for a new experiment, a worker includes a nested debug object, or a partner API preserves unknown keys. If one service allows additional properties and another rejects them, the same payload can pass staging and fail production.
The failure is especially confusing when optional fields, naming conventions, and generated clients are all changing at once. Before relaxing a validator, prove which field is unexpected and whether it belongs in the public contract.
Compare the contract with real fixtures
Use one sanitized passing payload and one failing payload. Format both so nested objects, arrays, and nullable fields are visible before you diff them.
- Check whether the rejected key is top-level or nested inside an object with stricter rules
- Confirm camelCase, snake_case, and kebab-case conversions at API boundaries
- Look for fields generated by logs, tracing, or UI state that should not leave the client
- Decide whether to document the field, strip it, or explicitly reject it with a clearer error
Keep strict validation useful
Strict schemas are valuable because they catch typos and accidental data leakage. The goal is not to turn off validation; it is to make the rule match the contract that consumers can depend on.
When the API intentionally accepts extension fields, scope that behavior to the exact object that needs it. A broad additionalProperties change can hide future mistakes across the whole payload.
A Flashman workflow
Use the JSON formatter to inspect the payload, the diff tool to isolate unexpected keys, the case converter to check naming transformations, and the YAML to JSON converter when schemas live in OpenAPI files.
End the fix with a small fixture table: accepted payload, rejected payload, expected error, and the schema object that owns the additionalProperties decision.