What JSON Schema actually solves
Bottom line: Schema governs structure and types, not business meaning. It stops missing fields, wrong types and out-of-range enums, while rules like amount over zero stay in code.
Bottom line: let JSON Schema enforce structure, types, ranges and formats, while cross-field rules, business invariants and external state stay in code; adopt it for public APIs and shared payloads, not for a five-field internal service.
It answers "is this data shaped correctly", not "does this data make sense".
What it does well
Structural completeness. Which fields must exist, whether extras are allowed (required, additionalProperties).
Types. port as number or string, tags as array or scalar. This alone removes a lot of defensive code in multi-language systems.
Ranges. enum, minimum/maximum, string and array length.
Formats. format for dates, email, URIs and UUIDs, with validators that enforce them.
Nesting. Every level of objects and arrays gets its own constraints, and errors carry a precise path.
Documentation. The Schema is the contract. Change a field and the diff shows the blast radius. It also generates types and forms, so one definition feeds several consumers.
What it cannot do
Cross-field dependencies. "End must be after start" can be expressed with if/then/else, but the result is longer and harder to read than three lines of code.
Business invariants. "Stock cannot go negative" depends on external state. Schema sees one document.
Semantics. price: -100 satisfies {"type": "number"} perfectly. Whether it is a legal price is outside the Schema's knowledge.
A workable division
| Layer | Owner |
|---|---|
| Syntax: is it valid JSON | Parser |
| Structure: fields, types, ranges, formats | JSON Schema |
| Semantics: cross-field, business rules, external state | Application code |
| Safety: size, depth, rate | Gateway / middleware |
Collapse these into one place and the Schema grows to hundreds of lines with five levels of if/then. At that point people route around it.
When it pays off
- Public APIs with unknown consumers
- Multiple services reading the same payload
- Config-driven systems where typos must fail fast
- Generating types or forms from the contract
For a small internal service with five fields and one frontend, hand-written checks are faster to maintain. Introducing Schema there is negative work.
FAQ
How do I decide whether to adopt JSON Schema?
Weigh public consumers, multiple services reading the same payload, and the need to generate types or forms. For a small internal service with five fields and one frontend, hand-written checks are faster to maintain.
Why should cross-field rules stay in code?
"End must be after start" can be squeezed into if/then/else, but the result is longer and harder to read than a few lines of code. Schema cannot see external state either.
Should Schema validate payload size and nesting depth?
No. Schema describes structure, not size or depth; those limits belong in a gateway or middleware layer.