Validating API requests with JSON Schema
Short answer: Every API endpoint that accepts JSON, from a booking form's backend to a partner integration or your mobile app, should check the request body against an explicit description of what is allowed before doing anything with it. JSON Schema is a widely used standard for that description: which fields exist, which are required, their types, formats, lengths and ranges, and whether unknown fields are rejected. Validate on the server, reject bad requests with a clear error, set additionalProperties to false where it makes sense, and keep the schema next to your API documentation so they cannot drift apart.
Why ad-hoc checks fall short
Most APIs start with a few if-statements: is the email present, is the quantity a number. Over time endpoints grow, fields are added, and checks are forgotten. The consequences are familiar:
- Orders with negative quantities or a delivery date before the order date.
- A database error, or a confusing 500 response, because a field arrived as a string instead of a number.
- Extra fields quietly saved, including ones the client should never set, such as a price, a discount or a role.
- Mobile apps and partners each interpreting the API slightly differently.
OWASP's Input Validation Cheat Sheet recommends defining rules for each field: exact membership for fixed choices, expected type, format and minimum and maximum for numbers and dates, length limits and structure for strings, allowed and required fields for objects, and item counts with validation of every item for arrays. Writing those rules once, in a schema, is far more reliable than scattering them across code.
What JSON Schema gives you
A JSON Schema document describes the shape of valid data. For a booking request, it might say:
- type: object, with properties for customer name, email, party size, date and notes.
- required: name, email, party size and date.
- Types and formats: email as a string in email format, date as a date string, party size as an integer.
- Ranges and lengths: party size between 1 and 12, notes no longer than 500 characters.
- Enumerations: a seating preference limited to "indoor", "outdoor" or "no preference".
Validator libraries exist for almost every language and framework, and many API frameworks can validate requests from a schema automatically.
Close the door on unexpected fields
JSON Schema's documentation on objects explains a default that surprises people: by default, any additional properties are allowed. If your schema lists five fields and a request sends a sixth, it still validates. Setting additionalProperties to false means no additional properties are allowed.
That matters for security. OWASP's Mass Assignment Cheat Sheet describes the problem of frameworks binding request fields straight onto internal objects, with an example of a user object containing an isAdmin field. It notes that block-lists are not enough because a new or overlooked sensitive field remains bindable, and that allowlists are recommended. A schema that rejects unknown fields is one practical allowlist. Pair it with code that copies only intended fields into your database models.
Syntax is not the whole story
A schema checks structure. OWASP's cheat sheet also asks you to validate semantics, whether a value makes sense for the operation, giving the example that a booking needs valid dates and an end date after its start date. It also reminds you to check authorisation separately: a valid account identifier does not mean the caller may access that account.
So after the schema passes, your code still checks business rules: the time slot is available, the product is in stock, the discount code is valid, the user owns the record.
Good error responses
When validation fails, respond with a 400 or 422 status and a body that tells the client exactly which field failed and why, such as "partySize must be between 1 and 12". Keep messages useful for developers but avoid echoing back sensitive input. Return all errors at once where practical, so a form can highlight every problem in one go. Log rejected requests with the endpoint and the failing rule, which quickly shows whether one client or one field causes most of the trouble.
Keep schema and documentation together
If you document your API with OpenAPI, its request body definitions are schemas too. Generate validation from the same definitions, or generate documentation from your schemas, so the docs never describe fields the server rejects or vice versa. Store schemas in your code repository, review changes to them like code, and version them alongside the API.
Rolling it out on an existing API
- Write schemas for your most important endpoints first: orders, payments, account changes.
- Run validation in log-only mode for a week to see what real clients send.
- Fix clients or relax rules where legitimate requests would fail.
- Switch to rejecting invalid requests, endpoint by endpoint.
- Add schemas for new endpoints before they ship.
A worked example
Picture a hypothetical Cardiff venue-hire company whose booking API was used by its website, a mobile app and two event-listing partners. Bad requests occasionally created bookings with zero guests, dates in the past or unexpected fields, and once a partner's request set an internal "confirmed" flag directly.
The developers wrote JSON Schemas for each endpoint with required fields, types, ranges, enumerations and additionalProperties set to false, ran them in log-only mode for a week, contacted the partner sending stray fields, and then enforced validation. Business rules such as availability stay in code after the schema check. Invalid bookings stopped, and partners now get clear 422 errors naming the field to fix.
FAQ
Does validation in the browser make this unnecessary?
No. Browser checks help users, but anyone can call your API directly. The server must validate.
Will strict schemas break older app versions?
They can. Run log-only first and plan changes with your app release schedule.
Is JSON Schema only for JSON APIs?
It is designed for JSON data, but many tools use it to validate configuration files and form data too.
If your API accepts data you didn't expect, or partners keep sending malformed requests, tell us about the endpoints involved.