← Все статьи

Отсутствующее поле и null в JSON Schema: как задать разные правила

· 8 мин чтения

Разбираем различие между отсутствием поля и значением null в JSON Schema 2020-12. Показываем, как настроить in и required, чтобы запретить или разрешить оба состояния. Приводим примеры схем, матрицу допустимых значений и типичные ошибки конфигурации.

Валидация JSON-сообщений часто ломается на граничном случае: клиент отправляет объект, где поле отсутствует, или присылает явный null. В JavaScript эти состояния иногда смешиваются, но в JSON Schema это принципиально разные вещи. Если схема требует наличие ключа (required), но не запрещает значение null, сообщение с {"status": null} пройдёт проверку, даже если бизнес-логика ожидает конкретную строку. Или наоборот: если поле не указано в required, но вы хотите, чтобы при наличии оно обязательно было строкой, а не null, стандартная настройка type: "string" может вести себя неожиданно в зависимости от версии схемы.

Семантика отсутствия и null

В JSON объект представляет собой словарь пар «ключ-значение». Отсутствие ключа означает, что пары с этим именем нет в объекте вовсе. Значение null — это одна из шести базовых типов JSON (alongside string, number, boolean, object, array). Это фундаментальное различие определяет поведение ключевых слов JSON Schema.

Ключевое слово required управляет только наличием ключа. Если поле включено в массив required, объект будет невалидным, если этот ключ отсутствует. Однако required ничего не говорит о том, какое значение должно стоять в этом ключе. Оно может быть любым, допускаемым другими ограничениями, включая null, если тип позволяет.

Ключевое слово type управляет значением. Если указан "type": "string", значение должно быть строкой. Значение null имеет тип "null". Таким образом, если поле присутствует, но равно null, и в схеме указано "type": "string", валидация завершится ошибкой, потому что тип не совпадает. Но если поле отсутствует, проверка типа вообще не запускается, так как нет значения, которому можно сопоставить тип.

Настройка обязательности и типа

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

Рассмотрим поле email. Допустим, бизнес-правило гласит: e-mail обязателен для регистрации, но может быть пустым (null) для гостей, которые не указали почту, но создали профиль. Или правило: e-mail либо отсутствует, либо является валидной строкой, но null запрещено.

Вариант 1: Поле обязательно, null запрещено.

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

Здесь required: ["email"] гарантирует, что ключ существует. "type": "string" гарантирует, что значение является строкой. Следовательно:

  • {"email": "test@example.com"} — валидно.
  • {"email": null} — невалидно (тип null != string).
  • {} — невалидно (отсутствует обязательное поле).

Вариант 2: Поле необязательно, но если присутствует, null запрещено.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    }
  }
}

Здесь нет required. Ключ может отсутствовать. Если ключ присутствует, значение должно быть строкой.

  • {"email": "test@example.com"} — валидно.
  • {"email": null} — невалидно (тип null != string).
  • {} — валидно (поле необязательное).

Вариант 3: Поле необязательно, null разрешён.

Здесь возникает нюанс версии JSON Schema. В спецификации JSON Schema Draft 4 и ранее, а также в некоторых реализациях, использование "type": "string" могло подразумевать, что null не допускается, если не указано иное. Однако в современных версиях (Draft 7, 2019-09, 2020-12) поведение строго следует спецификации: тип "string" исключает null. Чтобы разрешить null для поля, которое также может быть строкой, нужно явно указать объединение типов или использовать nullable (в OpenAPI 3.0) или перечислить типы (в OpenAPI 3.1 / JSON Schema 2020-12).

В чистом JSON Schema 2020-12 нет ключевого слова nullable. Чтобы разрешить null и string, используйте массив типов:

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

Теперь:

  • {"email": "test@example.com"} — валидно.
  • {"email": null} — валидно.
  • {} — валидно.

Особенности OpenAPI и union types

При работе с OpenAPI важно различать версии спецификации. В OpenAPI 3.0 используется JSON Schema Draft 4 (с некоторыми расширениями). В этой версии нет нативной поддержки union types через массив в type. Вместо этого используется флаг nullable: true.

# OpenAPI 3.0
components:
  schemas:
    User:
      type: object
      properties:
        email:
          type: string
          nullable: true

Этот флаг указывает, что значение может быть null. Без него type: string подразумевает, что null недопустим.

В OpenAPI 3.1 используется JSON Schema 2020-12 напрямую. Здесь флаг nullable больше не поддерживается. Вместо него используется механизм union types: type: ["string", "null"]. Смешивание этих подходов приводит к ошибкам валидации или игнорированию ограничений.

Матрица допустимых значений

Ниже представлена матрица для поля field в зависимости от настроек схемы. Предположим, базовый тип — string.

Настройка схемы Поле отсутствует Поле = null Поле = "value" Комментарий
required: [], type: "string" ✅ Валидно ❌ Невалидно ✅ Валидно Поле опциональное, null запрещён типом
required: ["field"], type: "string" ❌ Невалидно ❌ Невалидно ✅ Валидно Поле обязательное, null запрещён типом
required: [], type: ["string", "null"] ✅ Валидно ✅ Валидно ✅ Валидно Поле опциональное, null разрешён union type
required: ["field"], type: ["string", "null"] ❌ Невалидно ✅ Валидно ✅ Валидно Поле обязательное, null разрешён union type
required: [], type: "string", nullable: true (OAS 3.0) ✅ Валидно ✅ Валидно ✅ Валидно OpenAPI 3.0 расширение

Обратите внимание: во всех случаях, где type включает только "string", значение null считается невалидным, независимо от статуса required. Разница заключается только в том, будет ли ошибка вызвана отсутствием ключа или несоответствием типа.

Типичные ошибки и ловушки

1. Ошибка: Использование nullable: true в OpenAPI 3.1. Инструменты генерации кода и валидаторы, основанные на JSON Schema 2020-12, могут игнорировать этот флаг или выдавать ошибку. Всегда используйте type: ["string", "null"] для OAS 3.1.

2. Ошибка: Путаница с default и const. Если вы задаёте "default": null, это не делает null валидным значением. default — это подсказка для клиента, а не ограничение валидации. Валидность определяется исключительно type и enum/const.

3. Ошибка: Игнорирование версии схемы. Если ваш проект использует JSON Schema Draft 4, массив type: ["string", "null"] может работать, но поведение некоторых других ключевых слов (например, format) может отличаться от 2020-12. Убедитесь, что ваша библиотека валидации поддерживает заявленную версию.

4. Ошибка: Проверка формата. Ключевое слово format (например, "email") по умолчанию не является ограничением валидации в JSON Schema. Оно служит только информационным целям. Если вам критично, чтобы e-mail был валидным, используйте сторонние плагины или regex-паттерны, понимая, что это выходит за рамки базовой спецификации.

Практический пример: Профиль пользователя

Давайте спроектируем схему для профиля пользователя в учебной системе. Требования:

  • username — обязательная строка, null запрещён.
  • bio — необязательное поле. Может отсутствовать, может быть строкой, может быть null (пользователь сознательно очистил био).
  • avatar_url — необязательное поле. Может отсутствовать или быть строкой. Null запрещён (если аватар удалён, поле просто удаляется, а не ставится null).

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "UserProfile",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 3
    },
    "bio": {
      "type": ["string", "null"]
    },
    "avatar_url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": ["username"],
  "additionalProperties": false
}

Проверим несколько сценариев:

  1. {"username": "alice", "bio": null, "avatar_url": "http://example.com/a.png"} — ✅ Валидно. Username есть, bio null (разрешено), avatar_url строка (разрешено).
  2. {"username": "bob"} — ✅ Валидно. Bio и avatar_url отсутствуют (не требуются).
  3. {"username": "charlie", "bio": null, "avatar_url": null} — ❌ Невалидно. Avatar_url имеет тип string, null не входит в допустимые типы.
  4. {"username": "dave", "bio": "Hello"} — ✅ Валидно.
  5. {"username": null} — ❌ Невалидно. Username требуется и должен быть строкой.

Этот пример демонстрирует, как точное сочетание required и type (или union type) позволяет реализовать различные бизнес-семантики: «отсутствие = не задано», «null = явно очищено», «строка = значение задано».

Проверка и отладка

Для проверки схем рекомендуется использовать онлайн-валидаторы или локальные инструменты. При отладке обращайте внимание на сообщения об ошибках: большинство библиотек (ajv, jsonschema в Python, etc.) явно указывают, нарушено ли требование required или требование type.

Частая ситуация: тест проходит, но в продакшене падают запросы. Причина может быть в том, что фронтенд отправляет null для пустых полей, а бэкенд ожидает отсутствия ключа. Или наоборот. Явная фиксация контракта через JSON Schema и его проверка на этапе CI/CD предотвращают такие расхождения.

Ограничения и рекомендации

JSON Schema не позволяет выражать сложные логические зависимости между полями без использования allOf, anyOf или if/then/else. Например, если type равен "premium", то discount_code обязателен. Такие условные логики усложняют схему и снижают читаемость. Используйте их только когда бизнес-правила действительно требуют такой гибкости.

Также помните, что JSON Schema описывает структуру данных, а не их бизнес-смысл. Значение null может означать «неизвестно», «не задано» или «нулевое значение» в зависимости от контекста приложения. Документируйте семантику null в вашей внутренней документации, так как сама схема этого не передаёт.

Для работы с такими моделями удобно использовать редактор JSON Schema, который позволяет визуально настраивать типы и обязательность полей. Более широкий контекст о выборе форматов описания данных можно найти в статье JSON Schema vs XSD.