A schema is only useful if it actually catches bad payloads before they reach your handler. Most teams write the schema, then forget it during local development, or only enforce it in CI on a handful of fixtures. That gap is where the 2 a.m. incident starts. This walkthrough is about the boring, repeatable discipline of validating JSON at the boundary — in your editor, in a pre-commit hook, and in a staging smoke test — using a schema as the single source of truth.
I'll focus on the practical workflow: where validation belongs, what to do when a payload is "almost right," and how to keep the schema from rotting as the service evolves. The example payload is a customer order, because it has the usual suspects — optional fields, nested objects, arrays, and one enum that someone will eventually forget to update.
Why Boundary Validation Is a Different Problem From Unit Tests
A unit test with five hand-written fixtures tells you your code parses the happy path. It does not tell you what happens when the upstream system sends customer.country as null because their form crashed, or when a new required field ships and the old client still hits your endpoint.
Schema validation lives at a different layer than unit tests. It asks: given any string that looks like JSON, is this something I'm willing to process? That question gets asked three places:
