Understanding JSON Schema: Complete Validation Guide

What is JSON Schema?

JSON Schema is a vocabulary for validating and describing JSON documents. It defines the structure, constraints, and validation rules for your JSON data.

Basic Schema Example

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

Schema Keywords

• type: Data type (string, number, object, array, boolean, null)
• required: Required properties
• properties: Object property definitions
• minimum/maximum: Number constraints
• minLength/maxLength: String length constraints
• pattern: Regex pattern for strings
• format: Predefined formats (email, uri, date, etc.)

Validation in JavaScript

import Ajv from 'ajv';

const ajv = new Ajv();
const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number', minimum: 0 }
  },
  required: ['name']
};

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', age: 30 });

if (!valid) {
  console.log(validate.errors);
}

Validation in Python

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name"]
}

data = {"name": "Alice", "age": 30}

try:
    validate(instance=data, schema=schema)
    print("Valid!")
except ValidationError as e:
    print(f"Error: {e.message}")

Advanced Features

• $ref: Schema references and reusability
• allOf/anyOf/oneOf: Schema composition
• if/then/else: Conditional schemas
• additionalProperties: Control extra properties

Nested Schema Example

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "address": {
          "type": "object",
          "properties": {
            "street": { "type": "string" },
            "city": { "type": "string" }
          }
        }
      }
    }
  }
}

Array Validation

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "name": { "type": "string" }
    }
  },
  "minItems": 1,
  "maxItems": 100
}

Best Practices

Start simple, add complexity as needed

Use $defs for reusable schema parts

Provide clear error messages

Version your schemas

Test schemas thoroughly

Schema Reusability

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress": { "$ref": "#/$defs/address" },
    "shippingAddress": { "$ref": "#/$defs/address" }
  }
}

Conclusion

JSON Schema is essential for building robust APIs. It provides validation, documentation, and type safety for your JSON data!