Форматы строк

В JSON Schema строковые значения могут дополнительно проверяться не только через pattern, но и через механизм форматов. Форматы представляют собой семантические проверки, выходящие за рамки регулярных выражений: они описывают типовые структуры данных вроде email, URL, даты, UUID и других стандартизированных строковых представлений.

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

Механизм format в JSON Schema

Ключ format применяется к строковым значениям и задаёт ожидаемый семантический тип строки:

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

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

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

Встроенные форматы Ajv

Ajv поддерживает набор стандартных форматов, которые охватывают наиболее распространённые типы строк:

  • email — адрес электронной почты
  • uri — универсальный идентификатор ресурса
  • url — веб-адрес
  • uuid — идентификатор UUID
  • date — календарная дата в формате ISO 8601
  • time — время
  • date-time — дата и время ISO 8601
  • ipv4 — IPv4-адрес
  • ipv6 — IPv6-адрес
  • hostname — доменное имя

Пример использования:

const schema = {
  type: "object",
  properties: {
    email: { type: "string", format: "email" },
    website: { type: "string", format: "uri" },
    createdAt: { type: "string", format: "date-time" }
  }
};

Подключение поддержки форматов

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

import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv();
addFormats(ajv);

После подключения становятся доступны стандартные проверки форматов, включая email, uri и даты.

Различие между format и pattern

pattern опирается на регулярные выражения и проверяет строку синтаксически:

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

format проверяет семантическое соответствие:

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

Разница заключается в уровне абстракции: регулярное выражение не понимает структуру email, тогда как формат учитывает специфику адреса (локальная часть, домен, допустимые символы).

Строгость форматов и режим strict

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

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

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

Кастомные форматы

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

const ajv = new Ajv();

ajv.addFormat("lowercase", {
  type: "string",
  validate: (data) => data === data.toLowerCase()
});

Использование в схеме:

const schema = {
  type: "string",
  format: "lowercase"
};

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

Форматы с использованием регулярных выражений

Хотя format не обязан опираться на регулярные выражения, Ajv позволяет реализовать формат через RegExp:

ajv.addFormat("hexColor", /^[A-Fa-f0-9]{6}$/);

Это упрощённый способ описания строковых форматов, когда достаточно синтаксической проверки.

Форматы дат и времени

Форматы, связанные с датами, основаны на ISO 8601. Наиболее часто используемый — date-time:

{
  "type": "string",
  "format": "date-time"
}

Пример допустимого значения:

2026-05-10T14:30:00Z

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

Формат date ограничивается календарной датой:

2026-05-10

Формат time описывает только время суток:

14:30:00

Формат uri и его особенности

uri используется для проверки универсальных идентификаторов ресурсов. Валидация включает:

  • наличие схемы (http, https, ftp и др.)
  • корректную структуру адреса
  • допустимые символы в пути и query-параметрах

Пример:

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

Строка:

https://example.com/path?query=1

Отключение проверки форматов

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

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

В этом случае format перестаёт влиять на результат валидации.

Поведение при неизвестных форматах

Если формат не зарегистрирован, поведение зависит от конфигурации:

  • в стандартном режиме — формат игнорируется
  • в строгом режиме — возникает ошибка или предупреждение
  • при использовании кастомного валидатора — применяется пользовательская логика

Комбинирование format с другими ограничениями

Форматы часто используются вместе с другими ограничениями строк:

const schema = {
  type: "string",
  format: "email",
  minLength: 5,
  maxLength: 255
};

Такое сочетание позволяет одновременно контролировать:

  • структуру строки (формат)
  • диапазон длины
  • дополнительные ограничения

Асинхронные форматы

Асинхронные форматы применяются для проверок, требующих внешних запросов или базы данных:

ajv.addFormat("user-exists", {
  async: true,
  validate: async (value) => {
    const user = await db.findUser(value);
    return Boolean(user);
  }
});

Такая модель расширяет JSON Schema до уровня бизнес-логики.

Производительность форматов

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

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

Поведение при ошибках формата

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

{
  "keyword": "format",
  "instancePath": "/email",
  "message": "must match format \"email\""
}

Ошибка указывает:

  • путь до значения
  • тип нарушения (format)
  • ожидаемый формат

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

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

Оглавление