2026-07-07 · 6 min read · Rahul Chitturi
- json
- schema
- ci
A JSON schema failure in CI usually means two systems disagree about a contract. The payload may still be valid JSON, but a required field changed, an enum gained a value, or a generated fixture no longer matches the API version under test.
Before relaxing the schema, treat the failure as contract drift. Compare the payload, schema, fixture source, and client generation step so the team fixes the boundary that actually moved.
Start with the exact validation error
Schema validators often report a path, keyword, and expected type. Copy those details before rerunning a noisy test job. A failure at /items/0/status tells a different story than a root-level additionalProperties error.
- Pretty-print the failing payload before scanning nested fields
- Check required, enum, format, and additionalProperties errors separately
- Confirm the schema file comes from the same package version as the API
- Look for generated fixtures that were committed before a contract update
Separate syntax, shape, and version problems
Valid JSON syntax only proves the parser can read the payload. Schema validation proves the shape matches a contract. Version checks prove the contract is the right one. CI failures are easier to triage when those three questions are answered in order.
If only CI fails, compare environment-specific fixtures, feature flags, and cached generated clients. Local tests may pass because they use a stale schema or a smaller sample response.
Review contract changes like code changes
Diff schema files and example payloads side by side. A new optional field may be safe for readers, while a removed required field can break writers. Document whether the change is backward compatible before merging regenerated clients.
- Add explicit fixtures for newly required fields
- Keep enum additions visible in changelogs
- Avoid masking validation errors with broad any types
- Record the API version or commit SHA used by generated clients
A Flashman workflow
Use the JSON formatter to inspect the failing payload, the diff tool to compare old and new schemas, and the YAML to JSON converter when OpenAPI fragments arrive as YAML. Convert timestamps if fixture generation depends on release windows.
Keep customer data local while debugging. Replace IDs, emails, and tokens with synthetic values before sharing a minimized payload in an issue or pull request.