What is JSON Schema?

JSON Schema is a declarative language for defining the structure of JSON data. Think of it as TypeScript types, but for JSON—you define what properties exist, their types, and any constraints. Then you can validate any JSON document against that schema.

When to Use Schema Validation

• API request validation — Reject malformed requests before they hit your business logic
• Configuration files — Catch typos in config before deployment
• Form data — Validate user input on both client and server
• Data pipelines — Ensure incoming data matches expected format
• API documentation — Schemas serve as living documentation

Quick Reference

Basic Types

{ "type": "string" }
{ "type": "number" }
{ "type": "integer" }
{ "type": "boolean" }
{ "type": "null" }
{ "type": "array" }
{ "type": "object" }

String Constraints

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100,
  "pattern": "^[a-z]+$",
  "format": "email"  // or: uri, date-time, uuid
}

Number Constraints

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "exclusiveMinimum": 0,
  "multipleOf": 0.01
}

Object with Required Properties

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name"],
  "additionalProperties": false
}

Array Validation

{
  "type": "array",
  "items": { "type": "string" },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

Complete Example

Here's a schema for a user profile API response:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": { 
      "type": "integer",
      "minimum": 1
    },
    "username": { 
      "type": "string",
      "minLength": 3,
      "maxLength": 20,
      "pattern": "^[a-zA-Z0-9_]+$"
    },
    "email": { 
      "type": "string", 
      "format": "email" 
    },
    "role": { 
      "type": "string",
      "enum": ["admin", "user", "guest"]
    },
    "profile": {
      "type": "object",
      "properties": {
        "bio": { "type": "string", "maxLength": 500 },
        "avatar": { "type": "string", "format": "uri" }
      }
    },
    "createdAt": { 
      "type": "string", 
      "format": "date-time" 
    }
  },
  "required": ["id", "username", "email", "role"],
  "additionalProperties": false
}

Understanding Validation Errors

When validation fails, you'll see errors like:

• must have required property 'name' — A required field is missing
• must be string — Wrong type (e.g., number instead of string)
• must match format "email" — String doesn't match the format
• must NOT have additional properties — Unknown field whenadditionalProperties: false
• must be >= 0 — Number violates minimum constraint

Pro Tips

• 💡 Start strict — Use "additionalProperties": false to catch typos in property names. You can always loosen later.
• 💡 Use enums for known values — Instead of just string, use "enum": ["active", "inactive"] when you know the valid values.
• 💡 Add descriptions — Include "description" fields for documentation that travels with your schema.
• 💡 Test edge cases — Validate with empty objects, null values, and boundary numbers to ensure your schema handles them correctly.

Supported Draft Version

This validator uses Ajv and supports JSON Schema draft-07 by default. Most draft-04 and draft-06 schemas will also work.

Related Tools

• JSON Validator — Validate JSON syntax
• JSON Diff — Compare two JSON documents
• JSON Path Query — Extract values from JSON

Learn More

• json-schema.org — Official specification
• Understanding JSON Schema — Free online book

Common Mistakes & Pro Tips

• Declare the right draft in $schema — AJV validates against a specific draft, and keywords behave differently between them. Set "$schema" to e.g. "http://json-schema.org/draft-07/schema#" or "https://json-schema.org/draft/2020-12/schema" so you get the semantics you expect; in 2020-12, for instance, array tuples use "prefixItems" instead of an array-valued "items".
• "required" is separate from "properties" — Listing a field under "properties" only describes its shape if present, it does not make it mandatory. To require a field you must add its name to the "required" array on the same object level. A common bug is defining a property but forgetting to require it, so a document missing it still passes.
• additionalProperties: false is strict — Setting "additionalProperties": false rejects any key not explicitly named in "properties" (and "patternProperties"). It does not see properties inherited through "$ref", "allOf", or "oneOf", so combining it with composition often rejects valid data. Use it deliberately, and prefer "unevaluatedProperties" (2020-12) when composing schemas.
• "format" is annotation-only by default — Keywords like "email", "date-time", or "uri" do not fail validation unless format assertion is enabled. In AJV you must add the ajv-formats package and turn assertions on; otherwise a malformed email passes. Do not rely on "format" alone for input validation.
• Numbers, integers, and type coercion — "type": "integer" rejects 1.5 but accepts 1.0 because JSON has one number type; "type": "number" accepts both. AJV does not coerce strings to numbers unless coercion is explicitly enabled, so "42" fails an integer schema. Use "multipleOf", "minimum", and "exclusiveMinimum" for ranges.