Как сгенерировать JSON Schema
- Вставьте репрезентативный пример JSON. Лучше всего подходят массивы из нескольких элементов, потому что их элементы объединяются в одну схему.
- Выберите версию схемы (draft 2020-12 или draft-07) и укажите, нужно ли делать свойства обязательными, распознавать форматы и запрещать дополнительные свойства.
- Скопируйте или скачайте схему, а затем доработайте её вручную — например, добавьте описания, enum или минимальные и максимальные значения.
Что определяет генератор
| Пример JSON | Схема |
|---|---|
"ada@example.com" | {"type": "string", "format": "email"} |
"2026-05-01T10:00:00Z" | формат date-time (а также date, time, uri, uuid, ipv4) |
42 / 4.5 | "integer" / "number" |
| ключ, который есть в каждом объекте | попадает в required |
| ключ, которого нет в некоторых элементах массива | необязательный (не входит в required) |
[1, "a", null] | "items": {"type": ["string", "integer", "null"]} |
| объекты вперемешку с простыми значениями | anyOf с отдельной схемой для каждого вида |
Что такое JSON Schema?
JSON Schema — это словарь для описания и проверки структуры JSON-данных: какие свойства существуют, какой у каждого тип, какие из них обязательны и какие значения допустимы. Она используется для контрактов API в OpenAPI, файлов конфигурации, генерации форм и проверки структурированного вывода моделей ИИ. Текущая версия — 2020-12; draft-07 по-прежнему поддерживается многими старыми инструментами. Спецификация опубликована на json-schema.org.
Как доработать сгенерированную схему
- Добавьте
titleиdescription, чтобы задокументировать смысл каждого поля. - Ограничьте значения с помощью
enum,minimum,maximum,maxLengthилиpattern. - Отметьте Запретить дополнительные свойства (
additionalProperties: false), чтобы отклонять неизвестные ключи. - Проверяйте данные с помощью Ajv в JavaScript или пакета
jsonschemaв Python.
Часто задаваемые вопросы
Какую версию JSON Schema выбрать?
Для новых проектов используйте draft 2020-12 — это актуальная версия и основа OpenAPI 3.1. Выбирайте draft-07, если ваш валидатор или инструменты ещё не поддерживают 2020-12.
Почему все мои свойства стали обязательными?
В единственном объекте-примере присутствуют все свойства, поэтому все они помечаются как обязательные. Используйте массив из нескольких разных примеров или отключите Отметить свойства как обязательные.
Может ли генератор определить enum или диапазоны значений?
Нет. По одному примеру нельзя понять, какие значения допустимы в целом, поэтому enum, минимальные и максимальные значения и шаблоны (pattern) нужно добавлять вручную.
Как проверить JSON по схеме?
Используйте библиотеку-валидатор, например Ajv для JavaScript или jsonschema для Python. Многие редакторы кода также проверяют JSON-файл по схеме, указанной в его свойстве $schema.