JSON-схемы

JSON-схемы описывают структуру и ограничения JSON-данных. Схема представляет собой JSON-документ, в котором задаются допустимые поля и их типы, обязательность полей, разрешенные значения и другие правила проверки.

JSON-схемы, добавленные в JSON-профиль, используются для проверки запросов, содержащих данные в формате JSON. В отличие от синтаксической проверки, которая определяет только корректность формата JSON, схема проверяет соответствие данных заданным требованиям: допустима ли такая структура, присутствуют ли обязательные поля и соответствуют ли значения установленным ограничениям.

Действия с JSON-схемами выполняются в разделе Настройки в разделе Библиотеки ➜ JSON-схемы. Вы можете создавать схемы, редактировать их и удалять, а также выполнять экспорт и импорт схем.

Создание JSON-схемы

Чтобы создать JSON-схему:

1. В разделе Библиотеки ➜ JSON-схемы нажмите Добавить. Откроется окно свойства JSON-схемы.

2. Укажите название схемы, при необходимости описание и версию спецификации.

3. В поле Содержимое схемы опишите JSON-схему.

4. Нажмите Проверить синтаксис. Если результат проверки неудовлетворительный, внесите исправления и повторно выполните проверку.

5. Сохраните изменения.

Теперь созданную JSON-схему можно использовать при настройке JSON-профиля. Подробнее об этом  — в разделе «Создание JSON-профиля».

Общие сведения о JSON-схемах

Любая JSON-схема — это JSON-объект с ключевыми словами (ключами), описывающими ограничения.  Основные четыре ключа:

• schema — указывает версию спецификации схемы.

• type — тип данных (объект, строка, число и т. д.);

• properties — описание полей объекта, где каждый ключ — имя поля, а значение — подсхема для этого поля.;

• required — массив имен полей, которые должны присутствовать.

Ключ type ограничивает допустимый тип значения. Возможные типы:

• "string" — строка;

• "number" — число (целое или с плавающей точкой);

• "integer" — целое число (без дробной части);

• "boolean" — булево значение (true или false);

• "null" — значение null;

• "object" — объект { ... };

• "array" — массив [ ... ].

Тип можно указать как строку или как массив строк, если допустимо несколько типов. 

Также JSON-схемы могут содержать ограничения для строк, чисел, массивов, в том числе вложенных, перечислений и констант.

Подробнее о структуре JSON-схем  — в спецификациях: Draft 03, Draft 04, Draft 06.

Пример JSON-схемы.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "http://example.com/user.schema.json",
  "title": "User Schema",
  "description": "Схема для описания пользователя",
  "type": "object",
  "properties": {
    "id": {
      "description": "Уникальный идентификатор пользователя",
      "type": "integer",
      "minimum": 1
    },
    "username": {
      "description": "Имя пользователя",
      "type": "string",
      "minLength": 3,
      "maxLength": 20,
      "pattern": "^[a-zA-Z0-9_]+$"
    },
    "email": {
      "description": "Email адрес",
      "type": "string",
      "format": "email"
    },
    "age": {
      "description": "Возраст пользователя",
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "isActive": {
      "description": "Статус активности",
      "type": "boolean"
    },
    "roles": {
      "description": "Роли пользователя",
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["admin", "user", "guest"]
      },
      "minItems": 1,
      "uniqueItems": true
    },
    "address": {
      "description": "Адрес пользователя",
      "type": "object",
      "properties": {
        "street": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "zipCode": {
          "type": "string",
          "pattern": "^\\d{5}$"
        }
      },
      "required": ["street", "city"]
    },
    "phoneNumbers": {
      "description": "Список телефонных номеров",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["home", "work", "mobile"]
          },
          "number": {
            "type": "string"
          }
        },
        "required": ["type", "number"]
      }
    },
    "createdAt": {
      "description": "Дата создания",
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["id", "username", "email", "age"],
  "additionalProperties": false
}