JSON Schema Reference

38 keywords

$schemaCore / Metaapplies to: root

Declares the JSON Schema dialect version

{ "$schema": "https://json-schema.org/draft/2020-12/schema" }

ℹ Always include at root to declare the dialect

$idCore / Metaapplies to: any

Sets the base URI for the schema

{ "$id": "https://example.com/schemas/user.json" }

titleCore / Metaapplies to: any

Human-readable title for the schema or property

{ "title": "User", "type": "object" }

descriptionCore / Metaapplies to: any

Human-readable description of the schema's purpose

{ "description": "A registered user account", "type": "object" }

$commentCore / Metaapplies to: any

Developer comment — not rendered to users

{ "$comment": "Added 2024-01 to support OAuth users" }

$defs / definitionsCore / Metaapplies to: root

Repository for reusable sub-schemas

{ "$defs": { "email": { "type": "string", "format": "email" } } }

ℹ $defs is draft 2020-12+; use definitions in draft-07

$refCore / Metaapplies to: any

Reference to another schema by URI or JSON Pointer

{ "$ref": "#/$defs/email" }

ℹ Can reference internal (#/$defs/…) or external schemas

type: stringTypesapplies to: string

Value must be a JSON string

{ "type": "string" }

type: numberTypesapplies to: number

Value must be a JSON number (integer or float)

{ "type": "number" }

type: integerTypesapplies to: number

Value must be a whole number (no fractional part)

{ "type": "integer" }

type: booleanTypesapplies to: boolean

Value must be true or false

{ "type": "boolean" }

type: nullTypesapplies to: null

Value must be JSON null

{ "type": "null" }

type: arrayTypesapplies to: array

Value must be a JSON array

{ "type": "array" }

type: objectTypesapplies to: object

Value must be a JSON object

{ "type": "object" }

type: [multiple]Typesapplies to: any

Value may be one of the listed types

{ "type": ["string", "null"] }

ℹ Useful for optional/nullable fields

minLength / maxLengthStringsapplies to: string

Minimum and maximum number of Unicode code points

{ "type": "string", "minLength": 1, "maxLength": 100 }

patternStringsapplies to: string

Value must match a ECMA 262 regular expression

{ "type": "string", "pattern": "^[a-z0-9_]+$" }

ℹ Partial match — use ^ and $ to anchor

formatStringsapplies to: string

Semantic validation hint (implementation-dependent)

{ "type": "string", "format": "email" }

ℹ Common values: email, uri, uuid, date, date-time, ipv4, ipv6, hostname

enumStringsapplies to: any

Value must be one of the listed values

{ "type": "string", "enum": ["active", "inactive", "pending"] }

constStringsapplies to: any

Value must exactly equal the given value

{ "const": "v1" }

ℹ Equivalent to enum with a single value

minimum / maximumNumbersapplies to: number

Inclusive lower and upper bounds

{ "type": "number", "minimum": 0, "maximum": 100 }

exclusiveMinimum / exclusiveMaximumNumbersapplies to: number

Exclusive lower and upper bounds (value < max, value > min)

{ "type": "number", "exclusiveMinimum": 0 }

ℹ In draft-07 these were booleans; draft 2019+ they are numbers

multipleOfNumbersapplies to: number

Value must be a multiple of the given number

{ "type": "integer", "multipleOf": 5 }

propertiesObjectsapplies to: object

Schema for each named property

{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } } }

requiredObjectsapplies to: object

Array of property names that must be present

{ "type": "object", "required": ["id", "email"] }

additionalPropertiesObjectsapplies to: object

Schema or boolean controlling unknown properties

{ "type": "object", "additionalProperties": false }

ℹ false = no extra properties allowed; a schema validates extra properties

patternPropertiesObjectsapplies to: object

Schemas applied to properties whose name matches the regex key

{ "patternProperties": { "^S_": { "type": "string" } } }

minProperties / maxPropertiesObjectsapplies to: object

Min/max number of properties in the object

{ "type": "object", "minProperties": 1, "maxProperties": 10 }

items (draft-07)Arraysapplies to: array

Schema for all items (or tuple schemas as array)

{ "type": "array", "items": { "type": "string" } }

ℹ In draft-2020-12, items applies to all remaining items after prefixItems

prefixItems (2020-12)Arraysapplies to: array

Per-index schemas for a tuple

{ "type": "array", "prefixItems": [{ "type": "string" }, { "type": "number" }] }

ℹ Replaces tuple form of items from draft-07

minItems / maxItemsArraysapplies to: array

Min/max number of array elements

{ "type": "array", "minItems": 1, "maxItems": 50 }

uniqueItemsArraysapplies to: array

All items must be unique

{ "type": "array", "items": { "type": "string" }, "uniqueItems": true }

containsArraysapplies to: array

At least one item must match the given schema

{ "type": "array", "contains": { "const": "admin" } }

ℹ Use minContains / maxContains to control how many must match

allOfCompositionapplies to: any

Value must be valid against ALL listed schemas

{ "allOf": [{ "type": "string" }, { "minLength": 5 }] }

ℹ Intersection — use for schema composition/extension

anyOfCompositionapplies to: any

Value must be valid against AT LEAST ONE listed schema

{ "anyOf": [{ "type": "string" }, { "type": "number" }] }

oneOfCompositionapplies to: any

Value must be valid against EXACTLY ONE listed schema

{ "oneOf": [{ "type": "string" }, { "type": "number" }] }

ℹ Validates all and ensures exactly one matches — slower than anyOf

notCompositionapplies to: any

Value must NOT be valid against the given schema

{ "not": { "type": "null" } }

if / then / elseCompositionapplies to: any

Conditional validation: if condition matches, then/else applies

{ "if": { "properties": { "type": { "const": "email" } } }, "then": { "required": ["email"] }, "else": { "required": ["phone"] } }

Complete Schema Example

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.json",
  "title": "User",
  "description": "A registered user account",
  "type": "object",
  "required": ["id", "email", "role"],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 255
    },
    "name": {
      "type": ["string", "null"],
      "maxLength": 100
    },
    "role": {
      "type": "string",
      "enum": ["admin", "editor", "viewer"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true,
      "maxItems": 20
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false
}

Reusable Schema with $ref

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "zip":    { "type": "string", "pattern": "^[0-9]{5}$" },
        "country":{ "type": "string", "minLength": 2, "maxLength": 2 }
      }
    }
  },
  "type": "object",
  "properties": {
    "billing":  { "$ref": "#/$defs/address" },
    "shipping": { "$ref": "#/$defs/address" }
  }
}

How to find a JSON Schema keyword

Enter a keyword such as required into the reference search and read its explanation alongside the example. Use the applicable type shown on the entry to decide where that keyword belongs in your schema. The example below combines object properties with required: the list names a property that must exist, while its property schema controls the value's type. Copy only the portion that matches your intended rule.

Compare the draft you use with the reference before adding newer keywords to an older validator. This page is a searchable reference rather than a schema execution engine; it does not validate your documents when you search. Move the schema and a small test document into the JSON validator to check behavior, including missing fields and unexpected extra properties.

Keyword: required
Schema: {"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}
{"name":"Ada"}: satisfies these rules
{}: missing required name

JSON Schema FAQ

What is JSON Schema?

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. A JSON Schema is itself a JSON document that describes the structure, constraints, and documentation of another JSON document. It is widely used for API request/response validation, configuration file validation, and form validation.

What is the difference between draft-07 and draft-2020-12?

Draft-07 (2018) is the most widely supported version, used by Ajv, Java's everit-org, and Python jsonschema by default. Draft-2020-12 introduced $defs (replacing definitions), prefixItems for array tuples, the unevaluatedProperties/unevaluatedItems keywords, and dynamic references ($dynamicRef). Most validators support opt-in for the newer draft.

What is the difference between allOf, anyOf, and oneOf?

allOf requires a value to be valid against ALL listed schemas (intersection). anyOf requires it to be valid against AT LEAST ONE schema (union). oneOf requires it to be valid against EXACTLY ONE schema (exclusive). Use allOf for composing schemas, anyOf for accepting multiple types, and oneOf when exactly one branch must match.

How do I reference a reusable schema with $ref?

Define reusable schemas under the $defs (draft 2020-12) or definitions (draft-07) keyword, then reference them with $ref: '#/$defs/MyType'. You can also reference external schemas by full URI: $ref: 'https://example.com/schemas/address.json'. Circular references are supported by most validators.

JSON Formatter Online — Free & Private JSON Validator - Syntax & Schema Validation JSON Minifier - Compress & Optimize JSON JSON Diff Checker - Compare JSON Files JSON Editor - Advanced JSON Editing Tool JSON to CSV Converter - Convert JSON Data

Complete Schema Example

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.json",
  "title": "User",
  "description": "A registered user account",
  "type": "object",
  "required": ["id", "email", "role"],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 255
    },
    "name": {
      "type": ["string", "null"],
      "maxLength": 100
    },
    "role": {
      "type": "string",
      "enum": ["admin", "editor", "viewer"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true,
      "maxItems": 20
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false
}

Reusable Schema with $ref

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "zip":    { "type": "string", "pattern": "^[0-9]{5}$" },
        "country":{ "type": "string", "minLength": 2, "maxLength": 2 }
      }
    }
  },
  "type": "object",
  "properties": {
    "billing":  { "$ref": "#/$defs/address" },
    "shipping": { "$ref": "#/$defs/address" }
  }
}

How to find a JSON Schema keyword

Keyword: required
Schema: {"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}
{"name":"Ada"}: satisfies these rules
{}: missing required name

JSON Schema FAQ

JSON Schema Reference

Complete Schema Example

Reusable Schema with $ref

How to find a JSON Schema keyword

JSON Schema FAQ

What is JSON Schema?

What is the difference between draft-07 and draft-2020-12?

What is the difference between allOf, anyOf, and oneOf?

How do I reference a reusable schema with $ref?

Related Tools

JSON Schema Reference

Complete Schema Example

Reusable Schema with $ref

How to find a JSON Schema keyword

JSON Schema FAQ

What is JSON Schema?

What is the difference between draft-07 and draft-2020-12?

What is the difference between allOf, anyOf, and oneOf?

How do I reference a reusable schema with $ref?

Related Tools