Writing a schema is the easy part. Actually enforcing it against real payloads, on every deploy, is where most teams stall out, mostly because they haven't looked at what's already free and mature enough to wire into an existing pipeline this week. Here are seven that cover the whole surface, from a raw JSON payload to a full async event contract.
1. JSON Schema
JSON Schema is the base specification most of the other tools on this list build on top of. It gives you a vocabulary for describing exactly what a JSON payload should look like: required fields, types, formats, nested object shapes, and constraints like string patterns or numeric ranges. If you validate nothing else on this list, validating raw payloads against a JSON Schema document is the highest-leverage starting point, because almost every other tool here either consumes or exports it.
It's also the tool with the shortest path from zero to useful. A rough schema covering just the fields a downstream process actually reads is enough to start catching real drift, and you can flesh out the stricter constraints, format validation, enum restrictions, nested object rules, over time as the integration matures rather than trying to model everything on day one.
2. OpenAPI
For HTTP APIs specifically, OpenAPI documents the route, the request shape, the response shape, and the status codes in one file that's both human-readable and machine-validatable. Tooling built on top of an OpenAPI spec can generate request validators, mock servers, and client SDKs from the same source of truth, which keeps the documentation and the enforcement from drifting apart the way a hand-written wiki page inevitably does.
The mock server generation is easy to undervalue until you've used it. A consumer team can build and test their integration against a mock generated straight from the spec before the provider's real endpoint even exists, which shortens the feedback loop on both sides during active development instead of waiting for a shared environment to be ready.
3. AsyncAPI
The event-driven equivalent of OpenAPI. AsyncAPI documents channels, message schemas, and bindings for queues, topics, and streaming platforms, so a team publishing events has somewhere to declare the contract, and a team consuming them has something concrete to validate against instead of reverse-engineering the shape from a sample payload someone pasted into Slack.
This matters more than it might seem for async integrations specifically, because there's no request in flight to reject when something doesn't match. A consumer reading events off a queue days after they were published needs the schema documented and versioned somewhere durable, not inferred from whatever the last few messages happened to look like.
4. Pact
Pact is the standard tool for consumer-driven contract testing: the consumer writes down exactly what it expects from a call, and the provider verifies that expectation against its real running service in CI. It catches the specific failure mode schema validation alone misses, a change that's technically valid JSON but still breaks the actual behavior a consumer depends on.
It's the tool most worth introducing once a specific consumer-provider relationship has already broken more than once, rather than something to roll out everywhere immediately. The setup requires both teams to coordinate around a shared broker, which pays off fastest on the relationship that's actually causing pain today.
5. Ajv
For teams working in JavaScript or TypeScript, Ajv is a fast, widely used JSON Schema validator that can run directly in a request pipeline, rejecting malformed payloads before they ever reach business logic. It compiles schemas ahead of time for speed, which matters when validation needs to run on every request without adding noticeable latency.
Running validation at the edge of a service, right where a payload first arrives, means a malformed request never reaches the parts of the codebase that assume a valid shape. That's a much easier failure to debug than a null pointer three function calls deep, triggered by a payload that should have been rejected on arrival.
6. Spectral
A linter for OpenAPI and AsyncAPI documents themselves, catching structural problems in the contract before anyone tries to validate real traffic against it: missing descriptions, inconsistent naming conventions, or response codes that don't match the rest of the spec. Running a linter on the contract is a cheap gate that catches sloppy schema authoring before it becomes someone else's confusing integration bug.
Wiring this into the same pull request check that reviews code changes means a poorly structured contract gets flagged the moment it's proposed, rather than after a consumer team has already started building against a spec with gaps or inconsistencies baked into it.
7. Semantic versioning
Not a tool exactly, but semantic versioning is the shared vocabulary every one of the tools above needs to be genuinely useful. A schema validator can tell you a payload is invalid, but only a versioning convention tells you whether the change that caused it was supposed to be backward-compatible in the first place. Without it, every validation failure requires a conversation to figure out whether the break was intentional.
Applying it consistently means the version number on the schema itself, not the API route, is what actually changes when the shape changes. Once every team agrees a major bump always means "check before you upgrade," a validation failure stops being a surprise and starts being an expected signal that a migration is due.
Picking a starting point
You don't need all seven running by Friday. The highest-leverage combination for a team starting from nothing is usually JSON Schema or OpenAPI to define the shape, a validator like Ajv wired into the request path to enforce it at runtime, and Pact if there's a specific consumer relationship that's broken more than once. Add AsyncAPI once an event-driven integration point actually exists, not before.
The common thread across all of these is that none of them replace a team actually deciding what the contract should be. They enforce a decision once it's made, they don't make it for you, which is why the review process around contract changes matters as much as the tooling. 137Foundry's data integration team treats the tool selection as the smaller half of the problem, with the review and versioning discipline around it doing most of the actual work.
For a deeper look at how these pieces fit into a full contract-first workflow, including how to handle a breaking change once one is unavoidable, see 137Foundry's guide to designing a data contract that survives API changes. None of the tools above matter much without the deprecation and review process that guide walks through. 137Foundry has set up versions of this stack for clients integrating anywhere from two services to a dozen.
One last practical note on adoption: introduce these tools in the order a team will actually feel the benefit, not the order a diagram might suggest. Schema validation pays off within days of the first integration point it covers. Contract testing pays off the first time a provider change would otherwise have broken a consumer silently. Linting and versioning conventions pay off more slowly, as a codebase and its contracts accumulate, but they're what keeps the first two from degrading once several teams are maintaining schemas independently.
All seven of these are free to start with, which removes the usual budget conversation from the decision entirely. The remaining cost is time, mostly spent agreeing on conventions with whichever other team is on the other end of an integration, and that conversation tends to go faster once there's a specific, recent incident everyone remembers to point back to.
Top comments (0)