← Все статьи

JSON Schema для анкеты клиента: обязательные поля и ограничения

· 7 мин чтения

Практический разбор JSON Schema для анкеты клиента: настройка required, distinction between presence and null, validation of phone numbers and dates. Includes a comparison table of constraints and ready-to-use test documents for verifying schema behavior in your project.

При разработке API для регистрации клиентов аналитик часто сталкивается с вопросом: «Как garantir, что сервер получит только те данные, которые ему нужны, и в правильном формате?». Формы на фронтенде могут быть обмануты пользователем или изменены разработчиком, поэтому финальный контроль качества данных должен происходить на стороне бэкенда. JSON Schema предоставляет декларативный способ описать эти правила. В этой статье мы разберем, как построить схему для анкеты клиента, уделяя особое внимание тонкостям обработки обязательных полей и значений null.

Различие между наличием поля и значением null

Одна из самых распространенших концептуальных ошибок в JSON Schema — смешивание понятий «поле отсутствует» и «поле равно null». В спецификации JSON Schema (Draft 2020-12) эти состояния имеют разные семантики. Ключ required управляет только наличием ключа в объекте. Если поле указано в списке required, оно обязано присутствовать в JSON-объекте. Однако это не говорит ничего о его значении. Значение может быть null, строкой, числом или даже другим объектом, если тип это разрешает.

Если вы хотите сделать поле обязательным и одновременно запретить значение null, вам нужно явно определить тип. Например, {"type": "string"} автоматически исключает null, потому что в JSON Schema null имеет собственный тип "null". Если же поле может быть как строкой, так и null, но при этом обязательно должно присутствовать, схема должна выглядеть так: {"type": ["string", "null"]}. Такое поле пройдет валидацию, если оно равно null, но упадет, если его совсем убрать из объекта. Эта разница критична для бизнес-логики: например, «дата рождения» может быть обязательной для юридических лиц, но необязательной для физических, при этом ее значение не должно быть null, если оно указано.

Базовая схема анкеты

Рассмотрим типичную анкету физического лица. Она включает фамилию, имя, отчество, дату рождения, email и телефон. Мы примем следующие бизнес-правила:

  • ФИО и Email — обязательные, null не допускается.
  • Отчество — необязательное, может отсутствовать или быть null.
  • Дата рождения — обязательная, формат ISO 8601.
  • Телефон — необязательное, но если указано, должно соответствовать формату E.164.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CustomerProfile",
  "type": "object",
  "properties": {
    "last_name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 50
    },
    "first_name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 50
    },
    "middle_name": {
      "type": ["string", "null"],
      "maxLength": 50
    },
    "birth_date": {
      "type": "string",
      "format": "date"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "phone": {
      "type": ["string", "null"],
      "pattern": "^\\+[1-9]\\d{1,14}$"
    }
  },
  "required": [
    "last_name",
    "first_name",
    "birth_date",
    "email"
  ],
  "additionalProperties": false
}
Обратите внимание на параметр additionalProperties: false. Он запрещает передачу любых полей, которые не описаны в properties. Это важная мера безопасности: если клиент случайно или злоумышленно отправит поле is_admin, сервер отклонит запрос. Без этого флага лишние поля просто игнорируются, что может привести к непредсказуемому поведению при расширении API.

Ограничения на строки и форматы

Поле email использует ключ format: "email". Важно понимать, что в базовой спецификации JSON Schema форматы являются аннотациями. Это означает, что некоторые валидаторы могут не проверять их содержимое, если не включен режим строгой валидации. Для production-систем рекомендуется использовать валидаторы, которые поддерживают строгие форматы (например, Ajv с плагином ajv-formats), или добавлять регулярное выражение pattern для дополнительной гарантии. Для телефона мы использовали паттерн ^\+[1-9]\d{1,14}$, который соответствует стандарту E.164. Этот стандарт требует начала с плюса, первой цифры от 1 до 9 и общей длины от 1 до 15 цифр. Такой подход лучше, чем жесткая привязка к конкретной стране, так как позволяет принимать международные номера.

Для даты рождения используется format: "date", который ожидает формат YYYY-MM-DD. Это обеспечивает сортируемость дат и однозначность интерпретации. Если нужно ограничить диапазон лет (например, только после 1900 года), JSON Schema не позволяет напрямую сравнивать значения с текущей датой. Здесь можно использовать pattern для ограничения префикса года или перенести эту логику на уровень приложения. Однако для базовой валидации формата ISO 8601 достаточно ключевого слова format.

Сравнительная таблица ограничений

Ниже представлена таблица, показывающая, как различные ключи JSON Schema влияют на валидацию типовых полей анкеты. Это поможет быстро выбрать нужный инструмент под конкретное требование.

ПолеТребованиеJSON Schema KeyКомментарий
last_nameОбязательно, min 2 charsrequired, minLengthТип string запрещает null автоматически
middle_nameOptional, can be nulltype: ["string", "null"]Не в required, но тип допускает null
emailОбязательно, valid emailrequired, format: emailТребуется строгий валидатор
phoneOptional, E.164 formattype: ["string", "null"], patternRegex проверяет структуру номера
birth_dateОбязательно, ISO daterequired, format: dateФормат YYYY-MM-DD

Тестовые документы

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

Тест 1: Успех. Документ содержит все обязательные поля, отчество равно null, телефон отсутствует. Это допустимо, так как phone не в required, а middle_name допускает null.

{
  "last_name": "Ivanov",
  "first_name": "Ivan",
  "middle_name": null,
  "birth_date": "1990-05-15",
  "email": "ivan@example.com"
}

Тест 2: Ошибка absence. Убрано поле email. Схема должна вернуть ошибку, так как email находится в списке required.

{
  "last_name": "Petrov",
  "first_name": "Peter",
  "middle_name": null,
  "birth_date": "1985-11-20"
}

Тест 3: Ошибка format. Поле phone содержит строку "12345", которая не соответствует паттерну E.164 (нет плюса, неправильная длина). Также поле last_name имеет длину 1, что нарушает minLength: 2.

{
  "last_name": "A",
  "first_name": "Anna",
  "middle_name": "Andreevna",
  "birth_date": "1995-01-01",
  "email": "anna@test.ru",
  "phone": "12345"
}

Типичные ошибки и ограничения

При работе с JSON Schema важно избегать нескольких ловушек. Первая — использование number для финансовых величин. Если в анкету добавляется поле «баланс» или «сумма заказа», никогда не используйте type: "number". В JavaScript и многих языках number представляет собой float64, который подвержен ошибкам округления. Для денег используйте integer (хранящий копейки/центы) или string с фиксированным форматом. Вторая ловушка — забытый additionalProperties: false. Без него схема становится «прозрачной» для неизвестных полей, что снижает безопасность. Третья — смешивание версий спецификаций. Не используйте ключи из старых драфтов (например, divisibleBy из Draft 4) в схемах Draft 2020-12, где он заменен на multipleOf. Это приведет к ошибкам в современных валидаторах.

Также стоит помнить, что JSON Schema не является языком программирования. Вы не можете написать условную логику вида «если возраст > 18, тогда email обязателен». Для сложных зависимостей между полями используются конструкции if/then/else, но они значительно усложняют схему и снижают читаемость. В большинстве случаев лучше вынести такую бизнес-логику на уровень приложения, оставив в схеме только статические ограничения структуры данных.

Интеграция с инструментами

Схема JSON Schema может быть использована в различных этапах разработки. На фронтенде она может генерировать форму с автоматической валидацией и подсказками. На бэкенде библиотеки вроде Ajv (для Node.js) или jsonschema (для Python) компилируют схему в высокопроизводительный валидатор. В Postman или Swagger UI схема отображается как пример запроса, помогая разработчикам фронтенда понять ожидаемую структуру. Инструмент редактор JSON Schema позволяет визуально редактировать схему и мгновенно видеть результаты валидации примеров, что удобно для итеративного проектирования.

Сравнение JSON Schema с XSD (XML Schema Definition) показывает, что JSON Schema более естественен для REST API, так как JSON легче обрабатывается в браузерах и мобильных приложениях. Подробнее о различиях между этими технологиями читайте в статье JSON Schema vs XSD.

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

После написания схемы необходимо протестировать ее на граничных случаях. Большинство библиотек валидации возвращают структурированный отчет об ошибках. Важно, чтобы сообщения об ошибках были понятными: «Поле email должно содержать символ @» лучше, чем «Keyword 'format' failed». Для автоматизации процесса добавьте тесты в CI/CD pipeline. Каждый раз, когда изменяется схема, запускайте набор тестовых документов. Если схема становится слишком строгой (например, добавлено ограничение minLength: 10 для имени, хотя у некоторых пользователей имена короче), тесты упадут, и вы обнаружите регрессию до того, как она повлияет на пользователей.

Используйте подход «Property-Based Testing»: генерируйте случайные объекты, удовлетворяющие схеме, и убеждайтесь, что они проходят валидатор. Генерируйте также объекты, нарушающие одно конкретное правило, и убедитесь, что валидатор точно указывает на это нарушение. Это гарантирует, что ваша схема делает именно то, что заявлено, и ничего лишнего.

Итог

JSON Schema для анкеты клиента — это фундаментальный элемент архитектуры данных. Правильное разделение между обязательностью (presence) и типом (value), запрет дополнительных полей и явные ограничения на формат обеспечивают надежность и безопасность API. Начните с простой схемы, определите бизнес-правила, создайте тестовые документы и интегрируйте валидацию в ваш workflow. Это инвестиция, которая окупится сокращением количества багов, связанных с некорректными входными данными, и ускорением работы команд разработки.