Введение

JSON Schema — язык, на котором описывают, какими должны быть данные в формате JSON: какие поля есть у объекта, какого они типа, какие обязательны, в каком диапазоне лежат числа и по какому шаблону строятся строки. Сама схема — тоже JSON-документ. Схемы используют для проверки запросов и ответов API (на них основаны модели данных OpenAPI и AsyncAPI), конфигурационных файлов и сообщений в очередях, а также для генерации форм и документации.

Первая схема

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "title": "Товар",
  "description": "Товар из каталога интернет-магазина",
  "type": "object",
  "properties": {
    "productId": {
      "description": "Уникальный идентификатор товара",
      "type": "integer"
    },
    "name": {
      "description": "Название товара",
      "type": "string",
      "minLength": 1
    },
    "price": {
      "description": "Цена в рублях",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "tags": {
      "description": "Метки товара",
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true
    }
  },
  "required": ["productId", "name", "price"]
}

Документ, который соответствует схеме:

{
  "productId": 1,
  "name": "Кофемолка",
  "price": 3490,
  "tags": ["кухня", "техника"]
}

А этот — нет: цена отрицательная, а метки повторяются.

{
  "productId": 2,
  "name": "Чайник",
  "price": -10,
  "tags": ["кухня", "кухня"]
}

Как устроена проверка

Схема состоит из ключевых слов — полей вроде type, properties, minimum. Каждое ключевое слово — отдельное правило, и документ соответствует схеме, только если выполнены все правила. Ключевые слова делятся на:

• утверждения (assertions) — проверки: type, minLength, required, enum;
• аннотации (annotations) — описания, которые не влияют на проверку: title, description, default, examples;
• применители (applicators) — ключевые слова, которые применяют вложенные схемы к частям документа или комбинируют схемы: properties, items, allOf, if.

Пустая схема {} разрешает любой JSON. Схема true означает то же самое, а схема false не пропускает ничего — это удобно, например, чтобы запретить какое-то поле.

В редакторе

Откройте пример в редакторе JSON Schema: слева — код схемы, справа — её структура в виде дерева и форма проверки документа. Вставьте JSON в поле проверки, и редактор покажет, какие правила нарушены и где. Версию стандарта редактор определяет по $schema: поддерживаются 2020-12 (и 2019-09) и draft-07.

Разделы документации

• Типы данных — type, строки, числа, логические значения и null.
• Объекты и Массивы — свойства, обязательные поля, элементы и кортежи.
• Перечисления и константы, Аннотации — enum, const, описания и значения по умолчанию.
• Комбинирование схем и Условия — allOf, anyOf, oneOf, not, if/then/else.
• Структура и ссылки — $id, $ref, $defs, многофайловые схемы.
• Версии и диалекты, Форматы и данные не в JSON — $schema, словари, format, contentEncoding.