← Все статьи

required и nullable в OpenAPI: как описать отсутствующее и пустое поле

· 7 мин чтения

Разбираем разницу между отсутствием поля и значением null в OpenAPI 3.0. Показываем, как правильно настроить required и nullable, чтобы избежать ошибок валидации, и строим матрицу допустимых состояний для тестирования API.

Когда клиент отправляет POST-запрос с телом {"name": "Ivan"}, а сервер возвращает 400 Bad Request из-за отсутствия поля email, начинаются споры. Разработчик клиента говорит: «Поле не отмечено как обязательное в Swagger UI, значит, я могу его не присылать». Разработчик сервера отвечает: «В коде я проверяю presence, если ключа нет, это ошибка». Оба правы в рамках своего понимания, но оба неправы относительно контракта. Проблема кроется в том, что в OpenAPI 3.0 понятия «поле отсутствует» (missing) и «поле равно null» (null) имеют строго разные семантики, которые часто смешивают при проектировании.

Семантика ключей required и nullable

Ключ required в OpenAPI 3.0 управляет наличием имени поля в JSON-объекте. Если имя входит в массив required, клиент обязан передать этот ключ в теле запроса или получить его в ответе. Отсутствие ключа нарушает контракт. Ключ nullable управляет допустимостью значения null. Если nullable: true, поле может содержать значение null. Эти два механизма работают независимо. Поле может быть обязательным, но допускающим null (например, флаг удаления), или необязательным, но запрещающим null (если ключ передан, он должен иметь конкретное значение типа). Частая ошибка состоит в том, что аналитики считают nullable: true синонимом «поле опционально». Это неверно: если поле в required, клиент должен отправить ключ, даже если его значение будет null.

Четыре состояния поля

Для любого атрибута JSON-объекта существуют четыре дискретных состояния, которые необходимо учитывать при проектировании API:

  1. Отсутствует (Missing): ключа нет в объекте. Допустимо только если поле не указано в required.
  2. Null: ключ присутствует, значение null. Допустимо только если указано nullable: true.
  3. Пустое значение (Empty): ключ присутствует, значение соответствует типу, но является «пустым» (пустая строка "", пустой массив []). Допустимость регулируется ограничениями типа, такими как minLength или minItems.
  4. Валидное значение (Value): ключ присутствует, значение соответствует типу и всем ограничениям.

Эти состояния образуют пространство конфигураций, которое нужно покрывать тестами. Игнорирование различия между Missing и Null приводит к тому, что серверы ведут себя непредсказуемо: одни фреймворки преобразуют отсутствующее поле в null, другие оставляют undefined, третьи выбрасывают исключение. Явное описание этих состояний в спецификации устраняет двусмысленность.

Разница между OpenAPI 3.0 и 3.1

В OpenAPI 3.0 используется ключ nullable на уровне схемы. В OpenAPI 3.1, основанном на JSON Schema 2020-12, подход изменен: используется механизм Union Types. Чтобы сделать поле nullable в 3.1, нужно указать type: ["string", "null"]. Это критически важно при миграции. Если вы пишете спецификацию версии 3.0, использование синтаксиса массива типов приведет к ошибке парсинга. Если вы мигрируете на 3.1, ключ nullable станет недействительным и будет проигнорирован некоторыми инструментами. Аналитику необходимо четко фиксировать версию спецификации в файле и не смешивать синтаксические конструкции разных версий. Кроме того, в 3.1 ключ required работает аналогично, но теперь он может применяться к свойствам объекта более гибко, хотя базовая логика presence/null distinction остается прежней.

Учебный пример: схема заказа

Рассмотрим учебный ресурс Order с полями: customer_id (строка), discount_percent (число) и comment (строка). Бизнес-правила: ID клиента обязателен и не может быть пустым; процент скидки опционален, но если передан, должен быть числом от 0 до 100, null запрещен; комментарий опционален, может быть null (для очистки комментария) или отсутствовать (при создании). Вот фрагмент спецификации OpenAPI 3.0:

openapi: 3.0.3
info:
  title: Order Service
  version: 1.0.0
paths: {}
components:
  schemas:
    Order:
      type: object
      properties:
        customer_id:
          type: string
          minLength: 1
        discount_percent:
          type: number
          minimum: 0
          maximum: 100
        comment:
          type: string
          nullable: true
      required:
        - customer_id

Разберем каждое поле. customer_id находится в required и не имеет nullable. Значит, клиент должен передать ключ, и значение не может быть null. Пустая строка также запрещена из-за minLength: 1. discount_percent не в required и не имеет nullable. Клиент может не передавать ключ вовсе. Если ключ передан, значение должно быть числом. Передача null вызовет ошибку валидации, так как nullable не указан (по умолчанию false). comment не в required, но имеет nullable: true. Клиент может не передавать ключ (Missing), передать null (Null) или передать строку (Value). Все три варианта допустимы.

Матрица допустимых payload

Ниже представлена матрица, показывающая ожидаемое поведение сервера для каждого поля при различных состояниях. Эта таблица служит основой для написания интеграционных тестов. Статус 400 означает нарушение контракта, 200/201 — успешную обработку.

Поле Отсутствует (Missing) Null Пустое значение ("") Валидное значение
customer_id 400 Bad Request 400 Bad Request 400 Bad Request 200 OK
discount_percent 200 OK 400 Bad Request N/A (тип number) 200 OK
comment 200 OK 200 OK 400 Bad Request* 200 OK

*Примечание: для поля comment пустая строка "" обычно считается невалидной, если не добавлено явное разрешение через minLength: 0 или обработку на уровне приложения. Стандартная валидация строки часто предполагает, что пустая строка — это значение, отличное от null. Если бизнес-логика требует разрешать пустые комментарии, это нужно явно зафиксировать в описании поля или добавить ограничение minLength: 0.

Типичные ошибки в спецификациях

При аудите API-контрактов чаще всего выявляются следующие дефекты:

  • Имплицитный Required: Поле не включено в массив required, но серверная логика требует его наличия. Спецификация должна отражать реальное поведение. Если сервер падает без поля, поле должно быть в required. Иначе клиенты будут генерировать недопустимые запросы.
  • Избыточный Nullable: Указание nullable: true для примитивных типов (boolean, integer), где null не несет дополнительного смысла по сравнению с отсутствием поля. Это усложняет клиентский код: разработчикам приходится писать проверки на null там, где достаточно проверить presence. Лучше использовать отсутствие поля для обозначения «значение не задано».
  • Смешение Empty и Null: Использование nullable для обозначения «пустого текста» вместо явного управления длиной строки. Null — это отсутствие значения, пустая строка — это конкретное значение. Их смешение приводит к багам при сериализации в языках, где различают None/undefined и "" (например, Python, JavaScript).
  • Ошибка Версии: Использование синтаксиса OpenAPI 3.1 (type: ["string", "null"]) в файле, объявленном как 3.0. Инструменты вроде Swagger Editor или Redoc могут не распарсить такой файл или игнорировать часть ограничений, что приведет к неработающей документации.

Проверка и валидация

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

  1. Статический Анализ: Используйте инструменты линтинга OpenAPI (Spectral, openapi-linter). Они проверят синтаксис, соответствие версии и потенциальные конфликты между полями.
  2. Contract Testing: Напишите автоматические тесты, которые генерируют payload для каждой ячейки матрицы выше. Отправляйте их на endpoint и проверяйте, что код статуса совпадает с ожидаемым. Это предотвратит расхождение между документацией и кодом. Особенно важно тестировать граничные случаи: null для обязательных полей и отсутствие для необязательных.
  3. Генерация Клиентов: Попросите разработчиков сгенерировать клиентский код на основе вашей спецификации. Проверьте, как генератор обрабатывает поля с разными комбинациями required и nullable. Например, некоторые генераторы создают non-null типы для обязательных полей, что сделает невозможным передачу null, даже если schema позволяет. Это сигнал, что спецификация может быть слишком сложной для автоматической обработки.

Если вы обнаруживаете, что клиенты не могут передать null для поля, которое должно поддерживать удаление данных (soft delete), уточните в спецификации: возможно, вам нужен отдельный endpoint DELETE, а не PATCH с null, чтобы избежать двусмысленности. Использование null для удаления — антипаттерн, который лучше заменить явным действием.

Практические рекомендации

При проектировании API придерживайтесь этих принципов:

  • Явность лучше Неявности: Всегда указывайте nullable: true явно, если null допустим. Не полагайтесь на умолчания, особенно если спецификация используется разными инструментами генерации кода или валидаторами.
  • Разделяйте Absence и Null: Если отсутствие поля означает «значение не изменилось», а null означает «сбросить значение», document this clearly in description fields. Use descriptions to explain business intent behind each state. Например: «Комментарий: если поле отсутствует, старый комментарий сохраняется; если null, комментарий очищается.»
  • Keep it Simple: Избегайте ситуаций, когда поле может быть одновременно missing, null, and empty string unless strictly necessary. Each additional state increases cognitive load for developers and testing effort. Stick to two states per field where possible: present/value or absent/default.

Для работы с этими концепциями можно открыть редактор OpenAPI и доработать схемы. Взаимосвязи required, допустимости null и бизнес-правил нужно проверить на подготовленных примерах; автоматический разбор контракта не заменяет такое ревью. Более широкий взгляд на процесс создания контрактов представлен в статье Contract-First API Development.