Комбинирование схем

Схемы можно комбинировать: требовать соответствия нескольким схемам сразу, хотя бы одной, ровно одной или запрещать соответствие.

Ключевое слово	Документ соответствует, если он проходит…
allOf	все схемы из списка
anyOf	хотя бы одну схему
oneOf	ровно одну схему
not	не проходит указанную схему

allOf

Используется, чтобы «расширить» общую схему: базовые поля описаны один раз, а конкретная схема добавляет свои.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "entity": {
      "type": "object",
      "properties": { "id": { "type": "integer" } },
      "required": ["id"]
    }
  },
  "allOf": [
    { "$ref": "#/$defs/entity" },
    {
      "properties": { "title": { "type": "string" } },
      "required": ["title"]
    }
  ]
}

{ "id": 7, "title": "Отчёт" }

{ "title": "Отчёт" }

anyOf

Подходит, когда значение может иметь одну из нескольких форм и неважно, сколько из них совпало.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Контакт: телефон или email",
  "anyOf": [
    { "type": "string", "format": "email" },
    { "type": "string", "pattern": "^\\+\\d{11}$" }
  ]
}

"+79161234567"

oneOf

oneOf требует, чтобы совпала ровно одна схема. Если документ подходит под две — это ошибка. Поэтому схемы в oneOf должны взаимно исключать друг друга — обычно по полю-признаку с const.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Способ доставки",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": { "const": "courier" },
        "address": { "type": "string" }
      },
      "required": ["type", "address"]
    },
    {
      "type": "object",
      "properties": {
        "type": { "const": "pickup" },
        "pointId": { "type": "integer" }
      },
      "required": ["type", "pointId"]
    }
  ]
}

{ "type": "pickup", "pointId": 15 }

{ "type": "courier", "pointId": 15 }

not

not запрещает значение, подходящее под схему. Например, любая строка, кроме пустой:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "not": { "const": "" }
}

""

Советы

• Выносите общие части в $defs и подключайте через $ref внутри allOf.
• Если после allOf нужно запретить лишние поля, используйте unevaluatedProperties: false, а не additionalProperties: false.
• Сообщения об ошибках для oneOf и anyOf бывают громоздкими: валидатор перечисляет ошибки каждой ветви. Условия if/then часто дают более понятные сообщения.