Data Formats & Debugging · Field note
JSON Schema validation: stop guessing what shape an API accepts
Use JSON Schema as a contract, not just a lint check, so payload validation becomes predictable and explainable.
Before you start
Lint or format before comparing data, then check that cleanup did not change the fields, order, or values that matter.
Teams often say a payload is “valid JSON” as if that settled whether the API should accept it. It does not. Syntax validity and contract validity are two different layers.
JSON Schema is valuable because it turns an implied payload shape into an explicit one. That is exactly the sort of clarity a practical tool site should lean into.
In brief
What it is: JSON Schema is a vocabulary for describing the structure, constraints, and semantics of JSON data so instances can be validated against a contract.
Why it matters: It catches shape and rule mistakes earlier than endpoint-by-endpoint trial and error.
Watch for: A document can be perfectly valid JSON and still fail the schema because required fields, types, enum values, or nested constraints do not match.
Linting and validation are not the same job
A linter or syntax validator answers “can this JSON be parsed?” A schema validator answers “does this parsed JSON satisfy the contract we expect?” Treating those as the same task leads to slow debugging, because a syntax-clean payload can still be structurally wrong in ten different ways.
Once that distinction is clear, the tooling story gets much better: format first if needed, then validate against the schema, then fix the failing path instead of guessing.
The real value is error location
Schema validation becomes useful when it points to the exact path and rule that failed. “Property is required” is only mildly helpful. “/customer/address/postcode is required and missing” is operationally useful. That is why a good schema validator should show the failing instance path and the schema keyword together.
For teams building internal APIs, this quickly becomes a quality-of-life improvement. It keeps payload shape discussions grounded.
- Syntax valid is not contract valid.
- Path-aware errors are more useful than generic rejection.
- Draft/version awareness matters because schema vocabularies evolve.
See it in a small example
Notice: This schema says more than “must be JSON.” It says the payload must be an object with an email field shaped like an email string.
{
"type": "object",
"required": ["email"],
"properties": {
"email": { "type": "string", "format": "email" }
}
}
What to verify
- Validate syntax first if the document does not even parse.
- Then validate the parsed document against the intended schema draft.
- Read the failing instance path before changing unrelated fields.
Common questions
Does JSON Schema replace API docs?
It complements them by making structural rules explicit and machine-checkable.
Can one schema guarantee business correctness?
No. It helps with structure and constraints, but application logic still matters.