# JSON Schema validation: common keywords with examples

JSON Schema is a vocabulary for describing and validating JSON documents. An API can use one schema to check incoming requests, generate forms, or document its payloads. This reference covers the keywords used most often, each with a working example. Examples follow the 2020-12 specification; most also work in draft-07.

A schema is itself JSON. The `$schema` keyword declares which specification version it uses:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Product",
  "type": "object"
}
```

## The core keywords

@sheet Keywords
@style A1:C1: bold
@width A: 160
@width B: 130
@width C: 400
| Keyword | Applies to | What it checks |
| --- | --- | --- |
| type | any | The JSON type: string, number, integer, boolean, object, array, null |
| required | object | Named properties that must be present |
| properties | object | A schema for each named property |
| additionalProperties | object | Whether extra properties beyond the named ones are allowed |
| minLength, maxLength | string | String length in characters |
| pattern | string | The string matches a regular expression |
| format | string | A known shape such as email, date, uri (annotation only in many validators) |
| minimum, maximum | number | Inclusive numeric bounds (exclusiveMinimum / exclusiveMaximum for strict) |
| enum | any | The value is one of a fixed list |
| const | any | The value equals exactly one given value |
| items | array | A schema that every element must match |
| minItems, maxItems | array | Array size bounds |
| uniqueItems | array | No two elements are equal |
| $ref | any | Reuse another schema by URI |
| oneOf, anyOf, allOf | any | Combine schemas: exactly one, at least one, or all must match |
@endsheet

## A complete example

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Product",
  "type": "object",
  "properties": {
    "productId": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1, "maxLength": 100 },
    "price": { "type": "number", "exclusiveMinimum": 0 },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true
    },
    "status": { "enum": ["draft", "live", "archived"] }
  },
  "required": ["productId", "name", "price"],
  "additionalProperties": false
}
```

This passes validation:

```json
{ "productId": 1, "name": "A green door", "price": 12.50, "tags": ["home", "green"] }
```

This fails three rules: price is not above zero, `tags` has a duplicate, and `colour` is not a declared property:

```json
{ "productId": 1, "name": "A green door", "price": 0, "tags": ["home", "home"], "colour": "green" }
```

## Combining schemas

- `allOf`: every listed schema must match. Used to layer constraints.
- `anyOf`: at least one must match. Used for "string or number" fields.
- `oneOf`: exactly one must match. Stricter than anyOf; useful for mutually exclusive shapes.

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

## Reusing definitions with $ref

Define a piece once under `$defs` and point at it:

```json
{
  "$defs": {
    "positiveInt": { "type": "integer", "minimum": 1 }
  },
  "type": "object",
  "properties": {
    "quantity": { "$ref": "#/$defs/positiveInt" },
    "reorderLevel": { "$ref": "#/$defs/positiveInt" }
  }
}
```

## Practical notes

- A property that is absent is not checked by `properties`; only `required` forces presence.
- `format` (email, date-time, uri) is an annotation in the 2020-12 spec by default: validators may report it but are not required to reject bad values unless format assertion is enabled.
- Validation only checks shape and values. It does not check that an id exists in a database or that a price is correct.
- Test a schema with a validator in your language (for example Ajv for JavaScript or the `jsonschema` package for Python) before relying on it in production.

Source: JSON Schema documentation at https://json-schema.org/learn/getting-started-step-by-step and the 2020-12 specification, https://json-schema.org/draft/2020-12/json-schema-core