JSON Schema is a vocabulary for describing JSON data: what fields exist, what types they are, which are required, what patterns and ranges and constraints apply. It sounds humble. It is the most important and most overlooked specification in the API world.
Here is the structural fact people miss: an OpenAPI document is mostly JSON Schema. The paths and operations are a wrapper; the substance — every request body, every response, every parameter — is schema. So the schema is more fundamental than the OpenAPI that contains it. Get it right and everything above it is sound. Get it wrong and the errors propagate up through documentation, SDKs, validation, tests and every consumer’s data model.
The practical payoff is drift prevention. When teams do not speak schema, the same customer object exists in five slightly different shapes across five services, nobody notices until an integration breaks, and the fix is archaeology. Shared, versioned, reusable schema is what stops that. Schema work is the most stabilizing API work available, and it is almost always underinvested in relative to building more endpoints.
A useful division of labor to hold onto: schema defines storage, API defines access. What the data is should be described once and reused; how it is reached is a separate design question.
