JSON Schema is a powerful vocabulary that allows you to annotate and validate JSON documents. It provides a clear, human-readable way to describe the structure, constraints, and semantics of your JSON data.

What is JSON Schema?

JSON Schema is a JSON-based format for describing the structure of JSON data. It serves two primary purposes:

• Documentation: Clearly describing what fields exist, what types they are, and what values they can have
• Validation: Checking that incoming JSON data conforms to your expected structure

Think of it as a contract between your API and its consumers. When you share a JSON Schema, clients know exactly what to expect.

Basic Structure

A minimal JSON Schema looks like this:

{
  "type": "object"
}

This schema validates that the data is a JSON object. You can add more constraints:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

Primitive Types

JSON Schema supports these primitive types:

• string: Text data with optional format validation
• number: Any numeric value (integer or floating-point)
• integer: Whole numbers only
• boolean: true or false
• null: The null value
• array: An ordered list
• object: A JSON object

Object Validation

When validating objects, you can specify:

• properties: Define expected fields and their types
• required: Array of mandatory field names
• additionalProperties: Whether extra fields are allowed
• minProperties / maxProperties: Constrain object size
• propertyNames: Validate all property names

Array Validation

Arrays support:

• items: Schema for array elements
• minItems / maxItems: Constrain array length
• uniqueItems: Ensure all elements are unique
• contains: Check that at least one element matches

String Validation

Strings can be validated with:

• minLength / maxLength: Character count limits
• pattern: Regular expression match
• format: Predefined formats like date-time, email, uri, uuid

Numeric Validation

For numbers and integers:

• minimum / maximum: Value bounds
• exclusiveMinimum / exclusiveMaximum: Strict bounds
• multipleOf: Value must be a multiple of this number

Combining Schemas

JSON Schema provides logical operators:

• allOf: Must match all schemas
• anyOf: Must match at least one schema
• oneOf: Must match exactly one schema
• not: Must not match the schema

Reusable Definitions

Use $def to define reusable components:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zipcode": { "type": "string" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress": { "$ref": "#/$defs/address" },
    "shippingAddress": { "$ref": "#/$defs/address" }
  }
}

Conditional Application

Use if, then, and else for conditional validation:

{
  "type": "object",
  "properties": {
    "membership": { "type": "string" },
    "discount": { "type": "number" }
  },
  "if": {
    "properties": { "membership": { "enum": ["premium"] } }
  },
  "then": {
    "properties": { "discount": { "minimum": 0.2 } }
  },
  "else": {
    "properties": { "discount": { "maximum": 0.1 } }
  }
}

Summary

JSON Schema is an essential tool for API development. It provides clear documentation, robust validation, and supports complex data structures. Start with basic type validation and gradually adopt advanced features as your needs grow.