Опции конструктора

Экземпляр валидатора создаётся через вызов конструктора Ajv, принимающего объект конфигурации. Именно этот объект определяет поведение движка валидации: уровень строгости, поддержку форматов, правила обработки дополнительных полей, преобразования типов и многое другое.

Базовая форма инициализации:

import Ajv from "ajv";

const ajv = new Ajv({
  strict: true,
  allErrors: true
});

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

strict

Опция управляет уровнем строгости соответствия JSON Schema спецификации.

const ajv = new Ajv({
  strict: true
});

Поведение:

  • предупреждения и ошибки при использовании устаревших или нестандартных конструкций схем
  • контроль неизвестных ключевых слов
  • проверка корректности структуры схем

Режимы:

  • true — максимальная строгость
  • false — отключение строгих проверок
  • "log" — вывод предупреждений без прерывания выполнения

Используется для выявления ошибок на этапе разработки схем.

allErrors

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

const ajv = new Ajv({
  allErrors: true
});

Поведение:

  • true — сбор всех ошибок за одну валидацию
  • false — остановка на первой найденной ошибке

При включённом режиме формируется полный список нарушений, что полезно для форм и пользовательского ввода.

strictSchema

Контроль корректности самих схем JSON Schema.

const ajv = new Ajv({
  strictSchema: true
});

При включении:

  • запрещаются неизвестные ключи в описании схем
  • проверяется соответствие стандарту JSON Schema
  • выявляются потенциальные ошибки проектирования схем

Используется для повышения надёжности схем в больших проектах.

strictTypes

Управление строгой проверкой типов данных.

const ajv = new Ajv({
  strictTypes: true
});

При активной опции:

  • типы должны строго соответствовать schema definition
  • запрещаются неявные преобразования типов
  • ошибки фиксируются при несоответствии типа значения

Особенно полезно в API-валидации, где важна строгая типизация входных данных.

coerceTypes

Автоматическое приведение типов входных данных.

const ajv = new Ajv({
  coerceTypes: true
});

Поведение:

  • строка "123" может быть преобразована в число 123
  • "true" может интерпретироваться как boolean
  • работает только для совместимых типов

Варианты:

  • true — приведение включено глобально
  • "array" — приведение только для массивов схем
  • false — отключено

Опция полезна при работе с HTTP-запросами, где данные часто приходят в виде строк.

useDefaults

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

const ajv = new Ajv({
  useDefaults: true
});

Пример схемы:

const schema = {
  type: "object",
  properties: {
    role: { type: "string", default: "user" }
  }
};

Поведение:

  • при отсутствии поля оно добавляется автоматически
  • значение берётся из default

Режимы:

  • true — добавление всех default-значений
  • "empty" — только для отсутствующих полей верхнего уровня

removeAdditional

Удаление лишних полей, не описанных в схеме.

const ajv = new Ajv({
  removeAdditional: true
});

Поведение:

  • удаляет свойства объекта, не описанные в properties
  • помогает строго контролировать структуру данных

Варианты:

  • true — удаление всегда
  • "all" — рекурсивное удаление
  • false — отключено

validateFormats

Контроль форматов данных (email, uri, date и др.).

const ajv = new Ajv({
  validateFormats: true
});

Поведение:

  • включает проверку встроенных форматов
  • позволяет расширять список через пользовательские форматы

Пример формата:

ajv.addFormat("postal-code", /^\d{6}$/);

formats

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

const ajv = new Ajv({
  formats: {
    positiveInt: /^[1-9]\d*$/
  }
});

Форматы могут быть:

  • регулярными выражениями
  • функциями валидации
  • объектами с дополнительными параметрами

keywords

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

const ajv = new Ajv({
  keywords: [
    {
      keyword: "isPositive",
      validate: (schema, data) => data > 0
    }
  ]
});

Используется для расширения языка JSON Schema.

schemaId

Определяет способ идентификации схем.

const ajv = new Ajv({
  schemaId: "auto"
});

Варианты:

  • "auto" — автоматическое определение $id или id
  • "id" — использование старого формата id
  • "$id" — современный стандарт JSON Schema

uriResolver

Настройка разрешения URI для внешних схем.

const ajv = new Ajv({
  uriResolver: customResolver
});

Используется при работе с $ref, указывающими на внешние ресурсы.

Позволяет:

  • загружать схемы по URL
  • кешировать зависимости
  • переопределять логику резолвинга

addUsedSchema

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

const ajv = new Ajv({
  addUsedSchema: true
});

Поведение:

  • сохраняет все подключённые схемы
  • предотвращает повторную компиляцию
  • оптимизирует производительность при повторном использовании

messages

Управление текстами ошибок.

const ajv = new Ajv({
  messages: true
});

При включении:

  • формируются стандартные сообщения об ошибках
  • при отключении остаются только коды ошибок

Полезно для локализации и кастомных систем логирования.

code

Опции генерации кода валидаторов.

const ajv = new Ajv({
  code: {
    es5: false,
    optimize: 1
  }
});

Параметры:

  • es5 — генерация совместимого ES5-кода
  • optimize — уровень оптимизации компиляции
  • source — включение исходного кода для отладки

logger

Управление логированием внутренних событий.

const ajv = new Ajv({
  logger: console
});

Возможности:

  • вывод предупреждений о строгих режимах
  • логирование проблем схем
  • возможность подмены логгера на кастомный

discriminateCustomRules

Расширение поведения для discriminator в сложных схемах.

const ajv = new Ajv({
  discriminateCustomRules: true
});

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

Общая структура конфигурации

Комбинирование опций формирует поведение валидатора:

const ajv = new Ajv({
  strict: true,
  allErrors: true,
  coerceTypes: true,
  useDefaults: true,
  removeAdditional: "all",
  messages: false
});

Разные комбинации позволяют адаптировать библиотеку под сценарии:

  • строгая API-валидация
  • обработка пользовательских форм
  • высокопроизводительная проверка потоковых данных
  • интеграция с внешними схемами и реестрами
Оглавление