JSON Schema Keywords Reference
JSON Schema describes allowed JSON instances with validation and annotation keywords. Declare the schema dialect and test with the same validator used by the application because draft support varies.
Core type and value keywords
| Keyword | Purpose |
|---|---|
| type | Restricts the JSON type or allowed types. |
| enum | Allows values equal to one of a fixed set. |
| const | Requires equality to one value. |
| title | Provides a short human-readable schema title. |
| description | Explains intended meaning and usage. |
| default | Annotates a default value; validators do not necessarily insert it. |
| examples | Provides illustrative values that should satisfy the schema. |
Object keywords
properties maps known property names to schemas, but it does not make them mandatory. required is an array of names that must appear. additionalProperties controls names not covered by the applicable property rules and can be false or a schema for dictionary values. patternProperties applies schemas to names matching regular expressions. Property names themselves can be constrained with propertyNames.
Array keywords
items describes array elements under the selected dialect. prefixItems in newer dialects describes positional tuple entries. minItems and maxItems bound length, while uniqueItems: true requires pairwise-unique values under JSON equality. contains requires matching elements and can work with minimum and maximum contains counts where supported.
String constraints
minLength and maxLength constrain string length according to the dialect's character model. pattern applies a regular expression without automatically anchoring the whole string. Add anchors when full-value matching is intended. format can annotate values such as date-time, email, URI, or UUID, but enforcement and format vocabularies vary by validator.
Numeric constraints
minimum and maximum are inclusive bounds. exclusiveMinimum and exclusiveMaximum express strict bounds under the dialect syntax. multipleOf constrains values to a numeric step. Consider consumer precision when schemas permit large integers or decimals; JSON's number syntax does not guarantee one machine representation.
Composition and conditionals
| Keyword | Validation rule |
|---|---|
| allOf | Every listed subschema must match. |
| anyOf | At least one listed subschema must match. |
| oneOf | Exactly one listed subschema must match. |
| not | The listed schema must not match. |
| if / then / else | Applies conditional validation under supported dialects. |
Keep oneOf branches distinct so valid data cannot match several. Use composition to express real domain rules, not merely to satisfy a generator. Review error output for every branch because a top-level composition failure can hide the actionable constraint.
Identifiers and references
$schema declares the dialect. $id establishes a schema identifier and can affect reference resolution. $ref points to another schema or fragment using URI-reference and JSON Pointer rules. Relative references resolve from their current base, so bundled and multi-file schemas need portable paths and case-sensitive CI validation.
Frequently Asked Questions
Does properties imply required?
No. List mandatory names in required.
What does additionalProperties false do?
It rejects otherwise unpermitted object names.
How do oneOf and anyOf differ?
oneOf requires exactly one match; anyOf allows one or more.