Glossary {#glossary-jsonschema}#
# JSON Schema — Glossary of Terms
This glossary defines the most important JSON Schema keywords and concepts, with context and examples to help you avoid common pitfalls.
---
### JSON Schema
A vocabulary that allows you to annotate and validate JSON documents. Often used for API payloads, configs, and data exchange.
---
### Drafts
Versions of the specification.
- **draft-07**: still widely supported.
- **2019-09**: introduced `$defs`, vocabularies, `unevaluatedProperties`.
- **2020-12**: refined vocabularies, added `$dynamicRef`, anchors, and better extensibility.
---
### `$id`
Assigns a unique URI identifier to a schema. Useful when referencing schemas across files.
~~~yaml
$id: "https://example.com/schemas/user.json"
~~~
---
### `$ref`
A reference to another schema. Replaces the referencing object completely.
~~~yaml
$ref: '#/$defs/User'
~~~
---
### `$defs`
A container for reusable subschemas (replaces `definitions` in draft-07).
~~~yaml
$defs:
User:
type: object
properties:
id:
type: string
~~~
---
### `$dynamicRef` / `$dynamicAnchor`
Advanced referencing mechanism (2020-12). Allows deferred reference resolution, often used in extensible vocabularies.
---
### Type
Defines the primitive type of a value. Can be a string or an array of strings.
Values: `object`, `array`, `string`, `number`, `integer`, `boolean`, `null`.
~~~yaml
type: [string, "null"]
~~~
---
### Properties
Defines named fields of an object schema.
~~~yaml
type: object
properties:
name:
type: string
~~~
---
### Required
Lists object properties that must be present.
~~~yaml
required: ["name", "id"]
~~~
---
### Additional Properties
Controls whether extra fields not listed in `properties` are allowed. Defaults to `true`.
~~~yaml
additionalProperties: false
~~~
---
### Unevaluated Properties
Introduced in 2019-09. Applies after all other keywords are evaluated, offering finer control than `additionalProperties`.
---
### Pattern Properties
Allows defining schemas for properties that match a regex.
~~~yaml
patternProperties:
"^x-":
type: string
~~~
---
### Items
Defines schemas for array elements.
- Single schema: applies to all elements.
- Array of schemas: defines tuple validation.
~~~yaml
items:
- type: string # first element
- type: number # second element
~~~
---
### Additional Items
(Used in older drafts with tuple validation). Controls whether arrays can have extra items beyond those defined in `items`.
---
### MinItems / MaxItems
Constraints for array length.
~~~yaml
minItems: 1
maxItems: 5
~~~
---
### UniqueItems
When set to `true`, all elements in the array must be unique.
~~~yaml
uniqueItems: true
~~~
---
### Enum
Defines a set of allowed values.
~~~yaml
enum: ["red", "green", "blue"]
~~~
---
### Const
Defines a single allowed value.
~~~yaml
const: "green"
~~~
---
### OneOf
Validates against exactly one of the given subschemas.
~~~yaml
oneOf:
- type: string
- type: number
~~~
---
### AnyOf
Validates against one or more of the given subschemas.
---
### AllOf
Validates against all of the given subschemas (schema composition).
---
### Not
Schema must **not** validate against the given subschema.
~~~yaml
not:
type: string
~~~
---
### Default
Provides a suggested value, but is **informative only** (not enforced by validators).
~~~yaml
default: "guest"
~~~
---
### Format
Annotation for strings. Hints at semantic meaning, e.g. `date-time`, `email`, `uuid`. Enforcement depends on the validator.
---
### Pattern
A regex that string values must match. Uses ECMA-262 (JavaScript-style) regex.
~~~yaml
pattern: "^[A-Z]{3}-[0-9]{4}$"
~~~
---
### Minimum / Maximum
Numeric constraints (inclusive by default).
~~~yaml
minimum: 0
maximum: 100
~~~
---
### Exclusive Minimum / Exclusive Maximum
Strict numeric bounds.
~~~yaml
exclusiveMinimum: 0
exclusiveMaximum: 100
~~~
---
### MultipleOf
Number must be a multiple of the given value.
~~~yaml
multipleOf: 5
~~~
---
### MinLength / MaxLength
String length constraints.
~~~yaml
minLength: 3
maxLength: 50
~~~
---
### Dependencies (deprecated)
In draft-07, defined property dependencies. Replaced by `dependentSchemas` and `dependentRequired`.
---
### Dependent Schemas
Introduced in 2019-09. Requires a property to imply additional schema validation.
~~~yaml
dependentSchemas:
credit_card:
required: ["billing_address"]
~~~
---
### Dependent Required
Introduced in 2019-09. Requires certain other properties if one is present.
~~~yaml
dependentRequired:
password: ["passwordConfirmation"]
~~~
---
### Title
A short, human-readable description of the schema. Annotation only.
---
### Description
Longer, human-readable description. Annotation only.
---
### Examples
Illustrative example values. Annotation only.
~~~yaml
examples:
- "alice"
- "bob"
~~~
---
### Annotations vs Assertions
- **Assertions**: enforce validation (e.g., `type`, `minimum`, `required`).
- **Annotations**: metadata only (e.g., `title`, `description`, `default`).
---
