Документация Joi организована по принципу функциональных блоков, каждый из которых отражает отдельный уровень работы с системой валидации данных. Основная цель такой структуры — обеспечить быстрое сопоставление задачи с соответствующим методом или типом схемы без необходимости последовательного чтения всего материала.
В основе лежит разделение на несколько крупных разделов:
1. Описание базовых типов схем
Каждый тип данных в Joi представлен отдельным конструктором схемы:
string() — строкиnumber() — числаboolean() — логические значенияobject() — объектыarray() — массивыdate() — датыalternatives() — альтернативные схемыКаждый конструктор содержит набор методов, применимых только к соответствующему типу. Такое разделение снижает вероятность применения несовместимых правил.
2. Методы модификации и валидации
Методы в Joi делятся на несколько категорий:
Используются для задания диапазонов и условий допустимых данных:
min(), max() — ограничения диапазонаlength() — фиксированная длинаpattern() — регулярные выраженияgreater(), less() — сравнительные
ограниченияrequired() — обязательное полеoptional() — необязательное полеforbidden() — запрещённое полеdefault() — значение по умолчаниюtrim() — удаление пробеловlowercase(), uppercase() — изменение
регистраreplace() — замена по шаблонуcustom() — пользовательская функция преобразования3. Структура цепочек методов
Документация Joi делает акцент на цепочечном построении схем. Каждый метод возвращает новый экземпляр схемы, что позволяет последовательно наращивать ограничения:
Такой подход отражён в документации через примеры, где каждая цепочка демонстрирует эволюцию схемы от простого типа до комплексного валидатора.
4. Объектные схемы и вложенные структуры
Раздел, посвящённый object(), описывает работу с ключами
и вложенностью:
keys() — определение структуры объектаunknown() — разрешение неизвестных ключейpattern() — динамические ключиextract() — извлечение подструктурОсобое внимание уделяется вложенным схемам, где каждый уровень объекта валидируется независимо, но в рамках общей структуры.
5. Массивы и композиция схем
Раздел array() включает методы для работы с
коллекциями:
items() — описание допустимых элементовordered() — строго позиционная валидацияmin(), max() — ограничения размераunique() — контроль уникальности элементовДокументация подчёркивает возможность комбинирования схем внутри массива, включая поддержку альтернативных типов элементов.
6. Альтернативные схемы
alternatives() используется для ситуаций, где данные
могут соответствовать одному из нескольких вариантов:
try() — проверка нескольких схем последовательноconditional() — выбор схемы по условиюwhen() — зависимая логика валидацииДанный раздел демонстрирует механизм построения гибких правил, зависящих от контекста входных данных.
Отдельный блок документации описывает механизм формирования ошибок:
messages()Каждая ошибка сопровождается структурированным объектом, что позволяет интеграцию с внешними системами логирования и API-ответами.
Документация выделяет глобальные и локальные настройки:
abortEarly — остановка при первой ошибкеallowUnknown — разрешение неизвестных полейstripUnknown — удаление лишних полейconvert — автоматическое приведение типовpresence — глобальная обязательность полейЭти параметры определяют поведение схемы при обработке данных и влияют на результат валидации.
Joi поддерживает расширения через плагины:
Документация описывает структуру расширений как набор хуков, позволяющих вмешиваться в этапы валидации: построение схемы, проверка значения, формирование результата.
Каждый раздел сопровождается стандартизированными примерами:
Примеры строятся от простого к сложному, демонстрируя рост сложности без изменения базовой логики конструкции.
Справочная часть документации построена как набор независимых страниц по каждому методу:
Такая структура позволяет точечно находить информацию по конкретному методу без необходимости анализа всего API.
Все разделы документации связаны единым принципом: любой метод рассматривается в контексте схемы, к которой он применяется. Это создаёт целостную систему, где:
Подобная организация обеспечивает предсказуемость поведения библиотеки при построении сложных валидационных моделей.