JSON Schema Validation

JSON Schema is a vocabulary for annotating and validating JSON documents. It allows you to describe the expected structure, data types, constraints, and documentation of your JSON data in a machine-readable format. Think of it as a type system for JSON — it defines what valid data looks like so you can automatically reject malformed input.

Basic schema structure:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

This schema declares that valid data must be an object with a required name string (at least 1 character), an optional non-negative integer age, and a required email string.

Key validation keywords:

• type: Restricts the JSON type (string, number, integer, boolean, null, object, array)
• properties: Defines schemas for object properties
• required: Lists mandatory property names
• items: Schema for array elements
• enum: Restricts value to a fixed set
• pattern: Regex pattern for strings
• minimum/maximum: Numeric range constraints
• minLength/maxLength: String length constraints
• oneOf/anyOf/allOf: Compose schemas with boolean logic

Why JSON Schema matters:

Without schema validation, your application must manually check every field, type, and constraint of incoming JSON data. This leads to scattered validation logic, inconsistent error messages, and missed edge cases. JSON Schema centralizes validation into a single, declarative definition that can be shared between frontend and backend, used to generate documentation, and tested independently.

Common mistakes developers make:

A frequent mistake is writing schemas that are too permissive — using "type": "object" without defining properties validates that the input is an object but does not check its contents. Another mistake is forgetting "additionalProperties": false when you want to reject unexpected fields. Developers also sometimes confuse required (which is an array on the object schema) with making individual properties mandatory — putting "required": true inside a property definition is invalid.

Best practices:

Start using JSON Schema at the API boundary to validate all incoming requests. Use the latest draft (2020-12) for new projects. Generate documentation and TypeScript types from your schemas to keep them in sync. Use a well-maintained validator library like Ajv (JavaScript), jsonschema (Python), or everit-org/json-schema (Java). Write schema tests to verify that both valid and invalid examples behave as expected.