Separate Structural and Semantic Validation

  • Status: accepted

  • Date: 2026-07-26

Context and Problem Statement

JSON Schema expresses document structure and many conditional constraints, but some invariants compare values, calculate aggregates, or span collections. Encoding one invariant in both JSON Schema and Python creates unreachable code and divergent error behavior.

Decision Drivers

  • One authoritative owner per invariant

  • Standard validation before custom code

  • Precise JSON paths

  • Reviewable cross-field logic

Considered Options

  • Put every rule in Python

  • Duplicate important rules in both layers

  • Use JSON Schema for structural rules and Python for irreducible relationships

Decision Outcome

JSON Schema owns types, required fields, closed objects, enum constraints, collection cardinality, uniqueness, and expressible conditionals. Python semantic validators run only after structural success and own relational or calculated invariants that are not cleanly expressed by the schema.

Consequences

  • Removing a Python check requires a regression test proving schema ownership.

  • Semantic validators may rely on structurally valid input.

  • Published schema rules remain immutable.

  • Error classes distinguish structural and semantic failures.