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

Валидация структуры объекта в JSON Schema включает не только проверку типов и форматов, но и контроль «плотности» данных — количества допустимых или обязательных полей. В Ajv этот механизм реализуется через ключевые ограничения maxProperties и minProperties, которые позволяют задавать верхнюю и нижнюю границу количества свойств в объекте.

maxProperties: ограничение максимального числа свойств

Свойство maxProperties задаёт предельное количество ключей в объекте. Если объект содержит больше свойств, чем указано, валидация считается неуспешной.

Базовый пример схемы

{
  "type": "object",
  "maxProperties": 3
}

В данной схеме объект может содержать не более трёх ключей любого типа и названия.

Пример валидного и невалидного объекта

const schema = {
  type: "object",
  maxProperties: 2
};

Валидные данные:

{ a: 1, b: 2 }

Невалидные данные:

{ a: 1, b: 2, c: 3 }

Ajv при нарушении ограничения формирует ошибку с указанием ключевого правила maxProperties.

minProperties: минимальное количество свойств

Ограничение minProperties задаёт минимально допустимое число ключей. Объект должен содержать не менее указанного количества свойств, иначе он считается невалидным.

Пример схемы

{
  "type": "object",
  "minProperties": 1
}

Поведение при валидации

const schema = {
  type: "object",
  minProperties: 2
};

Валидный объект:

{ a: 1, b: 2 }

Невалидный объект:

{ a: 1 }

или

{}

Совместное использование minProperties и maxProperties

Оба ограничения могут использоваться одновременно для задания диапазона допустимого количества свойств.

Пример диапазона

{
  "type": "object",
  "minProperties": 2,
  "maxProperties": 4
}

Такой подход часто используется для контроля «структурной плотности» данных, когда объект не должен быть ни пустым, ни чрезмерно насыщенным полями.

Поведение Ajv при нарушении ограничений

Ajv возвращает структурированные ошибки валидации, содержащие:

  • путь к объекту (instancePath)
  • тип ошибки (keyword)
  • ожидаемое ограничение (params)
  • человекочитаемое сообщение (message)

Пример ошибки maxProperties

{
  "keyword": "maxProperties",
  "instancePath": "",
  "params": {
    "limit": 2
  },
  "message": "must NOT have more than 2 properties"
}

Пример ошибки minProperties

{
  "keyword": "minProperties",
  "instancePath": "",
  "params": {
    "limit": 2
  },
  "message": "must NOT have fewer than 2 properties"
}

Взаимодействие с additionalProperties

Ограничение количества свойств часто используется совместно с additionalProperties. Однако между ними существует принципиальная разница:

  • maxProperties ограничивает общее число ключей
  • additionalProperties управляет допустимостью неизвестных ключей

Пример комбинированной схемы

{
  "type": "object",
  "maxProperties": 3,
  "additionalProperties": false,
  "properties": {
    "a": { "type": "number" },
    "b": { "type": "number" },
    "c": { "type": "number" }
  }
}

В такой схеме:

  • запрещены любые дополнительные поля
  • общее число ключей не может превышать 3

Ограничение количества свойств и частичные схемы

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

Пример конфигурации профиля пользователя

{
  "type": "object",
  "minProperties": 1,
  "maxProperties": 5,
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string" },
    "phone": { "type": "string" },
    "address": { "type": "string" },
    "age": { "type": "integer" }
  }
}

Такая схема допускает гибкость, но ограничивает избыточное расширение объекта.

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

Ограничения minProperties и maxProperties применяются только к текущему уровню объекта, а не рекурсивно.

Пример

{
  "type": "object",
  "maxProperties": 2,
  "properties": {
    "meta": {
      "type": "object",
      "maxProperties": 5
    }
  }
}

В этом случае:

  • верхний объект ограничен двумя ключами
  • вложенный объект meta имеет собственное независимое ограничение

Динамические структуры и контроль сложности

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

Применение

  • API-ответы с расширяемыми объектами
  • пользовательские конфигурации
  • формы с динамическими полями

Контроль числа свойств позволяет предотвратить:

  • переполнение структуры лишними данными
  • ошибки сериализации
  • злоупотребление API через передачу избыточных параметров

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

Проверка maxProperties и minProperties относится к дешёвым операциям. Она выполняется за линейное время относительно количества ключей объекта.

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

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

Игнорирование вложенности

Ограничение применяется только к текущему уровню объекта, что часто приводит к неверным ожиданиям при работе с вложенными структурами.

Конфликт с additionalProperties

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

Избыточное ограничение

Установка слишком низкого maxProperties делает схему негибкой и усложняет эволюцию API.

Практическое значение ограничения количества свойств

Ограничение количества свойств в Ajv и JSON Schema используется как инструмент структурного контроля данных. Оно позволяет фиксировать допустимую «сложность» объекта и предотвращать появление неожиданных расширений структуры.

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

Оглавление