Стандартные ключевые слова

Валидация JSON Schema в Ajv строится на интерпретации набора базовых ключевых слов спецификации. Эти ключевые слова определяют структуру, ограничения типов данных, правила валидации объектов, массивов и примитивов, а также позволяют комбинировать схемы в сложные логические конструкции.

type

Ключевое слово type задаёт ожидаемый тип значения.

Поддерживаются стандартные JSON-типы:

  • string
  • number
  • integer
  • boolean
  • object
  • array
  • null

Пример:

{
  "type": "string"
}

При проверке Ajv отклоняет значения, не соответствующие указанному типу. Возможно указание нескольких типов:

{
  "type": ["string", "null"]
}

Это означает допустимость строки или null.

properties

Ключевое слово properties применяется к объектам и описывает допустимые поля.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  }
}

Каждое свойство внутри объекта валидируется по собственной схеме.

Если свойство отсутствует в объекте, оно просто не проверяется, если не указано обязательным.

required

Ключевое слово required определяет обязательные поля объекта.

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "email": { "type": "string" }
  },
  "required": ["id", "email"]
}

Отсутствие любого поля из списка приводит к ошибке валидации.

Важно: required применяется только к именам свойств, а не к их значениям.

additionalProperties

Ключевое слово additionalProperties управляет поведением неизвестных полей.

{
  "type": "object",
  "properties": {
    "id": { "type": "string" }
  },
  "additionalProperties": false
}

При значении false любые свойства, не описанные в properties, запрещаются.

Также допускается схема:

{
  "additionalProperties": {
    "type": "string"
  }
}

В этом случае все дополнительные поля должны соответствовать указанной схеме.

items

Ключевое слово items применяется к массивам и описывает элементы.

Однородные массивы:

{
  "type": "array",
  "items": {
    "type": "number"
  }
}

Каждый элемент массива должен быть числом.

Также поддерживается разная схема для разных позиций:

{
  "type": "array",
  "items": [
    { "type": "string" },
    { "type": "number" }
  ]
}

enum

Ключевое слово enum ограничивает значение фиксированным набором допустимых вариантов.

{
  "type": "string",
  "enum": ["red", "green", "blue"]
}

Значение должно строго совпадать с одним из элементов массива.

Ajv выполняет строгое сравнение без приведения типов.

const

Ключевое слово const задаёт единственное допустимое значение.

{
  "const": 42
}

Любое значение, отличное от указанного, считается невалидным.

В отличие от enum, допускается только одно фиксированное значение.

minimum и maximum

Ключевые слова minimum и maximum применяются к числовым значениям.

{
  "type": "number",
  "minimum": 10,
  "maximum": 20
}

Проверяется диапазон включительно.

Дополнительно используются:

  • exclusiveMinimum
  • exclusiveMaximum

Пример:

{
  "type": "number",
  "exclusiveMinimum": 0,
  "exclusiveMaximum": 100
}

minLength и maxLength

Ключевые слова minLength и maxLength применяются к строкам.

{
  "type": "string",
  "minLength": 3,
  "maxLength": 10
}

Проверяется количество символов строки.

Unicode-символы учитываются как единицы длины.

pattern

Ключевое слово pattern задаёт регулярное выражение, которому должна соответствовать строка.

{
  "type": "string",
  "pattern": "^[a-zA-Z0-9_]+$"
}

Ajv использует JavaScript RegExp, поэтому поддерживаются все особенности движка V8.

Регулярное выражение применяется к всей строке, если не указаны якоря.

allOf, anyOf, oneOf, not

Логические операторы позволяют комбинировать схемы.

allOf

Все схемы должны быть валидны:

{
  "allOf": [
    { "type": "string" },
    { "minLength": 5 }
  ]
}

anyOf

Должна соответствовать хотя бы одна схема:

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

oneOf

Строго одна схема должна быть валидной:

{
  "oneOf": [
    { "const": "A" },
    { "const": "B" }
  ]
}

not

Инверсия схемы:

{
  "not": {
    "type": "number"
  }
}

format

Ключевое слово format используется для проверки строковых форматов.

{
  "type": "string",
  "format": "email"
}

Поддерживаются стандартные форматы:

  • email
  • uri
  • date
  • date-time
  • ipv4
  • ipv6

Ajv допускает расширение через кастомные форматы, что позволяет подключать собственные валидаторы.

dependencies

Ключевое слово dependencies задаёт зависимости между полями объекта.

Свойства-зависимости:

{
  "type": "object",
  "properties": {
    "creditCard": { "type": "string" },
    "billingAddress": { "type": "string" }
  },
  "dependencies": {
    "creditCard": ["billingAddress"]
  }
}

Если присутствует creditCard, обязательно наличие billingAddress.

Также возможна схема-зависимость:

{
  "dependencies": {
    "creditCard": {
      "required": ["billingAddress"]
    }
  }
}

minItems и maxItems

Ключевые слова для массивов:

{
  "type": "array",
  "minItems": 1,
  "maxItems": 5
}

Определяют допустимую длину массива.

uniqueItems

Ключевое слово uniqueItems обеспечивает уникальность элементов массива.

{
  "type": "array",
  "uniqueItems": true
}

Сравнение выполняется по строгому равенству значений.

multipleOf

Ключевое слово multipleOf задаёт кратность числа.

{
  "type": "number",
  "multipleOf": 5
}

Значение должно быть кратным 5.

if, then, else

Условная логика позволяет строить зависимые схемы.

{
  "if": {
    "properties": { "type": { "const": "admin" } }
  },
  "then": {
    "required": ["permissions"]
  },
  "else": {
    "required": ["role"]
  }
}

Эта конструкция позволяет изменять правила валидации в зависимости от входных данных.

Оглавление