flashman
← All posts

JSON Schema if, then, and else debugging

Debug JSON Schema conditional validation by tracing if, then, and else evaluation, missing properties, branch annotations, dialect support, and fixtures.

2026-09-26 · 6 min read · Rahul Chitturi

  • json-schema
  • validation
  • debugging

JSON Schema conditionals apply then when an if subschema succeeds and else when it fails. The if result does not itself make the instance valid or invalid, which can make an apparently obvious rule accept incomplete data.

The most common surprise is that properties only evaluates fields that exist. A condition checking a property value can pass when that property is absent unless required is part of the condition.

Trace the condition independently

Record the schema dialect, complete instance, enclosing applicators, and validator version. Evaluate if by itself, note its boolean result, and only then inspect the selected branch. Repeat the exercise for referenced or nested conditionals.

  • Add required inside if when presence is part of the test.
  • Keep the condition narrower than either consequence.
  • Do not expect errors from an unselected branch.
  • Check whether branch annotations affect later keywords.

Build a decision table

Create fixtures for the discriminator being absent, null, the expected value, another value, and the wrong type. Add one instance that fails each consequence for a reason unrelated to the condition.

For several cases, nested conditionals can become difficult to audit. Compare a oneOf design with mutually exclusive const values, but verify that exactly one branch matches rather than relying on generated-form behavior.

Compare portable fixtures

Use Flashman's JSON formatter for schemas and instances, YAML/JSON converter for configuration copies, diff for validator output, and regex tester for public pattern constraints.

Test missing fields, nulls, wrong types, overlapping cases, nested objects, $ref boundaries, unevaluated properties, annotation collection, draft changes, validator upgrades, and generated clients.

Try these tools