Лучшие практики валидации и проектирования JSON Schema

Почему валидация JSON важна

API — это основа современных приложений, а JSON — их универсальный язык. Но без надлежащей валидации некорректный или вредоносный JSON может обрушить ваш сервис, повредить базу данных или открыть бреши в безопасности. Я видел сбои в продакшене, вызванные одним пропущенным полем или неожиданным типом. Валидация JSON — это не просто отлов опечаток, это обеспечение контрактов, улучшение сообщений об ошибках и защита вашей системы.

В этой статье мы рассмотрим практические лучшие практики проектирования JSON-схем и валидации данных. Строите ли вы REST API, резолвер GraphQL или микросервис — эти принципы помогут вам спать спокойнее.

1. Начните с чёткой схемы

Схема — это контракт вашего API. Она определяет, какие поля допустимы, их типы и ограничения. Без неё вы действуете вслепую. Используйте JSON Schema (стандартизированный словарь) для описания ваших данных. Он не зависит от языка и широко поддерживается.

Вот минимальный пример для объекта пользователя:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

Ключевые моменты: required гарантирует обязательные поля; additionalProperties: false отклоняет неизвестные поля (полезно для строгих API).

2. Валидируйте рано и часто

Валидируйте на периферии — до запуска бизнес-логики. Это предотвращает распространение некорректных данных. В Node.js можно использовать библиотеки вроде Ajv; в Python — jsonschema; в Go — gojsonschema. Всегда валидируйте входящие запросы и исходящие ответы (чтобы отлавливать баги).

Пример на Python:

from jsonschema import validate, ValidationError

try:
    validate(instance=request.json, schema=user_schema)
except ValidationError as e:
    return {"error": e.message}, 400

Возвращайте понятные сообщения об ошибках — они помогают клиентам быстро исправлять проблемы.

3. Проектируйте с учётом эволюции

API меняются. Ваша схема должна допускать дополнения без нарушения работы клиентов. Следуйте этим правилам:

• Никогда не удаляйте и не переименовывайте поля без повышения версии.
• Делайте новые поля необязательными, если они не критичны.
• Используйте версионирование в URL (например, /v1/users) или медиатипе.
• Предпочитайте аддитивные изменения — добавляйте поля, а не изменяйте существующие.

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

4. Осторожно работайте с типами

В JSON ограниченный набор типов: string, number, boolean, object, array, null. Обратите внимание на:

• Числа: JSON не различает целые и дробные. Используйте type: integer, если нужны целые числа.
• Даты: Используйте строки ISO 8601 (например, 2026-01-15T10:00:00Z) и валидируйте с format: date-time.
• Перечисления: Ограничивайте значения известным набором, чтобы избежать некорректных состояний.
• Null против отсутствия: Решите, допустим ли null. Часто лучше опустить поле, чем отправлять null.

5. Защитите валидацию

Валидация — это средство безопасности. Злоумышленники могут отправлять огромные данные, глубоко вложенные объекты или неожиданные типы, чтобы вызвать отказ в обслуживании. Смягчайте это с помощью:

• Ограничений размера: Отклоняйте данные больше определённого размера (например, 1 МБ).
• Ограничений глубины: Предотвращайте глубоко вложенный JSON (например, максимум 10 уровней).
• Строгих схем: Запрещайте дополнительные свойства, чтобы избежать инъекции неожиданных полей.
• Санитизации строк: Даже после валидации экранируйте вывод для предотвращения XSS.

Также валидируйте на сервере — никогда не доверяйте только клиентской валидации.

6. Используйте таблицу сравнения библиотек валидации

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

Все эти библиотеки реализуют JSON Schema, поэтому ваши схемы переносимы.

7. Документируйте вашу схему

Схема полезна только тогда, когда разработчики её понимают. Генерируйте документацию API из вашей схемы с помощью инструментов вроде OpenAPI (ранее Swagger) или ключевого слова description в JSON Schema. Включайте примеры для каждого поля.

Для быстрой проверки вы можете форматировать и валидировать JSON вручную с помощью JSON-форматтера. Это помогает выявить синтаксические ошибки и проблемы структуры до того, как вы углубитесь в валидацию схемы.

8. Тестируйте ваши схемы

Схемы — это код, тестируйте их. Пишите модульные тесты с валидными и невалидными данными, чтобы убедиться, что ваши правила валидации работают как ожидается. Инструменты вроде json-schema-test-suite могут помочь. Также рассмотрите контрактное тестирование между сервисами, чтобы рано выявлять несоответствия.

FAQ

Что такое JSON Schema и почему её стоит использовать?

JSON Schema — это стандарт описания структуры JSON-данных. Он позволяет определять типы, обязательные поля и ограничения, обеспечивая автоматическую валидацию и документацию. Он широко поддерживается в разных языках.

Как обрабатывать дополнительные свойства при валидации JSON?

По умолчанию JSON Schema разрешает дополнительные свойства. Установите additionalProperties: false, чтобы отклонять неизвестные поля — это повышает безопасность и отлавливает опечатки. Однако будьте осторожны с эволюцией API — строгие схемы могут сломать клиентов, отправляющих лишние поля.

Можно ли использовать JSON Schema для валидации запросов и ответов?

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

Заключение

Валидация JSON и проектирование схем — основа надёжных API. Определяя чёткие схемы, валидируя рано, планируя эволюцию и защищая ваши эндпоинты, вы строите системы, которые надёжны и поддерживаемы. Начните со схемы, выберите библиотеку валидации и тщательно тестируйте. Ваше будущее «я» (и ваши пользователи) скажут вам спасибо.