2026-07-03 · 6 min read · Rahul Chitturi
- json
- ci
- debugging
Schema validation failures in CI often look like a single red line: a required field is missing, a type changed, or an enum no longer accepts the value produced by a service. The useful clue is rarely the final assertion alone. It is the difference between the payload your test expected and the payload the build actually generated.
Before changing the schema, format the failing JSON and compare it with a known-good sample. That keeps the investigation about contracts instead of guesswork.
Separate syntax from contract errors
Start by confirming the payload is valid JSON. A trailing comma, unescaped newline, or copied log prefix can cause a parser error before schema rules even run. Once syntax is clean, read the validation message against the formatted object path.
- Required field errors usually indicate a producer or fixture drifted
- Type errors can come from stringified numbers, booleans, or nulls
- Enum errors often mean staging and production configs disagree
- Additional property errors may reveal a new API version in the wrong test path
Compare environments intentionally
CI failures that do not reproduce locally usually point to environment-specific fixtures, feature flags, generated timestamps, or service defaults. Diff a local payload against the CI artifact after formatting both with the same indentation. Ignore volatile fields first, then inspect the remaining structural changes.
Keep samples safe
Validation payloads can include customer IDs, emails, access tokens, or internal URLs. Redact sensitive values before sharing them in tickets. If the structure is what matters, replace values with realistic placeholders while preserving object shape and field names.
A Flashman workflow
Use the JSON formatter to make the failing payload readable, the diff tool to compare it with a passing fixture, and the YAML to JSON converter when CI config stores examples in YAML. Because the tools run in the browser, private samples can stay on your machine during triage.