Валидация email, uri, date-time

В библиотеке Ajv проверка строковых форматов реализуется через ключевое слово format, входящее в спецификацию JSON Schema. Форматы применяются поверх базовых типов и позволяют задавать семантические ограничения: корректность email-адресов, URI, временных меток и других структурированных строк.

Механизм форматной проверки в Ajv не является частью ядра строгой спецификации JSON Schema Draft-07/2019-09/2020-12 в виде обязательной логики исполнения. Поддержка форматов подключается отдельно и может быть расширена через плагины, наиболее распространённый из которых — ajv-formats.

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

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

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

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

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

Валидация email

Формат email используется для проверки строк, соответствующих синтаксису электронных адресов согласно RFC 5322 (с упрощениями на практике).

Схема JSON Schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["email"]
}

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

const schema = {
  type: "object",
  properties: {
    email: { type: "string", format: "email" }
  },
  required: ["email"]
};

const validate = ajv.compile(schema);

validate({ email: "test@example.com" }); // true
validate({ email: "invalid-email" });    // false

Особенности проверки email

Форматная проверка email в Ajv ориентирована на синтаксическую корректность:

  • наличие локальной части и домена
  • допустимые символы в имени
  • корректное разделение @

При этом не выполняется проверка существования домена или почтового ящика, так как это выходит за пределы JSON Schema.

Валидация uri

Формат uri применяется для проверки унифицированных идентификаторов ресурсов.

URI включает схемы http, https, ftp, mailto и другие согласно RFC 3986.

Схема

{
  "type": "object",
  "properties": {
    "website": {
      "type": "string",
      "format": "uri"
    }
  }
}

Пример

const schema = {
  type: "object",
  properties: {
    website: { type: "string", format: "uri" }
  }
};

const validate = ajv.compile(schema);

validate({ website: "https://example.com" }); // true
validate({ website: "not a url" });           // false

Поведение проверки URI

Формат uri в Ajv учитывает:

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

Не выполняется сетевое разрешение адреса и проверка доступности ресурса.

Валидация date-time

Формат date-time предназначен для проверки строк, соответствующих стандарту ISO 8601.

Типичный пример:

2026-05-10T14:30:00Z

Схема

{
  "type": "object",
  "properties": {
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}

Пример проверки

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

const validate = ajv.compile(schema);

validate({ createdAt: "2026-05-10T14:30:00Z" }); // true
validate({ createdAt: "10-05-2026" });          // false

Требования формата date-time

В Ajv проверка учитывает строгую структуру ISO 8601:

  • календарная дата (YYYY-MM-DD)
  • разделитель T
  • время (HH:mm:ss)
  • опциональные миллисекунды
  • временная зона (Z или смещение +hh:mm)

Допустимые варианты:

  • 2026-05-10T14:30:00Z
  • 2026-05-10T14:30:00+05:00
  • 2026-05-10T14:30:00.123Z

Недопустимые варианты:

  • 2026/05/10 14:30
  • 10-05-2026
  • 2026-05-10

Строгая и неблокирующая природа форматной валидации

Форматы в Ajv могут работать в нескольких режимах:

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

Форматная проверка не заменяет базовую типизацию JSON Schema. Комбинация type + format обеспечивает более точное ограничение данных:

{
  "type": "string",
  "format": "email",
  "minLength": 5,
  "maxLength": 254
}

Кастомизация форматов

Ajv позволяет добавлять собственные форматы:

ajv.addFormat("even-number", {
  type: "number",
  validate: (n) => n % 2 === 0
});

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

{
  "type": "number",
  "format": "even-number"
}

Этот механизм работает аналогично встроенным форматам email, uri, date-time, расширяя систему проверки без изменения схемы JSON Schema.

Роль форматов в архитектуре валидации

Форматы в Ajv выполняют функцию семантического слоя поверх синтаксической валидации. Их использование позволяет:

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

Комбинация стандартных форматов обеспечивает базовый набор правил для большинства прикладных API: идентификация пользователей (email), навигация (uri), временные метки (date-time).

Оглавление