Skip to content

Semantic Schema Validation

A conformance audit — instantiates Grammar-Guided Structure Recovery

Checks a recovered structure against a versioned semantic schema — not whether it parsed, but whether it means something admissible — and records a version-tagged conformance audit.

Semantic Schema Validation takes a structure that has already parsed cleanly and asks the second, deeper question: does it conform to what the data is supposed to mean? It checks the recovered structure against an external schema that encodes semantics — required fields, type and domain constraints, value ranges, enumerations, referential and cross-field integrity — and, because such contracts evolve, it validates against a specific version and records the outcome as an audit. Its defining move is to separate "did it parse" from "is it admissible," gating on the second: a structure can be flawless syntax and still be meaningless or dangerous, and this is the mechanism that says so against a named, versioned contract rather than against local intuition.

Example

An API gateway receives a JSON request that has already parsed into a clean tree. Semantic Schema Validation checks it against the versioned request schema — say a JSON Schema pinned to draft 2020-12, contract version v2.3: age must be an integer in 0..150, email must match the string format, country must be one of a fixed enum, and if shipping is present then address is required. The payload is syntactically perfect JSON — it parsed without complaint — yet it sets age: -3 and omits address while shipping: true. Both violations sail past the parser and past any node-local check of a single field; both fail the schema.

The validator emits a conformance report: each constraint, pass or fail, tagged with schema version v2.3. That version tag is what makes the result durable — when the schema later changes, what was accepted under which contract remains answerable, and drift between producer and contract becomes visible instead of silent.

How it works

The validator loads the schema for the declared or target version, then walks the recovered structure against it, checking the constraints that syntax cannot express: presence, type, range, enumeration, format, and the cross-field and referential rules that only make sense over the whole structure. Each check is recorded — pass or fail, with the constraint and the location — into a conformance audit stamped with the schema version. Two boundaries define it: unlike a grammar, it judges meaning against an external contract, not what parses; unlike a single lint rule, that contract is a versioned, shared artifact rather than a local well-formedness predicate.

Tuning parameters

  • Version pinning — validate against a fixed schema version (reproducible, but can lag) vs. the latest (current, but a moving target).
  • Strictness — reject unknown fields (closed-world, safe) vs. allow them (open-world, forgiving of additive change).
  • Constraint depth — shallow (types and presence) vs. deep (cross-field, referential, business rules). Deeper catches more but couples the schema to logic that changes faster than the contract.
  • Coercion — attempt to coerce near-miss values (string "3" → integer 3) vs. reject them. Coercion is convenient and hides upstream problems.
  • Audit retention — how long conformance records are kept, and at what granularity.

When it helps, and when it misleads

Its strength is that it catches the large, dangerous class of structures that parse but do not mean anything admissible — the negative age, the dangling reference, the missing-but-required field — the errors most likely to cause silent damage downstream; and the version-tagged audit makes "what conformed to which contract, when" an answerable question. Its failure modes trace to the schema's fidelity. An over-strict schema rejects legitimate new inputs, especially just after a version bump; coercion can paper over genuine upstream errors; and deep business logic smuggled into the schema couples it to rules that churn faster than the contract should. The classic misuse is running it backwards — loosening the schema to admit whatever a producer is already sending, so validation blesses drift instead of catching it — or validating after the data has already been acted on, as a formality. The discipline that keeps it honest is to version the schema deliberately, keep it aligned to real requirements rather than to observed traffic, and validate before the structure is trusted.[1]

How it implements the components

Semantic Schema Validation realizes the versioned-contract and audit components of the archetype — checking recovered meaning against a named schema and recording the result:

  • versioned_rule_record — the schema it validates against is a versioned artifact, and each check is bound to a specific version, so conformance is always relative to a known contract.
  • audit_trace — it emits a per-constraint, version-tagged conformance record (pass/fail with location) that stands as the durable audit of what conformed to which contract.

It does not define what merely parses (the Grammar Rule Set), does not author the atomic node-local checks (individual Linting or Validation Rules), and does not handle the runtime consequence of a forbidden combination (the Invalid Combination Linter).

Notes

Because every conformance result is stamped with the schema version in force, an accepted structure stays auditable against the exact contract it was accepted under. That is what turns validation from a pass/fail gate into a record of drift: when producer and schema diverge over time, the version-tagged audit is what lets someone see when, and against which contract, the divergence began.

References

[1] The distinction this mechanism turns on is the classic well-formed vs. valid split from the XML world: a document is well-formed if it obeys the grammar (it parses), but only valid if it also conforms to a declared schema (DTD, XSD, or in the JSON world a JSON Schema). Parsing gets you the first; semantic schema validation gets you the second. ↩