JSON is the lingua franca of web APIs, but without validation, malformed data slips through and causes hard-to-debug errors downstream. JSON Schema provides a declarative way to define the expected structure of JSON data — required fields, data types, value constraints, and nested object shapes — and validate incoming data against that definition before processing it.
What JSON Schema Does
A JSON Schema is itself a JSON document that describes the structure of other JSON documents. It specifies which properties are required, what types they must be, what values are acceptable, and how nested objects and arrays should be structured. Think of it as a contract between data producers and consumers: the schema defines what valid data looks like, and any deviation is caught immediately.
Basic Schema Building Blocks
The fundamental keywords are `type` (string, number, boolean, object, array, null), `properties` (for object keys), `required` (for mandatory fields), `items` (for array element validation), and `enum` (for allowed values). Combining these keywords lets you express most validation requirements. For example, a user object might require a `name` string, an `email` string matching a regex pattern, and an `age` integer between 0 and 150.
Schema Composition
Complex schemas are built by composing simpler ones using `$ref` for reusable definitions, `allOf` for combining schemas, `oneOf` for mutually exclusive alternatives, and `anyOf` for flexible matching. This composability lets you define a base schema and extend it for different contexts without duplicating validation logic.
Validation in Practice
Most languages have mature JSON Schema validation libraries: `ajv` for JavaScript, `jsonschema` for Python, and `everit-org/json-schema` for Java. Validation typically takes microseconds per document, making it practical for request validation in API endpoints. The performance cost is negligible compared to the debugging time saved by catching malformed data at the boundary.
JSON Schema as Documentation
A well-written schema serves double duty as API documentation. Tools like Swagger/OpenAPI use JSON Schema to generate interactive API docs, client SDKs, and mock servers. When your schema is the single source of truth for both validation and documentation, they can never drift out of sync.
Regex Patterns in JSON Schema
JSON Schema supports the `pattern` keyword for validating string values against regex patterns. This is where regex knowledge becomes essential for schema authors. A date format, email address, or custom identifier pattern embedded in your schema catches invalid strings before they reach your business logic. RegExpress helps you develop and test these patterns before embedding them in your schemas.