Meta-Schemas

What are Meta-Schemas?

A meta-schema is a JSON Schema that describes the structure and syntax of other JSON schemas. Meta-schemas serve several critical purposes:

Define valid schema syntax - Specify which keywords are allowed and their value constraints
Validate schemas - Ensure schemas conform to the specification’s requirements
Declare vocabularies - Identify which sets of keywords are available
Establish dialects - Define specific combinations of vocabularies for different use cases

Every JSON Schema has a meta-schema, which can be explicitly declared using the $schema keyword.

Core Meta-Schema Structure

The JSON Schema v1/2026 meta-schema is located at:

https://json-schema.org/v1/2026

Basic Structure

{
  "$schema": "https://json-schema.org/v1/2026",
  "$id": "https://json-schema.org/v1/2026",
  "$dynamicAnchor": "meta",
  "title": "JSON Schema Core and Validation specification meta-schema",
  "type": ["object", "boolean"]
}

Key Meta-Schema Properties

$schema: Self-identifies the meta-schema’s own dialect
$id: Establishes the canonical identifier
$dynamicAnchor: Enables dynamic reference resolution for extensibility
title: Human-readable description
type: Allows schemas to be objects or booleans

Meta-Schema Keywords

The meta-schema defines constraints for all standard JSON Schema keywords:

Identifier Keywords

{
  "properties": {
    "$id": {
      "$ref": "#/$defs/iriReferenceString",
      "$comment": "Fragments not allowed.",
      "pattern": "^[^#]*$"
    },
    "$schema": { "$ref": "#/$defs/iriString" },
    "$ref": { "$ref": "#/$defs/iriReferenceString" },
    "$anchor": { "$ref": "#/$defs/anchorString" },
    "$dynamicRef": { "$ref": "#/$defs/anchorString" },
    "$dynamicAnchor": { "$ref": "#/$defs/anchorString" }
  }
}

Validation Keywords

Type and Constant Keywords

{
  "properties": {
    "type": {
      "anyOf": [
        { "$ref": "#/$defs/simpleTypes" },
        {
          "type": "array",
          "items": { "$ref": "#/$defs/simpleTypes" },
          "minItems": 1,
          "uniqueItems": true
        }
      ]
    },
    "const": true,
    "enum": {
      "type": "array",
      "items": true
    }
  }
}

Numeric Keywords

{
  "properties": {
    "multipleOf": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "maximum": { "type": "number" },
    "exclusiveMaximum": { "type": "number" },
    "minimum": { "type": "number" },
    "exclusiveMinimum": { "type": "number" }
  }
}

String Keywords

{
  "properties": {
    "maxLength": { "$ref": "#/$defs/nonNegativeInteger" },
    "minLength": { "$ref": "#/$defs/nonNegativeIntegerDefault0" },
    "pattern": {
      "type": "string",
      "format": "regex"
    }
  }
}

Array Keywords

{
  "properties": {
    "maxItems": { "$ref": "#/$defs/nonNegativeInteger" },
    "minItems": { "$ref": "#/$defs/nonNegativeIntegerDefault0" },
    "uniqueItems": {
      "type": "boolean",
      "default": false
    },
    "prefixItems": { "$ref": "#/$defs/schemaArray" },
    "items": { "$dynamicRef": "meta" },
    "contains": { "$dynamicRef": "meta" },
    "maxContains": { "$ref": "#/$defs/nonNegativeInteger" },
    "minContains": {
      "$ref": "#/$defs/nonNegativeInteger",
      "default": 1
    }
  }
}

Object Keywords

{
  "properties": {
    "maxProperties": { "$ref": "#/$defs/nonNegativeInteger" },
    "minProperties": { "$ref": "#/$defs/nonNegativeIntegerDefault0" },
    "required": { "$ref": "#/$defs/stringArray" },
    "properties": {
      "type": "object",
      "additionalProperties": { "$dynamicRef": "meta" },
      "default": {}
    },
    "patternProperties": {
      "type": "object",
      "additionalProperties": { "$dynamicRef": "meta" },
      "propertyNames": { "format": "regex" },
      "default": {}
    },
    "additionalProperties": { "$dynamicRef": "meta" },
    "dependentRequired": {
      "type": "object",
      "additionalProperties": { "$ref": "#/$defs/stringArray" }
    },
    "dependentSchemas": {
      "type": "object",
      "additionalProperties": { "$dynamicRef": "meta" },
      "default": {}
    },
    "propertyNames": { "$dynamicRef": "meta" }
  }
}

Applicator Keywords

{
  "properties": {
    "allOf": { "$ref": "#/$defs/schemaArray" },
    "anyOf": { "$ref": "#/$defs/schemaArray" },
    "oneOf": { "$ref": "#/$defs/schemaArray" },
    "not": { "$dynamicRef": "meta" },
    "if": { "$dynamicRef": "meta" },
    "then": { "$dynamicRef": "meta" },
    "else": { "$dynamicRef": "meta" },
    "unevaluatedItems": { "$dynamicRef": "meta" },
    "unevaluatedProperties": { "$dynamicRef": "meta" }
  }
}

Metadata Keywords

{
  "properties": {
    "title": { "type": "string" },
    "description": { "type": "string" },
    "default": true,
    "deprecated": {
      "type": "boolean",
      "default": false
    },
    "readOnly": {
      "type": "boolean",
      "default": false
    },
    "writeOnly": {
      "type": "boolean",
      "default": false
    },
    "examples": {
      "type": "array",
      "items": true
    }
  }
}

Content Keywords

{
  "properties": {
    "format": { "type": "string" },
    "contentEncoding": { "type": "string" },
    "contentMediaType": { "type": "string" },
    "contentSchema": { "$dynamicRef": "meta" }
  }
}

Reusable Definitions

The meta-schema defines reusable components in $defs:

{
  "$defs": {
    "anchorString": {
      "type": "string",
      "pattern": "^[A-Za-z_][-A-Za-z0-9._]*$"
    },
    "iriString": {
      "type": "string",
      "format": "iri"
    },
    "iriReferenceString": {
      "type": "string",
      "format": "iri-reference"
    },
    "nonNegativeInteger": {
      "type": "integer",
      "minimum": 0
    },
    "nonNegativeIntegerDefault0": {
      "$ref": "#/$defs/nonNegativeInteger",
      "default": 0
    },
    "schemaArray": {
      "type": "array",
      "minItems": 1,
      "items": { "$dynamicRef": "meta" }
    },
    "simpleTypes": {
      "enum": [
        "array",
        "boolean",
        "integer",
        "null",
        "number",
        "object",
        "string"
      ]
    },
    "stringArray": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true,
      "default": []
    }
  }
}

Extension Mechanism

The meta-schema includes patterns for allowing extensions:

Custom Extension Keywords

{
  "patternProperties": {
    "^x-": true
  }
}

Keywords beginning with x- are automatically treated as annotations.

Property Name Restrictions

{
  "propertyNames": {
    "pattern": "^[^$]|^\\$(id|schema|ref|anchor|dynamicRef|dynamicAnchor|comment|defs)$"
  }
}

This pattern ensures:

Non-core keywords cannot start with $
Only recognized $ keywords are allowed

Dynamic Extension Point

{
  "$dynamicRef": "extension",
  "unevaluatedProperties": false,
  "$defs": {
    "extension": {
      "$dynamicAnchor": "extension"
    }
  }
}

This allows extending the meta-schema while maintaining validation.

Vocabulary-Based Meta-Schema

The draft-next specification uses a vocabulary-based approach:

{
  "$schema": "https://json-schema.org/draft/next/schema",
  "$id": "https://json-schema.org/draft/next/schema",
  "$vocabulary": {
    "https://json-schema.org/draft/next/vocab/core": true,
    "https://json-schema.org/draft/next/vocab/applicator": true,
    "https://json-schema.org/draft/next/vocab/unevaluated": true,
    "https://json-schema.org/draft/next/vocab/validation": true,
    "https://json-schema.org/draft/next/vocab/meta-data": true,
    "https://json-schema.org/draft/next/vocab/format-annotation": true,
    "https://json-schema.org/draft/next/vocab/content": true
  },
  "allOf": [
    {"$ref": "meta/core"},
    {"$ref": "meta/applicator"},
    {"$ref": "meta/unevaluated"},
    {"$ref": "meta/validation"},
    {"$ref": "meta/meta-data"},
    {"$ref": "meta/format-annotation"},
    {"$ref": "meta/content"}
  ]
}

Vocabulary Breakdown

Core Vocabulary

IRI: https://json-schema.org/draft/next/vocab/coreKeywords:

$schema, $id, $ref, $anchor
$dynamicRef, $dynamicAnchor
$defs, $comment

Purpose: Essential keywords for schema structure and referencing.

Applicator Vocabulary

IRI: https://json-schema.org/draft/next/vocab/applicatorKeywords:

prefixItems, items, contains
properties, patternProperties, additionalProperties
propertyNames, dependentSchemas
allOf, anyOf, oneOf, not
if, then, else

Purpose: Keywords that apply subschemas to instance locations.

Unevaluated Vocabulary

IRI: https://json-schema.org/draft/next/vocab/unevaluatedKeywords:

unevaluatedItems
unevaluatedProperties

Purpose: Keywords that apply to locations not evaluated by other keywords.

Validation Vocabulary

IRI: https://json-schema.org/draft/next/vocab/validationKeywords:

Type: type, enum, const
Numeric: multipleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum
String: maxLength, minLength, pattern
Array: maxItems, minItems, uniqueItems, maxContains, minContains
Object: maxProperties, minProperties, required, dependentRequired

Purpose: Assertion keywords for validating instance structure.

Meta-Data Vocabulary

IRI: https://json-schema.org/draft/next/vocab/meta-dataKeywords:

title, description
default, deprecated
readOnly, writeOnly
examples

Purpose: Annotation keywords for documentation and tooling.

Format Annotation Vocabulary

IRI: https://json-schema.org/draft/next/vocab/format-annotationKeywords:

format

Purpose: Semantic validation of string formats.

Content Vocabulary

IRI: https://json-schema.org/draft/next/vocab/contentKeywords:

contentEncoding
contentMediaType
contentSchema

Purpose: Describing string-encoded content.

Deprecated Keywords

The meta-schema maintains backward compatibility by including deprecated keywords:

{
  "properties": {
    "definitions": {
      "$comment": "\"definitions\" has been replaced by \"$defs\".",
      "type": "object",
      "additionalProperties": { "$dynamicRef": "meta" },
      "deprecated": true,
      "default": {}
    },
    "dependencies": {
      "$comment": "\"dependencies\" has been split and replaced by \"dependentSchemas\" and \"dependentRequired\".",
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          { "$dynamicRef": "meta" },
          { "$ref": "meta/validation#/$defs/stringArray" }
        ]
      },
      "deprecated": true,
      "default": {}
    },
    "$recursiveAnchor": {
      "$comment": "\"$recursiveAnchor\" has been replaced by \"$dynamicAnchor\".",
      "type": "boolean",
      "deprecated": true
    },
    "$recursiveRef": {
      "$comment": "\"$recursiveRef\" has been replaced by \"$dynamicRef\".",
      "type": "string",
      "format": "uri-reference",
      "deprecated": true
    }
  }
}

Publication URLs

Meta-schemas are published at official URLs:

Current Version (v1/2026)

Canonical: https://json-schema.org/v1/2026
Version alias: https://json-schema.org/v1 (latest within v1)

Draft Versions

Draft-next: https://json-schema.org/draft/next/schema

Implementations SHOULD include a bundled copy of the meta-schema rather than fetching it from the network.

Using Meta-Schemas

Validating a Schema

To validate that a schema is well-formed:

{
  "$schema": "https://json-schema.org/v1/2026",
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  }
}

This schema should validate successfully against the v1/2026 meta-schema.

Creating Custom Meta-Schemas

You can extend the standard meta-schema for custom dialects:

{
  "$schema": "https://json-schema.org/v1/2026",
  "$id": "https://example.com/meta/custom",
  "allOf": [
    { "$ref": "https://json-schema.org/v1/2026" }
  ],
  "properties": {
    "x-custom-keyword": {
      "type": "string",
      "description": "Custom extension keyword"
    }
  }
}

Dialect Determination

Implementations determine the dialect using:

$schema keyword (highest priority)
Parent schema dialect (for embedded resources)
External context (media type parameters, embedding specifications)
User configuration

If the dialect cannot be determined, implementations MUST refuse to process the schema.

Best Practices

Always declare $schema in root schemas to ensure correct interpretation
Validate your schemas against their meta-schema before publishing
Use vocabulary-based meta-schemas for modular dialect design
Bundle meta-schemas in your implementation rather than fetching from URLs
Document custom extensions clearly when creating custom meta-schemas

For more information about meta-schemas and vocabularies, visit json-schema.org

Get Started

Core Concepts

Specification

Development Process

What are Meta-Schemas?

Core Meta-Schema Structure

Basic Structure

Meta-Schema Keywords

Identifier Keywords

Validation Keywords

Applicator Keywords

Metadata Keywords

Content Keywords

Reusable Definitions

Extension Mechanism

Custom Extension Keywords

Property Name Restrictions

Dynamic Extension Point

Vocabulary-Based Meta-Schema

Vocabulary Breakdown

Deprecated Keywords

Publication URLs

Current Version (v1/2026)

Draft Versions

Using Meta-Schemas

Validating a Schema

Creating Custom Meta-Schemas

Dialect Determination

Best Practices

Get Started

Core Concepts

Specification

Development Process

​What are Meta-Schemas?

​Core Meta-Schema Structure

​Basic Structure

​Meta-Schema Keywords

​Identifier Keywords

​Validation Keywords

​Applicator Keywords

​Metadata Keywords

​Content Keywords

​Reusable Definitions

​Extension Mechanism

​Custom Extension Keywords

​Property Name Restrictions

​Dynamic Extension Point

​Vocabulary-Based Meta-Schema

​Vocabulary Breakdown

​Deprecated Keywords

​Publication URLs

​Current Version (v1/2026)

​Draft Versions

​Using Meta-Schemas

​Validating a Schema

​Creating Custom Meta-Schemas

​Dialect Determination

​Best Practices

What are Meta-Schemas?

Core Meta-Schema Structure

Basic Structure

Meta-Schema Keywords

Identifier Keywords

Validation Keywords

Applicator Keywords

Metadata Keywords

Content Keywords

Reusable Definitions

Extension Mechanism

Custom Extension Keywords

Property Name Restrictions

Dynamic Extension Point

Vocabulary-Based Meta-Schema

Vocabulary Breakdown

Deprecated Keywords

Publication URLs

Current Version (v1/2026)

Draft Versions

Using Meta-Schemas

Validating a Schema

Creating Custom Meta-Schemas

Dialect Determination

Best Practices