Режимы работы

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

Включение строгого режима влияет не только на проверку данных, но и на саму валидацию схем:

  • запрещаются неизвестные ключевые слова;
  • контролируется соответствие версии спецификации;
  • сигнализируются потенциально неоднозначные конструкции;
  • уменьшается количество «молчаливых» ошибок, которые в обычном режиме игнорируются.

Основные параметры строгого режима:

  • strict — глобальное включение строгой проверки;
  • strictSchema — контроль корректности структуры схем;
  • strictTypes — строгая проверка типов;
  • strictTuples — контроль кортежей (tuple validation).

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

Режим подавления и детализации ошибок

Ajv предоставляет два принципиально разных подхода к обработке ошибок: быстрый и полный.

Быстрый режим (fast failure)

В этом режиме валидация останавливается при первой найденной ошибке. Это повышает производительность, но уменьшает информативность результата.

Характеристики:

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

Полный режим (allErrors)

Включает сбор всех ошибок, найденных при проверке объекта.

  • возвращаются все нарушения схемы;
  • увеличивается время выполнения;
  • полезен для UI-валидации и форм.

Параметр:

  • allErrors: true — сбор всех ошибок.

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

Режим приведения типов (coercion mode)

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

Пример поведения:

  • строка "123" → число 123;
  • "true" → true;
  • "0" → 0.

Ключевой параметр:

  • coerceTypes: true

Особенности режима:

  • изменения происходят до основной валидации;
  • влияет на исходный объект (мутация входных данных);
  • повышает гибкость при работе с внешними API.

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

Режим значений по умолчанию (defaults injection mode)

Ajv может автоматически добавлять значения, заданные в схеме как default.

Параметр:

  • useDefaults

Варианты поведения:

  • "empty" — добавление только при отсутствии значения;
  • "shared" — использование общих ссылок для объектов;
  • true — стандартное включение.

Особенности:

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

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

Режим обработки дополнительных свойств (additional properties mode)

Ajv контролирует поведение свойств, не описанных в схеме.

Удаление лишних полей

  • removeAdditional: true

Все свойства, не указанные в схеме, удаляются из объекта.

Запрет дополнительных свойств

  • additionalProperties: false в схеме

При таком режиме данные с лишними ключами считаются невалидными.

Комбинированный режим

Ajv позволяет сочетать оба подхода: сначала проверка, затем очистка объекта.

Особенности:

  • применяется на этапе валидации;
  • может изменять структуру входного объекта;
  • важен для API, где требуется строгий контракт данных.

Режим компиляции схем (compile mode)

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

Синхронная компиляция

  • compile(schema)

Схема преобразуется в оптимизированную функцию проверки.

Особенности:

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

Асинхронная компиляция

  • compileAsync(schema)

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

Характеристики:

  • возвращает Promise;
  • поддерживает загрузку внешних схем;
  • увеличивает гибкость при сложной архитектуре.

Режим генерации кода (code generation mode)

Ajv строит валидатор как сгенерированный JavaScript-код.

Особенности:

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

Ключевые аспекты:

  • генерация оптимизированного AST;
  • преобразование в чистую функцию;
  • возможность повторного использования кода между вызовами.

Этот режим является основой высокой производительности Ajv.

Режим работы с версиями JSON Schema

Ajv поддерживает разные версии спецификации JSON Schema:

  • Draft 07;
  • 2019-09;
  • 2020-12.

Каждый режим определяет:

  • набор доступных ключевых слов;
  • правила валидации;
  • поведение ссылок $ref;
  • поддержку форматов.

Особенности:

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

Режим контекста выполнения (runtime context mode)

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

Основные аспекты:

  • передача this в функции валидации;
  • доступ к внешним данным через контекст;
  • управление зависимыми проверками.

Параметры:

  • passContext — передача контекста в функции;
  • logger — контроль логирования;
  • code.context — доступ к внутреннему состоянию.

Этот режим важен при построении сложных систем валидации, зависящих от внешнего состояния.

Режим обработки ссылок (reference resolution mode)

Ajv активно работает с $ref и внешними схемами.

Режимы:

  • локальное разрешение ссылок;
  • глобальное резолвирование через кеш;
  • асинхронная загрузка внешних схем.

Особенности:

  • ускорение при повторном использовании схем;
  • возможность централизованного реестра схем;
  • контроль циклических зависимостей.

Режим производительности (performance-oriented mode)

В производительном режиме Ajv минимизирует любые дополнительные проверки и оптимизирует выполнение:

  • отключение расширенной диагностики;
  • упрощение обработки ошибок;
  • использование предварительно скомпилированных функций;
  • кеширование валидаторов.

Параметры, влияющие на режим:

  • отключение verbose-ошибок;
  • использование precompiled schemas;
  • отказ от runtime-валидации схем.

Этот режим применяется в системах, где валидация выполняется массово и критична по времени выполнения.

Режим расширений (keyword extension mode)

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

Особенности:

  • регистрация пользовательских keyword;
  • интеграция с кодогенерацией;
  • возможность синхронных и асинхронных проверок.

Влияние на режим работы:

  • изменяется процесс компиляции схемы;
  • добавляются новые шаги в pipeline валидации;
  • расширяется язык описания схем.

Этот режим превращает Ajv из валидатора JSON Schema в расширяемую систему проверки данных.

Оглавление