JSON Schema (Draft 2020-12)

JSON Schema is a declarative standard vocabulary written in JSON for annotating, validating, and enforcing structural constraints on JSON data documents. Standardized by the IETF JSON Schema Working Group across successive draft specifications (Draft 7, Draft 2019-09, Draft 2020-12), JSON Schema allows developers to describe allowed keys, mandatory properties, regex patterns, numeric thresholds, and array cardinality. It forms the backbone of OpenAPI contracts, API gateway validations, and LLM structured outputs.

Generate schema definitions automatically from sample payloads with our JSON to Schema Generator or compile schemas to TypeScript with JSON to Zod.

---

Technical Specifications at a Glance

Specification	Details
Current Standard	JSON Schema Draft 2020-12 (IETF Internet-Draft)
Media Type	application/schema+json
Specification URI	https://json-schema.org/draft/2020-12/schema
File Extension	.json, .schema.json
Validation Engines	Ajv (JavaScript/TypeScript), jsonschema (Python), gojsonschema (Go)
Integration Ecosystem	OpenAPI 3.1, AsyncAPI, JSON-RPC, VS Code settings validation

---

Anatomy of a JSON Schema (Draft 2020-12)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://devflow.tools/schemas/user-profile.json",
  "title": "UserProfile",
  "type": "object",
  "required": ["id", "username", "email", "roles"],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique UUID identifier"
    },
    "username": {
      "type": "string",
      "minLength": 3,
      "maxLength": 30,
      "pattern": "^[a-zA-Z0-9_]+$"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 18,
      "maximum": 120
    },
    "roles": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": ["admin", "editor", "viewer"]
      }
    }
  },
  "additionalProperties": false
}

---

Key Validation Keywords Reference

Keyword	Target Type	Validation Behavior
type	Any	Enforces primitive types: string, number, integer, boolean, array, object, null.
required	Object	Array of string key names that must be present.
additionalProperties	Object	Controls whether undeclared properties are permitted (false enforces strict payloads).
enum	Any	Constrains value to an explicit set of allowable literals.
format	String	Semantic validation checks (email, uri, date-time, uuid, ipv4).
pattern	String	Validates value against an ECMA-262 Regex.
items / prefixItems	Array	Enforces schemas for all array elements or tuple sequences.
$ref	Any	Reusable sub-schema pointer reference (e.g., "$ref": "#/$defs/Address").

---

Code Example: Validating JSON with Ajv (TypeScript)

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv({ allErrors: true });
addFormats(ajv); // Adds email, uri, uuid format validators

const schema = {
  type: 'object',
  properties: {
    sku: { type: 'string', minLength: 5 },
    price: { type: 'number', minimum: 0.01 },
  },
  required: ['sku', 'price'],
  additionalProperties: false,
};

const validate = ajv.compile(schema);

const testData = { sku: 'PROD-99', price: 19.99 };

if (validate(testData)) {
  console.log('Valid JSON payload!');
} else {
  console.error('Validation errors:', validate.errors);
}

---

Frequently Asked Questions

What is the difference between JSON Schema Draft 7 and Draft 2020-12?

Draft 2020-12 introduces major modernizations, including complete separation of vocabulary extensions, unified dynamic referencing ($dynamicRef), tuple array validation via prefixItems, and full alignment with the latest OpenAPI 3.1 specifications.

How does JSON Schema compare to Zod in TypeScript?

JSON Schema is a language-neutral, serializable JSON specification standard understood by backends written in Python, Java, Go, C#, or Rust. Zod is a TypeScript-first runtime validation library designed for developer ergonomics in Node.js and browser environments. You can easily cross-compile between both using our JSON to Zod Converter.

Can JSON Schema be used to constrain LLM responses?

Yes. Modern AI models (OpenAI Structured Outputs, Anthropic, Gemini) consume JSON Schema definitions directly via their API parameters to guarantee that generated completions adhere strictly to your programmatic schema without hallucinated keys. Test schemas with our LLM JSON Schema Builder.