2026-09-08 · 6 min read · Rahul Chitturi
- json-schema
- api
- debugging
A JSON document can satisfy every visible field rule and still fail a composed schema. oneOf requires exactly one matching branch, while anyOf requires one or more, so overlapping object shapes can make oneOf reject data that looks valid.
Generated forms and API clients can hide the overlap by selecting a branch from a discriminator even though the server validates the complete schema independently.
Count matches instead of guessing
Validate the same harmless fixture against each branch separately and record every success and error. Then apply the enclosing oneOf, anyOf, or allOf rule using the exact validator, draft, and options from production.
- Check required fields and additionalProperties in every branch
- Look for broad types or empty schemas that match unexpectedly
- Treat annotations such as defaults as different from validation
- Confirm whether a discriminator is implemented by the validator
Make variants structurally distinct
Use a required tag with a const value when the domain has explicit variants, and keep shared constraints outside the alternatives. Do not depend on property order or error ordering to choose a branch.
If several branches are intentionally valid, use anyOf and define how application code chooses behavior. If exactly one must be valid, add constraints that make overlap impossible and test future variants against old fixtures.
A Flashman workflow
Use the JSON formatter to normalize schemas and fixtures, diff to compare branches, case converter to spot discriminator naming drift, and regex tester for pattern constraints. Keep confidential payloads out of shared reports.
Test zero, one, and multiple matching branches, missing tags, unknown properties, nested composition, null values, format handling, draft upgrades, and each generated client.