JSON Schema Validation: A Practical Guide

What Is JSON Schema?

JSON Schema is a vocabulary for annotating and validating JSON documents. It defines the expected structure, types, constraints, and relationships of data in a JSON object. Think of it as a contract that incoming or outgoing JSON data must fulfill.

Using JSON Schema catches malformed data early, provides automatic documentation, enables code generation, and improves API reliability. It is supported by validators in every major programming language and is used extensively in OpenAPI (Swagger) specifications.

Basic Schema Structure

A JSON Schema is itself a JSON document. The simplest schema specifies a type. A schema requiring a string looks like: {“type”: “string”}. A schema requiring an integer: {“type”: “integer”}.

For objects, you define properties and which ones are required. A user schema might specify that the object must have a “name” property (string), an “email” property (string with format email), and an “age” property (integer with a minimum of 0). The “required” array lists which properties must be present.

Additional keywords add constraints. “minLength” and “maxLength” limit string length. “minimum” and “maximum” constrain numbers. “pattern” enforces regular expression matching. “enum” restricts values to a predefined list.

Common Validation Keywords

Type validation: The “type” keyword accepts string, number, integer, boolean, array, object, or null. You can allow multiple types with an array: {“type”: [“string”, “null”]} permits either a string or null.

String constraints: “minLength”, “maxLength”, and “pattern” validate string content. “format” provides semantic validation for common patterns like email, date-time, uri, and uuid, though format validation is optional in some implementations.

Number constraints: “minimum”, “maximum”, “exclusiveMinimum”, “exclusiveMaximum”, and “multipleOf” constrain numeric values. A price field might use {“type”: “number”, “minimum”: 0, “multipleOf”: 0.01}.

Array constraints: “items” defines the schema for array elements. “minItems” and “maxItems” control array length. “uniqueItems” ensures no duplicates.

Object constraints: “properties” defines property schemas. “required” lists mandatory properties. “additionalProperties” controls whether extra properties are allowed (useful for strict validation).

Composing Complex Schemas

JSON Schema supports composition through “allOf” (must match all schemas), “anyOf” (must match at least one), “oneOf” (must match exactly one), and “not” (must not match). These operators enable complex validation logic without repetition.

The “$ref” keyword references another schema by URI, enabling modular, reusable schema definitions. A common pattern is defining shared types (address, phone number, monetary amount) in separate files and referencing them throughout your API schemas.

Conditional logic with “if”, “then”, and “else” keywords allows schemas that adapt based on data content. For example, if a “country” field equals “US”, then a “state” field must match a US state code pattern.

Using JSON Schema in Practice

Validation libraries exist for every major language: ajv for JavaScript, jsonschema for Python, justify for Java, and many others. These libraries validate data against a schema and return detailed error messages identifying exactly which constraint failed and where.

In API development, JSON Schema powers request validation middleware, response verification in tests, and automatic documentation generation through OpenAPI. Many API gateways validate requests against schemas before they reach your application code.

Use the JSON tools on CalcHub to format and validate JSON, or explore our developer tools for schema building and API utilities.

Validate JSON data with CalcHub’s developer tools.