JSON Schema 参考 关键字参考

Declares the JSON Schema dialect version

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

ℹ Always include at root to declare the dialect

Sets the base URI for the schema

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

Human-readable title for the schema or property

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

Human-readable description of the schema's purpose

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

Developer comment — not rendered to users

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

Repository for reusable sub-schemas

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

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

Reference to another schema by URI or JSON Pointer

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

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

Value must be a JSON string

{ "type": "string" }

Value must be a JSON number (integer or float)

{ "type": "number" }

Value must be a whole number (no fractional part)

{ "type": "integer" }

Value must be true or false

{ "type": "boolean" }

Value must be JSON null

{ "type": "null" }

Value must be a JSON array

{ "type": "array" }

Value must be a JSON object

{ "type": "object" }

Value may be one of the listed types

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

ℹ Useful for optional/nullable fields

Minimum and maximum number of Unicode code points

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

Value must match a ECMA 262 regular expression

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

ℹ Partial match — use ^ and $ to anchor

Semantic validation hint (implementation-dependent)

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

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

Value must be one of the listed values

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

Value must exactly equal the given value

{ "const": "v1" }

ℹ Equivalent to enum with a single value

Inclusive lower and upper bounds

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

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

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

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

Value must be a multiple of the given number

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

Schema for each named property

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

Array of property names that must be present

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

Schema or boolean controlling unknown properties

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

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

Schemas applied to properties whose name matches the regex key

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

Min/max number of properties in the object

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

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

Per-index schemas for a tuple

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

ℹ Replaces tuple form of items from draft-07

Min/max number of array elements

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

All items must be unique

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

At least one item must match the given schema

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

ℹ Use minContains / maxContains to control how many must match

Value must be valid against ALL listed schemas

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

ℹ Intersection — use for schema composition/extension

Value must be valid against AT LEAST ONE listed schema

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

Value must be valid against EXACTLY ONE listed schema

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

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

Value must NOT be valid against the given schema

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

Conditional validation: if condition matches, then/else applies

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