Catalog › Structural › Schema Validator

Schema Validator

Structural High oracle Predictive

Structural coherence at the boundary of the system. OpenAPI/GraphQL schema validation, Terraform plan, Kubernetes admission validation, SQL parser/type checker — all of these answer: is this a valid instance of the expected shape?

Where a type checker validates internal coherence, schema validators validate boundary coherence: does this API request match the contract? Does this infrastructure definition resolve?

In practice

A schema reading is a rejection at the boundary, naming the exact field and constraint that failed:

Error: invalid_request
  POST /v2/invoices
  body.currency: value "usd" does not match pattern ^[A-Z]{3}$
  body.lines[2].amount: required property "amount" is missing

The same shape, different substrates: a Terraform plan that proposes deleting a production resource, an admission controller refusing a pod spec, a kubectl apply that fails on an unknown field. Each is the boundary saying “this is not a valid instance.”

Reading it well comes down to deciding where the truth lives. When the request and the schema disagree, one of them is wrong, and the validator cannot tell you which. A spike of identical rejections usually means the schema drifted behind its producers, and loosening the constraint without asking is how boundaries lose their meaning. Validate on write and on read both: a shape that was valid at ingestion can be invalid by the time anything consumes it.

Response playbook

When validation fails:

  1. Classify before changing anything. Is the instance wrong, or did the schema fall behind reality? The fix is opposite in each case.
  2. If the instance is wrong, fix the producer. Hand-patching a payload to satisfy the validator leaves the next payload equally broken.
  3. If the schema is behind, version it, do not silently loosen it. Widening a constraint changes the contract for every consumer that reads through it.
  4. For infrastructure plans, diff before apply. A plan is a preview of production; read the destroy lines first.
  5. Re-run the check after every fix. Boundary validation is cheap enough to run on every attempt.

What it cannot detect

Schema validation cannot detect whether a valid request produces the correct behavioral result. It checks shape, not meaning.

Oracle strength varies significantly by sub-technique. A Terraform plan is a near-perfect oracle of what will be applied — it shows the exact diff the infrastructure will undergo. An OpenAPI schema is a weaker oracle of runtime behavior — the schema can be valid while the implementation violates it. Kubernetes admission control sits in between. The “High” rating above reflects the strong end of this range; for schema-as-document validation, expect closer to medium.

Structural Type Checker Structural Linter Behavioral Contract Tests
Categories: Structural Boundary Assumptions

References

Publications

Tooling