JSON Schema is a vocabulary for annotating and validating JSON data. A JSON Schema is itself a JSON document that describes what valid data looks like — which fields are required, what types values must be, and what constraints they must satisfy. For example, a schema can specify that an object must have an "id" field of type integer and an "email" field of type string with format "email". JSON Schema is widely used for API contract testing, configuration file validation, form validation, and generating TypeScript types automatically. The most widely supported version in libraries and tooling is draft-07, though draft 2020-12 is the current stable standard.

How do I validate an object with required fields in JSON Schema?

To require specific fields in a JSON Schema object, use the "required" keyword alongside "properties". The "required" keyword takes an array of property name strings. For example: {"type": "object", "required": ["id", "email"], "properties": {"id": {"type": "integer"}, "email": {"type": "string", "format": "email"}, "name": {"type": "string"}}}. This schema requires both "id" and "email" to be present. The "name" property is allowed but optional. If a required field is missing from the validated data, the validator reports a validation error. Note that "required" only checks for the presence of keys, not whether their values are null.

JSON Schema Tutorial: Validate JSON with Examples

Q: What JSON Schema keywords are most commonly used?

The most commonly used JSON Schema keywords are: "type" (restricts the value to a JSON type such as string, number, integer, boolean, array, object, or null), "properties" (defines schemas for each key in an object), "required" (lists keys that must be present), "enum" (restricts a value to a fixed list of allowed values), "minimum" and "maximum" (numeric range constraints), "minLength" and "maxLength" (string length constraints), "pattern" (regex constraint on strings), "format" (semantic hints like "email" or "date-time"), "items" (schema for array elements), and "$ref" (reference to a reusable sub-schema defined in "$defs"). Most schemas combine several of these to fully describe the expected data shape.

Q: What is the difference between JSON Schema and JSON?

JSON is a data format — a syntax for representing structured data using strings, numbers, booleans, null, arrays, and objects. JSON Schema is a way to describe and validate JSON data. A JSON Schema document is itself valid JSON, but it contains keywords like "type", "properties", and "required" that describe rules rather than data. For example, the JSON value {"name": "Alice", "age": 30} is a piece of data, while the schema {"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}} describes what valid data should look like. JSON Schema requires a validator library to actually check data against a schema.

Q: What JSON Schema versions exist and which is current?

JSON Schema has been published in several drafts: draft-04 (2013), draft-06 (2017), draft-07 (2018), draft 2019-09, and draft 2020-12. The current stable version is draft 2020-12, but draft-07 remains the most widely supported in validator libraries across languages. When writing a schema, declare the version using the "$schema" keyword so validators know which specification to apply — for example, "$schema": "http://json-schema.org/draft-07/schema#" for draft-07. The main differences between versions involve keywords like "items" vs "prefixItems" for arrays, and "$defs" replacing "definitions" in newer drafts.

Q: How do I add a description to a JSON Schema property?

Use the "description" keyword inside any schema to add human-readable documentation. For example: {"type": "object", "properties": {"status": {"type": "string", "enum": ["active", "inactive"], "description": "The current account status. Use active for normal accounts and inactive for suspended ones."}}}. The "description" keyword has no effect on validation — it is purely for documentation and tooling. Similarly, the "title" keyword provides a short label for a schema or property. Code generators, documentation tools, and API explorers like Swagger UI display these annotations to help developers understand what each field represents.

Last updated: May 11, 2026

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

JSON Schema is a JSON document that describes and validates the structure of other JSON data — a schema declares required fields, allowed types, and constraints that a value must satisfy. The current stable specification is Draft 2020-12, but Draft 07 remains the most widely supported across validator libraries; Ajv, the dominant JavaScript validator, has 100 million weekly npm downloads and supports both drafts. A schema document is identified by the $schema keyword pointing to the draft URI, and a required array listing mandatory property names; omitting required makes all properties optional regardless of whether they appear in properties. This guide covers the 7 JSON Schema types, required and properties, if/then/else conditionals, $ref for reuse, Draft 07 vs Draft 2020-12 differences, and Ajv validation in JavaScript.

What is JSON Schema?

Any JSON value can be validated against a schema: an API request body, a configuration file, or a database document. The most-used validator for JavaScript is Ajv, with over 100 million weekly npm downloads. Validators also exist for Python (jsonschema), Java (everit), Go (gojsonschema), and most other languages. JSON Schema is additionally used to auto-generate TypeScript types and power form validation libraries such as React Hook Form and Zod.

// A simple schema for a user object
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "name": { "type": "string" }
  }
}

// Valid data:
{ "id": 1, "email": "alice@example.com", "name": "Alice" }
{ "id": 2, "email": "bob@example.com" }

// Invalid data:
{ "email": "alice@example.com" }        // missing required "id"
{ "id": "one", "email": "a@b.com" }    // id must be integer

If you need ready-made snippets instead of a full tutorial, jump to JSON Schema examples.

Core keywords

type

Specifies the expected JSON type. Valid values: string, number, integer, boolean, array, object, null.

{ "type": "string" }    // validates: "hello"
{ "type": "integer" }   // validates: 42, not 3.14
{ "type": "number" }    // validates: 42, 3.14
{ "type": ["string", "null"] }  // validates: "hello" or null

properties and required

properties defines a schema for each key. required lists keys that must be present. A key in properties but not in requiredis optional.

{
  "type": "object",
  "required": ["title", "price"],
  "properties": {
    "title": { "type": "string" },
    "price": { "type": "number", "minimum": 0 },
    "description": { "type": "string" }   // optional
  }
}

String constraints

{
  "type": "string",
  "minLength": 1,        // at least 1 character
  "maxLength": 100,      // at most 100 characters
  "pattern": "^[a-z]+$" // must match regex (lowercase letters only)
}

Number constraints

{
  "type": "number",
  "minimum": 0,          // >= 0
  "maximum": 100,        // <= 100
  "exclusiveMinimum": 0, // > 0 (draft-07 style)
  "multipleOf": 0.5      // must be a multiple of 0.5
}

enum

Restricts a value to a fixed set of allowed values.

{ "enum": ["pending", "active", "suspended", "deleted"] }

// Also works for mixed types:
{ "enum": [1, "one", null, true] }

format

Provides semantic validation hints. Validators may or may not enforce format checks — it depends on the implementation.

{ "type": "string", "format": "email" }
{ "type": "string", "format": "date" }        // "2024-01-15"
{ "type": "string", "format": "date-time" }   // "2024-01-15T10:30:00Z"
{ "type": "string", "format": "uri" }
{ "type": "string", "format": "uuid" }

Array validation

{
  "type": "array",
  "items": { "type": "string" },   // all items must be strings
  "minItems": 1,                   // at least one item
  "maxItems": 10,                  // at most ten items
  "uniqueItems": true              // no duplicate values
}

Composition keywords

allOf, anyOf, oneOf

// allOf — must satisfy ALL sub-schemas
{
  "allOf": [
    { "type": "object" },
    { "required": ["name"] }
  ]
}

// anyOf — must satisfy AT LEAST ONE sub-schema
{
  "anyOf": [
    { "type": "string" },
    { "type": "number" }
  ]
}

// oneOf — must satisfy EXACTLY ONE sub-schema
{
  "oneOf": [
    { "type": "string", "maxLength": 5 },
    { "type": "string", "minLength": 10 }
  ]
}

not

// Must NOT be a string
{ "not": { "type": "string" } }

$ref and $defs

Use $defs to define reusable sub-schemas and reference them with $ref:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "billing": { "$ref": "#/$defs/address" },
    "shipping": { "$ref": "#/$defs/address" }
  },
  "$defs": {
    "address": {
      "type": "object",
      "required": ["street", "city"],
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zip": { "type": "string" }
      }
    }
  }
}

Complete annotated example

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Product",
  "type": "object",
  "required": ["id", "name", "price", "category"],
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "exclusiveMinimum": 0
    },
    "category": {
      "type": "string",
      "enum": ["electronics", "books", "clothing", "food"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string", "minLength": 1 },
      "uniqueItems": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": { "type": "string" }
    }
  }
}

Draft versions

JSON Schema has multiple published drafts: draft-04, draft-06, draft-07, draft 2019-09, draft 2020-12. The most widely supported in libraries and tooling is draft-07. When writing schemas, always declare the version with $schema so validators know which spec to use.

Validate JSON against a schema

Paste your JSON and schema into Jsonic's JSON Schema Validator to check for errors instantly. Runs in your browser — nothing is uploaded.

Open JSON Schema Validator

Frequently asked questions

What is JSON Schema?

JSON Schema is a vocabulary for annotating and validating JSON data. A schema is itself a JSON document that describes what valid data looks like — which fields are required, what types values must be, and what constraints they must satisfy. It's widely used for API contract testing, configuration validation, and generating TypeScript types.

What JSON Schema keywords are most commonly used?

The most common keywords are: type, properties, required, enum, minimum/maximum, minLength/maxLength, pattern, format, items, and $ref. Most schemas combine several of these to fully describe the expected data shape.

What is the difference between JSON Schema and JSON?

JSON is a data format for representing structured data. JSON Schema is a way to describe and validate JSON data. A schema document is itself valid JSON, but uses special keywords like type and required to describe rules rather than data. A validator library is needed to check data against a schema.

How do I validate an object with required fields?

Use the required keyword alongside properties. The required array lists property names that must be present. Properties listed in properties but not in required are optional.

What JSON Schema versions exist and which is current?

Published drafts include draft-04, draft-06, draft-07, draft 2019-09, and draft 2020-12. Draft 2020-12 is the current standard, but draft-07 is the most widely supported in validator libraries. Always declare the version with $schema.

How do I add a description to a JSON Schema property?

Use the description keyword inside any schema. It has no effect on validation — it's purely for documentation. Code generators, API explorers, and documentation tools display it to help developers understand each field.

JSON Schema Tutorial: Validate JSON with Examples

What is JSON Schema?

Core keywords

type

properties and required

String constraints

Number constraints

enum

format

Array validation

Composition keywords

allOf, anyOf, oneOf

not

$ref and $defs

Complete annotated example

Draft versions

Validate JSON against a schema

Frequently asked questions

What is JSON Schema?

What JSON Schema keywords are most commonly used?

What is the difference between JSON Schema and JSON?

How do I validate an object with required fields?

What JSON Schema versions exist and which is current?

How do I add a description to a JSON Schema property?

Further reading and primary sources

Recommended reading