JSON Schema: Полное руководство по валидации JSON

Введение

В мире веб-разработки и API, JSON (JavaScript Object Notation) стал де-факто стандартом для обмена данными. Его простота и читаемость сделали его популярным выбором для разработчиков. Однако, с ростом сложности приложений, возникает потребность в обеспечении корректности и целостности данных, передаваемых в формате JSON. Здесь на помощь приходит JSON Schema.

JSON Schema — это мощный инструмент для валидации (проверки) структуры и типов данных в JSON-документах. По своей сути, это декларативный язык, который позволяет описывать, какой должна быть структура JSON-документа. Вы можете думать о JSON Schema как о “чертеже” для ваших JSON-данных.

Зачем это нужно?

Обеспечение качества данных: JSON Schema гарантирует, что данные, которые получает ваше приложение, соответствуют ожидаемому формату. Это помогает предотвратить ошибки, связанные с некорректными данными.
Документация API: JSON Schema служит отличной документацией для вашего API. Разработчики, использующие ваш API, могут точно знать, какой формат данных ожидается и какой будет ответ.
Автоматизированное тестирование: Вы можете использовать JSON Schema для автоматической проверки ответов API в ваших тестах, что упрощает процесс тестирования.
Генерация пользовательских интерфейсов: На основе JSON Schema можно автоматически генерировать формы для ввода данных, что ускоряет разработку.

Основные концепции

JSON Schema оперирует набором “ключевых слов” (keywords), которые используются для описания различных аспектов данных. Рассмотрим основные из них.

Ключевое слово `type`

Самое базовое ключевое слово — type. Оно определяет тип данных, который может принимать поле. Основные типы:

"string": строка
"number": число (целое или с плавающей точкой)
"integer": целое число
"object": объект
"array": массив
"boolean": булево значение (true или false)
"null": значение null

Пример:

{ "type": "string" }

Этот JSON Schema будет валидным для любой строки, но не для числа или другого типа.

Ключевые слова для объектов

properties: определяет свойства объекта и их схемы.
required: список обязательных свойств объекта.
minProperties и maxProperties: минимальное и максимальное количество свойств в объекте.
additionalProperties: позволяет или запрещает наличие дополнительных, не описанных в properties, свойств.

Ключевые слова для массивов

items: описывает схему для элементов массива.
minItems и maxItems: минимальное и максимальное количество элементов в массиве.
uniqueItems: если true, все элементы массива должны быть уникальными.

Ключевые слова для строк

minLength и maxLength: минимальная и максимальная длина строки.
pattern: регулярное выражение, которому должна соответствовать строка.
format: предопределенные форматы для строк, такие как "date-time", "email", "uri".

Ключевые слова для чисел

minimum и maximum: минимальное и максимальное значение числа.
exclusiveMinimum и exclusiveMaximum: строгое минимальное и максимальное значение (не включая само значение).
multipleOf: число должно быть кратно указанному значению.

Практические примеры

Пример 1: Валидация информации о пользователе

Предположим, мы хотим валидировать JSON-объект с информацией о пользователе. У пользователя должны быть имя (строка), email (строка в формате email) и возраст (целое число не меньше 18).

JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "description": "A user in the system",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 18
    }
  },
  "required": ["name", "email", "age"]
}

Валидный JSON:

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30
}

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

{
  "name": "J",
  "email": "john.doe",
  "age": 17
}

Этот JSON не пройдет валидацию по нескольким причинам: длина имени меньше 2, email не в правильном формате, и возраст меньше 18.

Пример 2: Валидация списка продуктов

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

JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Product list",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "price": {
        "type": "number",
        "minimum": 0
      },
      "description": {
        "type": "string"
      }
    },
    "required": ["name", "price"]
  }
}

Валидный JSON:

[
  {
    "name": "Laptop",
    "price": 1200
  },
  {
    "name": "Mouse",
    "price": 25,
    "description": "A wireless mouse"
  }
]

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

[
  {
    "name": "Keyboard"
  }
]

Этот JSON невалиден, так как у продукта “Keyboard” отсутствует обязательное поле price.

Типичные ошибки и как их избежать

Забывают про $schema: Всегда указывайте версию JSON Schema с помощью ключевого слова $schema. Это помогает валидаторам правильно интерпретировать вашу схему.
Неправильное использование required: Ключевое слово required должно находиться на том же уровне, что и properties, и содержать массив строк с именами обязательных полей.
Путаница между minimum/maximum и minLength/maxLength: Первые два используются для чисел, вторые — для строк и массивов.
Сложные вложенные структуры: При описании сложных вложенных объектов и массивов легко запутаться. Используйте $ref для переиспользования частей схемы и улучшения читаемости.

Связь с другими темами

OpenAPI (Swagger): OpenAPI, стандарт для описания RESTful API, использует JSON Schema для определения моделей данных (запросов и ответов). Это позволяет автоматически генерировать документацию и клиентский код.
GraphQL: Хотя GraphQL имеет свою собственную систему типов, JSON Schema может быть полезна для валидации данных, которые приходят в качестве переменных в GraphQL-запросах.
Микросервисная архитектура: В микросервисах, где сервисы общаются друг с другом через API, JSON Schema помогает обеспечить консистентность данных и контрактов между сервисами.

Заключение

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