The architecture of validators as gates that produce pass/fail outcomes on inputs — recognising that validator design (multi-layer coverage from schema through semantic and policy, placement at appropriate stages, actionable failure messages, evolution as the system evolves, and false-positive discipline) is what determines whether validators function as trusted gates or as ceremonial checks the team learns to bypass.
This page is about validators as machine-applied gates. A validator takes input — a JSON document, a code change, a configuration file, an HTTP request, a deployment manifest — and produces a binary outcome: pass (the input meets the validator's criteria) or fail (the input doesn't, with a specific reason). The discipline of human-applied review instruments — the architecture-review checklist, the deployment-readiness checklist, the security-review checklist — lives in checklists/. Checklists are applied by humans during deliberate review work; validators are applied by machines as automatic gates. Same family (gating instruments), different operational mode.
A primitive validator is what gets added when "we keep getting bad input": a single regex check, a hardcoded length validation, a presence-of-required-field check. It catches the specific cases that motivated it and misses everything else. Worse, primitive validators frequently produce unhelpful failure messages: "Validation failed" or "Invalid input" — telling the consumer that something is wrong but not what or how to fix it. The result is validators that exist but don't help: consumers learn to rely on guess-and-check rather than on the validator's signal, the validator becomes ceremonial, and eventually it gets bypassed for "edge cases" that proliferate.
A production validator architecture treats validation as a layered, multi-stage discipline. Schema validation — does the input have the expected structure (required fields present, types correct, format constraints met)? Semantic validation — does the input make sense given the system's domain rules (this field's value is in the allowed range, this combination of fields is consistent, this reference resolves to a real thing)? Policy validation — does the input comply with operational policies (security constraints, regulatory requirements, organisational standards)? Contract validation — at boundaries between systems, does the input match the agreed-upon contract (API specification, message schema, interface definition)? Each layer is independent, each can be implemented and updated separately, and each contributes to the overall coverage.
Beyond layering, validators are placed at appropriate stages: pre-commit (linters, formatters, schema checks before code is shared); CI (semantic checks, contract tests, security scans before merge); deploy (configuration validators, dependency checks before production); runtime (request validation, response validation as production traffic flows). Each stage has different latency budgets and different failure costs. Failed validation is actionable: error messages explain what's wrong, where (file, line, field), and how to fix it. The validator is trusted because it doesn't produce false positives that erode confidence; consumers respect its signal because the signal is reliable.
The architectural shift is not "we have validators." It is: validators are machine-applied gates whose layered coverage, stage placement, message actionability, evolution discipline, and false-positive rate determine whether they function as trusted gates that prevent bad inputs from reaching production or as ceremonial checks the team learns to bypass — and the difference compounds in the incidents that bypassed validation didn't catch.
The most consequential property of a validator is whether its output binds. A validator that produces "warnings" the team can ignore, or "advice" the team can override, or "soft signals" with no enforcement isn't a gate — it's a hint. Hints are useful; gates are different. The architectural distinction is what the validator's output forces: pass means the input proceeds; fail means the input doesn't. Failed validation halts the pipeline, blocks the merge, rejects the request, refuses the deploy. The discipline pays the friction cost (consumers can't ship past a failed validator) and pays the friction back in the bad inputs that don't reach production. A validator whose output can be ignored is a validator the team will eventually ignore — and the failures it was meant to prevent will surface in production rather than at the gate.
Pick the most-used validator in your organisation. What does failure mean — does it block the merge / deploy / request, or does it produce a warning the team can ignore? If the latter, the validator is a hint, not a gate — and the failures it would catch will eventually surface in production.
OWASP Application Security Verification Standard treats validation as gating discipline at framework level. Open Policy Agent (OPA) operationalises policy validation as binding gates with documented override paths.
A validator that conflates layers fails predictably. A validator that checks "the field age is present and is an integer" handles schema validation but misses semantic validation (age = -5 passes schema but is semantically nonsense) and policy validation (age = 200 passes both but violates business policy that ages must be plausible). A validator that mixes all three together becomes complex, slow to evolve, and hard to debug when it fails in unexpected ways. The architectural discipline is layered validation with each layer independent: schema (structure, types, required fields, format constraints) using a schema language (JSON Schema, Protobuf, Pydantic, OpenAPI); semantic (domain rules: ranges, consistency, reference resolution) in code closer to the domain; policy (organisational/regulatory rules) in a policy engine (OPA Rego, Conftest); contract (cross-system agreements) using contract testing (Pact) or schema validation against a published API spec. Each layer can be implemented, evolved, and debugged independently.
Pick a critical input path in your organisation (an API endpoint, a config file, a deployment manifest). What's its schema validator, what's its semantic validator, what's its policy validator? If the answer is "we have one validator that checks everything," the layering is conflated — and changes to any layer require touching all layers.
JSON Schema is the canonical schema language for JSON; OpenAPI extends it for HTTP API contracts; Protobuf provides schema for binary protocols. Open Policy Agent (OPA) operationalises policy validation with a dedicated policy language. Pact operationalises consumer-driven contract testing.
A validator that takes 30 seconds is fine in CI (where many checks run in parallel) and prohibitive at runtime (where it adds latency to every request). A validator that requires production credentials can't run pre-commit (where it would mean every developer has those credentials). A validator that catches data-shape issues belongs at the boundary where the data enters the system, not deep inside business logic. The architectural discipline is stage-appropriate placement: each validator runs at the earliest stage where it has the inputs it needs and where its latency cost is acceptable. Pre-commit: linters, formatters, fast schema checks (sub-second budget, runs on developer's machine). CI: semantic checks, contract tests, security scans (minutes-budget, runs on shared infrastructure). Deploy: configuration validators, dependency checks, infrastructure-as-code policy checks (deploy-window budget). Runtime: request validation, response validation, rate-limit enforcement (sub-millisecond budget, runs in production). Validators at the wrong stage are either too slow (runtime validator with CI-scale work) or too late (runtime validator catching what should have been caught pre-commit).
checklists/deployment): infrastructure policy checks, configuration validators, dependency vulnerability scans.Pick the slowest validator in your CI pipeline. What does it check, and could the same check run pre-commit? If yes, the validator is placed too late — every PR pays the CI latency for a check that could have run on the developer's machine before the PR was opened.
12-Factor App (Factor V: Build, Release, Run) covers the stage separation that validators map to. Conftest operationalises policy validation at deploy time for infrastructure-as-code. OpenAPI and Schemathesis provide runtime validation against published API contracts.
A validator that fails with "Validation failed" tells the consumer that something is wrong without saying what. The consumer's response is to read the source, reverse-engineer what was expected, guess at the fix, and try again. Multiple iterations later, the consumer either gets it right or gives up. The architectural discipline is actionable failure messages: every failed validation produces a message that includes (1) what's wrong — the specific rule that was violated, in language a consumer can understand; (2) where — file path, line number, field name, request element — so the consumer can locate the offending input; (3) how to fix it — the expected format/value/structure, with examples where possible. The discipline pays compound returns: validators with actionable messages are trusted because consumers can act on them; validators with cryptic messages are bypassed because acting on them is too costly.
age to be an integer between 0 and 120, got 'old'" rather than "type error."Pick a recent validation failure in your organisation. Did the failure message tell the consumer (a) what's wrong, (b) where, and (c) how to fix it? If any of those are missing, the consumer paid a discovery cost on top of the fix cost — and the next consumer hitting the same failure pays the same cost again.
Pydantic is a canonical example of actionable validation messages in the Python ecosystem; its error messages include field paths, expected types, and observed values. The principle generalises across validation frameworks: actionable messages are a UX feature that compounds with use.
A schema authored two years ago doesn't necessarily reflect the current system. New fields have been added to the data, new policies have been adopted by the organisation, new constraints have emerged from the domain. A validator that doesn't evolve with the system either rejects valid inputs (false positives, eroding trust) or accepts invalid inputs (false negatives, the failures the validator was supposed to prevent). The architectural discipline is to treat validators as living artefacts: schemas have versions, evolution paths, and migration strategies; semantic rules are reviewed when domain rules change; policies are updated as organisational standards evolve; contracts are renegotiated when consumer-producer agreements change. The validator's evolution discipline matches the system's evolution rate — fast-evolving systems need validators that can be updated without ceremony; stable systems can have more deliberate validator evolution.
Pick a validator your organisation has used for over a year. When was it last revised, and what motivated the revision? If the answer is "we don't track that — it's been the same since it was written," the validator is operating on the assumption that the system hasn't changed. Either it's accepting input it shouldn't or rejecting input it should accept; in either case, the cost is being paid.
The schema-evolution discipline is treated in Protobuf — Protocol Buffers (with explicit field-numbering and reserved-field rules to support evolution), JSON Schema (with $id versioning), and OpenAPI (with API versioning patterns). The operational discipline transfers across schema languages.
The most insidious validator failure mode is the false positive: the validator rejects an input that's actually valid. A few false positives are tolerable; a steady rate of false positives erodes trust until consumers stop respecting the validator's output. They learn to override on every failure (because failures are usually false positives anyway), they bypass the validator for "exceptional cases" (which proliferate), or they reroute around the validator entirely. By the time a real defect hits the validator, the team's response is to override that too. The architectural discipline is to treat false positives as defects in the validator: every false positive triggers investigation (was the rule too strict? was the input class not anticipated? is the validator buggy?) and revision. The goal is a validator with a near-zero false-positive rate, even at the cost of accepting some false negatives — because trust is the resource the validator depends on, and false positives consume it faster than false negatives reveal themselves.
Pick the most-overridden validator in your organisation. What's its false-positive rate — how often do overrides indicate the validation was wrong rather than that the team chose to ship despite a real flag? If false positives are common and uninvestigated, the validator's trust is being eroded — and the team's habit of overriding on this validator transfers to others.
The false-positive discipline transfers from broader software-defect discipline; the same principle applies to alerting in observability (false-positive alerts erode trust) and to test suites (flaky tests are worse than failing tests because they erode trust in the suite). The architectural framing of "trust is the resource validators depend on" is treated implicitly in Continuous Delivery — Humble & Farley for build-pipeline gates.
The diagram below shows the canonical placement of validators across the development-to-runtime pipeline: pre-commit (fast schema checks, linters, formatters), CI (semantic checks, contract tests, security scans), deploy (configuration validators, infrastructure policy checks), runtime (request/response validation, rate-limit enforcement). Each stage has its own latency budget and failure cost; validators are placed at the earliest stage where their inputs are available and their cost is acceptable.
Failures produce warnings the team can ignore. The team learns to ignore them. Bad inputs reach production despite the validator existing.
Binding gates: pass allows progress, fail halts. Override paths exist for documented exceptional cases with audit trail, but aren't the default mode. Patterns of overrides trigger calibration review.
Hand-written if-statements check structure, business rules, and policy together. Changes to any layer require touching all layers. Failures in the conflated validator are hard to debug.
Layered validation: schema in a schema language (JSON Schema, Protobuf, Pydantic); semantic in domain code; policy in a policy engine (OPA); contract at boundaries (Pact, OpenAPI). Each layer independent.
A schema check that should run pre-commit runs in CI (slow feedback). A request validator that should run at runtime runs at startup (catches startup-time inputs but not request-time). The placement doesn't match the stage's properties.
Stage-appropriate placement: each validator runs at the earliest stage where its inputs are available and its latency is acceptable. Pre-commit fast and developer-machine-runnable; CI minutes-scale; runtime sub-millisecond.
The validator rejects input but doesn't say what's wrong, where, or how to fix. The consumer guesses, iterates, eventually succeeds or gives up.
Actionable messages with three elements: what (the specific rule violated), where (file/line/field/request identifier), how to fix (expected format/value, with examples). For complex rules, link to documentation.
The validator was written two years ago. The system has evolved. The validator now either rejects valid inputs (eroding trust) or accepts invalid ones (failing its purpose).
Validators as living artefacts: versioned schemas, documented owners and review cadences, evolution paths for breaking changes, testing against representative input corpora before deploy.
Override paths exist for exceptional cases with audit trail; not the default. Patterns of overrides trigger calibration review.
Schema in a schema language; semantic in domain code; policy in a policy engine; contract at boundaries. Layers can be evolved separately.
JSON Schema, Protobuf, Pydantic, OpenAPI — auto-generated validators, IDE support, documentation generation. Not hand-written if-statements.
OPA, Conftest, equivalent. Policies authored by security/compliance teams; reviewed and updated separately from application code.
Both sides of the boundary validate against the same contract (OpenAPI spec, Pact contract, Protobuf schema). The contract is shared, versioned, and tested.
Pre-commit fast and local; CI minutes-scale; deploy at the deploy gate; runtime sub-millisecond. Misplaced validators are too slow or too late.
The rule violated (in consumer-friendly language), location (file/line/field), expected format/value with examples. Links to documentation for complex rules.
Deprecation period, dual-validation phase, removal of old. Consumers have time to migrate. The validator's evolution discipline matches the system's.
Recorded production traffic, golden examples, edge-case collections. Catches regressions where a schema update rejects previously-valid input.
Each override recorded with reason; patterns analysed; high false-positive rates trigger revision. Trust is the resource validators depend on; false positives consume it faster than false negatives reveal themselves.