Ограничения по длине

Ограничения по длине в JSON Schema формируют один из базовых механизмов контроля входных данных, особенно при валидации строк, массивов и частично объектов. В Ajv эти ограничения реализуются строго в соответствии со спецификацией JSON Schema Draft 7/2019-09/2020-12, что обеспечивает предсказуемое поведение при проверке структур данных.

Ограничения длины строк

Для строк используются ключевые слова minLength и maxLength, которые определяют допустимый диапазон длины строки в символах.

const schema = {
  type: "string",
  minLength: 5,
  maxLength: 10
};

const ajv = new Ajv();
const validate = ajv.compile(schema);

validate("hello");      // true
validate("hi");         // false (слишком короткая строка)
validate("very long string"); // false (слишком длинная)

Особенности подсчёта длины

Важный аспект заключается в том, что длина строки в JSON Schema определяется количеством Unicode-символов, а не байтов. Это приводит к следующим нюансам:

  • символы ASCII и кириллица считаются как единицы длины;
  • эмодзи и суррогатные пары могут учитываться как один символ или пара кодовых единиц в зависимости от среды выполнения;
  • нормализация Unicode (NFC/NFD) может влиять на фактическое восприятие длины.

В контексте Ajv проверка опирается на внутреннее представление строки JavaScript, а не на байтовую длину.

Ограничения длины массивов

Для массивов используются minItems и maxItems, определяющие допустимое количество элементов.

const schema = {
  type: "array",
  minItems: 2,
  maxItems: 4
};

const ajv = new Ajv();
const validate = ajv.compile(schema);

validate([1]);           // false
validate([1, 2]);        // true
validate([1, 2, 3, 4]);  // true
validate([1, 2, 3, 4, 5]); // false

Влияние структуры элементов

Ограничения применяются к количеству элементов, независимо от их типа:

  • примитивы (числа, строки);
  • вложенные объекты;
  • смешанные массивы.

Дополнительно часто комбинируются с items, prefixItems и additionalItems, что позволяет задавать строгую структуру массива вместе с ограничением длины.

Ограничения количества свойств объектов

Хотя термин “длина” чаще относится к строкам и массивам, в JSON Schema аналогичный механизм применяется к объектам через minProperties и maxProperties.

const schema = {
  type: "object",
  minProperties: 1,
  maxProperties: 3
};

const ajv = new Ajv();
const validate = ajv.compile(schema);

validate({}); // false
validate({ a: 1 }); // true
validate({ a: 1, b: 2, c: 3 }); // true
validate({ a: 1, b: 2, c: 3, d: 4 }); // false

В Ajv подсчёт свойств ведётся по собственным enumerable keys объекта.

Комбинирование ограничений длины

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

const schema = {
  type: "string",
  minLength: 3,
  maxLength: 8,
  pattern: "^[a-zA-Z]+$"
};

Такой подход позволяет одновременно:

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

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

Поведение при ошибках валидации

При нарушении ограничений длины Ajv формирует структурированное сообщение об ошибке, содержащее:

  • тип нарушения (minLength, maxLength, minItems, maxItems);
  • фактическое значение;
  • ожидаемые границы.

Пример типичного результата:

{
  "instancePath": "",
  "keyword": "minLength",
  "message": "must NOT have fewer than 5 characters",
  "params": {
    "limit": 5
  }
}

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

Производительность проверок длины

Проверки длины относятся к дешёвым операциям, так как:

  • вычисление длины строки выполняется за O(n), но обычно оптимизировано в JS-движках;
  • подсчёт элементов массива или свойств объекта выполняется через прямой обход структуры;
  • в Ajv такие проверки интегрированы в компилированную функцию валидации.

Тем не менее, при работе с очень большими структурами:

  • массивы с десятками тысяч элементов;
  • строки высокой длины (например, JSON-документы);

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

Ограничения длины и строгая типизация

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

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

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

Типовые ошибки при использовании ограничений

Распространённые проблемы:

  • использование minLength для чисел вместо строк;
  • ожидание байтовой длины вместо символов Unicode;
  • неправильная оценка длины при наличии эмодзи;
  • несоответствие между minItems и бизнес-логикой (например, обязательные поля массива).

Такие ошибки часто приводят к некорректной валидации даже при правильно составленной схеме.

Практическая композиция ограничений

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

const schema = {
  type: "array",
  minItems: 1,
  maxItems: 10,
  items: {
    type: "string",
    minLength: 2,
    maxLength: 20
  }
};

Такой подход задаёт многоуровневую валидацию:

  • ограничение общего количества элементов;
  • ограничение длины каждого элемента;
  • контроль типа данных.

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

Оглавление