Схема от JSON до JSON: от образца полезной нагрузки до

Что умозаключение может и не может видеть

Хороший преобразователь из одного документа точно извлекает типы, вложенность, формы элементов массива и имена свойств. Чего он не может вывести, так это намерения. Он не знает, что поле является необязательным, поскольку оно включено в данную конкретную запись, что строка представляет собой адрес электронной почты, что число является положительным целым числом или что значение происходит из фиксированного набора. Поэтому все производные данные помечаются цифрой `required`, что является правильным значением по умолчанию для проекта контракта и неправильным для отправки без проверки.

Усиление сгенерированной схемы

1. Сравните два или три реальных образца: ключи, отсутствующие ни в одном образце, должны выпасть из `required`.
2. Добавьте `format` там, где значение известно — `date-time`, `email`, `uri`, `uuid`, `ipv4`.
3. Превратите открытые наборы в значения `enum`, если поле действительно имеет фиксированный словарь, например статус или регион.
4. Закрепите числа цифрами `minimum`, `maximum` и `multipleOf`, чтобы отрицательная величина не могла быть подтверждена.
5. Добавляйте `additionalProperties: false` только в том случае, если неизвестные ключи должны быть отклонены — в противном случае оставьте схему открытой для прямой совместимости.

Требуется обещание, а не наблюдение. Пометка поля как обязательного, поскольку оно содержится в одном образце, является наиболее распространенным способом, которым предполагаемая схема нарушает реальную интеграцию.

Где схема заслужила свое существование

Практическая ценность проявляется на границах: проверка полезной нагрузки веб-перехватчика перед тем, как ему доверять, проверка файлов фикстур в CI, чтобы тесты проваливались из-за неверных данных, а не из-за запутанных нулевых ошибок, документирование ответа API для людей, которые никогда не будут читать серверный код, и генерация типизированных клиентов. Схема JSON также является самым дешевым способом помешать изменению конфигурации незаметно изменить публичный ответ, поскольку валидатор улавливает его во время сборки, а не во время производства.

                {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "plan": { "type": "string", "enum": ["free", "pro", "team"] }
  }
}
              

Держите это под контролем версий

Сгенерированные схемы исчезают в тот момент, когда ими никто не владеет. Зафиксируйте защищенный файл рядом с кодом, который создает данные, ссылайтесь на него из валидатора в CI и перегенерируйте только тогда, когда контракт действительно изменится, рассматривая схему как источник истины для формы, а образец как доказательство, а не наоборот.

Вывод в браузере

Реальные полезные данные полны идентификаторов, адресов электронной почты и токенов, поэтому преобразование схемы JSON в JSON, при котором загружается образец, означает передачу производственных данных для чисто механической операции. Локальный вывод сохраняет полезную нагрузку на вкладке, позволяет вставить запись о клиенте, не задумываясь, и работает при отключенной сети.