CLI аргументы

Библиотека Ajv предоставляет не только API для JavaScript-кода, но и полноценный CLI-инструмент через пакет ajv-cli, предназначенный для валидации данных, компиляции схем и интеграции в сборочные процессы.

CLI строится вокруг работы с JSON Schema и позволяет выполнять операции без написания кода, используя набор аргументов командной строки.

Установка и структура CLI-инструмента

CLI доступен через отдельный пакет:

npm install -g ajv-cli

После установки становится доступной команда:

ajv

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

  • валидация данных (validate)
  • компиляция схем (compile)
  • проверка схем и данных в пакетном режиме
  • генерация объединённых модулей

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

Валидация данных

Режим validate используется для проверки JSON-данных относительно схемы.

ajv validate -s schema.json -d data.json

Параметры:

  • -s, --schema — путь к JSON Schema
  • -d, --data — путь к проверяемым данным
  • допускается использование glob-паттернов для множественных файлов

При успешной проверке процесс завершается с кодом 0, при ошибке — ненулевым кодом.

Компиляция схем

Режим compile преобразует схемы в JavaScript-модуль, содержащий валидатор.

ajv compile -s schema.json -o validator.js

Параметры:

  • -o, --output — файл результата
  • -s, --schema — исходная схема
  • --es5 — генерация ES5-кода
  • --module — формат модуля (cjs, esm)

Аргументы командной строки

Работа с несколькими схемами

Поддерживается передача нескольких схем:

ajv compile -s schema1.json -s schema2.json -o bundle.js

Также допускается использование директорий и шаблонов:

ajv compile -s "schemas/**/*.json" -o bundle.js

Режим строгой проверки

Флаг --strict активирует строгий режим проверки спецификации JSON Schema.

Поведение включает:

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

Дополнительные параметры строгого режима:

  • --strict-schema
  • --strict-types
  • --strict-tuples

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

Флаг:

--all-errors

Отключает остановку на первой ошибке и собирает все найденные нарушения схемы.

Вывод ошибок структурируется в массив, содержащий:

  • путь к данным
  • описание нарушения
  • ожидаемое значение
  • фактическое значение

Коэрция типов

Флаг:

--coerce-types

Включает автоматическое приведение типов при валидации:

  • строки → числа
  • строки → boolean (в ограниченных случаях)
  • преобразование массивов при необходимости

Форматы и расширения

Ajv поддерживает подключение дополнительных форматов:

--formats custom-formats.js

И пользовательских ключевых слов:

--keywords custom-keywords.js

Механизм расширений подключается в момент компиляции схемы и влияет на генерацию валидатора.

Формат вывода

Поддерживаются различные форматы результатов:

  • text — человекочитаемый вывод
  • json — структурированный вывод
  • stylish — формат с группировкой ошибок

Пример:

ajv validate -s schema.json -d data.json --errors=json

Использование стандартного ввода

Допускается передача данных через stdin:

cat data.json | ajv validate -s schema.json

Или:

ajv validate -s schema.json -d -

Exit-коды CLI

CLI использует стандартную систему кодов завершения:

  • 0 — успешная валидация
  • 1 — ошибки в данных
  • 2 — ошибки схемы или конфигурации
  • 3 — внутренняя ошибка исполнения

Компиляция в связанный модуль

Режим bundling используется для генерации единого файла валидаторов:

ajv compile -s schema.json --bundle -o bundle.js

В этом режиме:

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

Производительность CLI-операций

CLI оптимизирован под:

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

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

Типовые сценарии применения аргументов

Массовая валидация файлов

ajv validate -s schema.json -d "data/**/*.json" --all-errors

Компиляция схемы с расширениями

ajv compile -s schema.json --keywords custom.js --formats formats.js -o validator.js

Генерация строгого валидатора

ajv compile -s schema.json --strict --coerce-types -o validator.js

Структура ошибок CLI

При валидации ошибки формируются в виде массива объектов:

[
  {
    "instancePath": "/user/age",
    "keyword": "type",
    "message": "must be number",
    "params": {
      "type": "number"
    }
  }
]

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

Работа с несколькими окружениями схем

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

  • development
  • staging
  • production

Используются разные наборы аргументов:

ajv validate -s schema.prod.json -d data.json --strict
ajv validate -s schema.dev.json -d data.json --all-errors

Особенности интерпретации аргументов

CLI разбирает параметры в следующем порядке:

  1. глобальные опции
  2. режим работы (validate/compile)
  3. схемы и данные
  4. дополнительные расширения
  5. формат вывода

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

Оглавление