JSON Schema Validation: Catching Bad Payloads Before They Reach Production

How schema validation stops malformed payloads at the edge of a system, which keywords earn their place, and where validation belongs in a request path.

What JSON Schema Validation Actually Does

JSON Schema is a specification for describing the structure and constraints of JSON data. When you validate a payload against a schema, you are checking that the incoming data conforms to the declared rules — the types of each field, which properties are required, the format of strings, the range of numbers, and so on. This is not a fuzzy check. A value that fails validation is rejected, and a value that passes meets the declared contract.

The specification is maintained by the JSON Schema organization and has been stable for years. The most widely used version is Draft 2020-12, though earlier drafts such as 2019-09 and draft-07 remain in use. The differences between drafts are small and affect only a few keywords. If you are unsure which draft your tool supports, check the documentation — the core validation rules are consistent across versions.

Validation happens before your application logic processes the data. This means you catch malformed payloads early, at the boundary of your system, rather than discovering errors deep inside your business logic where they are harder to trace.

The Structure of a Schema

A JSON Schema is itself a JSON document. It declares a type at the top level — typically object for payloads — and then defines the rules for each property.

Here is a minimal example for a user record:

{ "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "age": { "type": "integer", "minimum": 0 } }, "required": ["id", "name"] }

The properties keyword lists each field with its own rules. The required array specifies which fields must be present. If email is missing from the payload, the validation passes because it is not required. If id is missing, the payload is rejected.

Each property can have multiple constraints. A string can have minLength, maxLength, pattern, and format. A number can have minimum, maximum, exclusiveMinimum, exclusiveMaximum, and multipleOf. These are not optional decorations — they are enforced during validation.

Common Mistakes in Schema Design

The most frequent error is using type incorrectly. In JSON, type is a keyword, not a property of the data. It declares the expected type of the value. A common mistake is writing "id": { "type": "string" } when the actual data has integer IDs, which causes a validation failure even though the value is present and correct.

Another common mistake is forgetting that required only checks for the presence of a key, not for non-null values. A key with a null value passes the required check. If you need to reject null values, add "not": { "type": "null" } to the property definition.

Arrays are often misunderstood. The items keyword defines the schema for each element in an array. If you write "tags": { "type": "array", "items": { "type": "string" } }, every element must be a string. If any element is a number, the validation fails. Older drafts also allowed a tuple form, where items took an array of schemas positionally; check which form your validator expects before relying on it.

One more: additionalProperties defaults to true, meaning extra keys in an object are allowed. If you want to reject unknown keys, set additionalProperties to false. This is useful for strict APIs where the contract is explicit.

Validating in Practice

Validation can happen at any layer. In a backend service, you might validate incoming requests before they reach your controllers. In a frontend application, you might validate user input before sending it to the API. The choice depends on where you want to catch errors.

Most programming languages have libraries for JSON Schema validation. The libraries differ in performance and feature support, but the validation rules are the same. If you are using a library that supports Draft 2020-12, you can use the full set of keywords. If it only supports an older draft, check which keywords are available.

For teams that work with payloads frequently, having a tool that can validate against a schema without writing code is useful. JSONForge provides a JSON Schema validator that accepts a schema and a payload and reports whether they match. It also generates schemas from sample data, which is helpful when you need to create a schema quickly from an existing payload.

When you validate, pay attention to the error messages. A good validator reports which field failed and why. If the message is unclear, check the schema definition — the error is usually in the schema, not in the data.

When Validation Is Not Enough

Validation checks the structure of the data, not its semantic correctness. A payload can pass validation and still be semantically wrong. For example, a status field might be a valid string, but the value "active" might be the only valid value. Validation does not catch this unless you use enum in the schema.

Similarly, validation does not check business rules. A price field might be a valid number, but the business rule might require it to be greater than zero. You can express this in the schema with "minimum": 0, but some rules are too complex for the schema and must be checked in code.

The point is that validation is a layer, not a destination. It catches structural errors early, but it does not replace all other checks. Use it where it adds value, and supplement it with code-level checks where needed.

Tool mentioned: JSONForge