The Complete JSON Schema Guide (Draft 7)

What is JSON Schema?

A JSON Schema is itself a JSON document that describes the shape of other JSON data. Use it to validate API payloads, document expected formats, generate code (TypeScript, Go), and catch bad data before it reaches your logic.

Core keywords

The type keyword constrains a value to string, number, boolean, null, object, or array. properties and required describe object shape; items describes array elements.

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "number", "minimum": 0, "maximum": 150 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

Beyond type: enum restricts to a fixed set, const requires an exact value, pattern matches a regex, minLength/maxLength bound string length, and additionalProperties: false forbids unknown keys.

A real-world API schema

Here's a schema for a user-registration endpoint. Notice how each constraint doubles as documentation, and how required + additionalProperties: false make the contract strict.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "username": { "type": "string", "pattern": "^[a-zA-Z0-9_]{3,30}$" },
    "email": { "type": "string", "format": "email" },
    "password": { "type": "string", "minLength": 8 },
    "acceptTerms": { "type": "boolean", "const": true }
  },
  "required": ["username", "email", "password", "acceptTerms"],
  "additionalProperties": false
}

Best practices

Always declare $schema so validators know which draft you target. Add description fields — they become live API docs. Prefer format (email, uri) over hand-rolled regex. Use additionalProperties: false for strict APIs, but allow it when extensibility matters. Avoid deeply nested schemas — factor with $ref and definitions.