01
Определить роль внешнего массива
В режиме одного документа массив остаётся корневым значением данных. В режиме нескольких образцов его элементы объединяются как независимые документы. Для нескольких документов-массивов нужен массив массивов.
От образцов к контракту
Генератор JSON Schemaсначала различия, затем ограничения
Начните с примера. Выбирайте несколько образцов, только если каждый элемент внешнего массива — отдельный документ.
Генератор JSON Schema
Образцы JSON
Выходная схема
Обработка в этом браузере; образцы не передаются и не сохраняются.
Образцов: 1 · свойств: 7 · enum: 0 · пропущено: 0
Генератор JSON Schema помогает, когда вместо спецификации есть только несколько ответов API. Один успешный ответ не доказывает, что все ключи будут присутствовать всегда. Разные образцы показывают пропуски и изменения типов.
Отсутствующий ключ и ключ со значением null — разные случаи. required отвечает за наличие свойства, а type — за допустимое значение. Обязательное свойство может разрешать null; эти настройки независимы.
Зачем нужен Генератор JSON Schema
Учитывать не только первую запись
Генератор JSON Schema анализирует все элементы массива в одной структурной позиции. Пропущенный ключ перестаёт быть общим обязательным свойством, а явный null добавляется к типу. Одноимённые поля из разных путей не смешиваются.
Сохранить ручные ограничения
Переход к редактированию отключает автоматическую генерацию. Повторный запуск показывает отдельный вариант. Применение заменяет одну схему; отмена восстанавливает также исходный ввод и настройки.
Три решения перед экспортом
02
Разделить наличие и null
Общие обязательные свойства присутствуют в каждом объекте на этой позиции. Требование всех полей может отклонить исходный неполный образец. Разрешение null не удаляет имена из required.
03
Обновлять результат после изменений
Изменение ввода или настроек сразу блокирует экспорт. Автоматический запуск ждёт 350 мс; в ручном режиме доступно Ctrl/Cmd+Enter. После правок новый вариант нужно проверить и явно применить.
Как выводится структура
Три версии с общим набором правил
Генератор JSON Schema предлагает Draft 7, 2019-09 и 2020-12. Используются общие type, properties, required, enum и items с одной схемой. Меняется URI $schema; миграции существующих сложных схем здесь нет.
Схема для массивов учитывает каждый элемент
Пустые массивы не дают сведений о типе элементов. Если все пусты, items равен {}. Числа 1.0 и 100e-2 математически целые и дают integer; наличие дроби объединяет тип до number.
Перечисления только по выбору
enum изначально выключен. При включении для скалярной позиции собирается до 20 различных значений, включая добавленный null. Превышение убирает весь enum и учитывается в строке состояния, без обрезки списка.
Схема из JSON без округления больших чисел
Числовые токены сохраняются в исходном виде. Равные значения, например 1 и 1.0, объединяются без преобразования в Number. Схему можно править, но проверка редактора ограничена синтаксисом JSON и видом корня.
Чего образцы не доказывают
- Без догадок о бизнес-правилах
- Даты остаются string. format, pattern, диапазоны, длины и значения по умолчанию не выводятся. Дополнительные свойства разрешены. Такие ограничения следует брать из требований, а не из случайного состава образцов.
- Невидимые варианты остаются неизвестными
- Только null не раскрывает непустой тип, а пустые массивы не раскрывают элементы. Связи между полями и дискриминаторы не сохраняются, поэтому схема может разрешить сочетания, которых не было в примерах.
- Без кортежей и анализа лишь первого элемента
- Все элементы формируют общий items. Фиксированные позиции, длина, ссылки и условия не создаются. Настройка всех обязательных полей может намеренно исключить исходную запись с пропущенным ключом.
- Правка не означает проверку семантики
- Выход должен быть объектом или логическим значением JSON; ошибки синтаксиса и повторные ключи отклоняются. Метасхема, внешние ссылки и бизнес-образцы не проверяются. Ошибочное имя типа всё ещё может быть синтаксически допустимым.
- Ограничения целого документа
- Ввод и вывод: по 500 000 символов и 50 000 узлов. Глубина ввода до 40, редактируемого вывода до 100. Несколько образцов: 1–1 000 элементов. Комментарии, завершающие запятые, NDJSON, файлы и URL не поддерживаются. Превышение лимита вывода останавливает всю генерацию.
Генератор JSON Schema: вопросы
Какой draft JSON Schema использует генератор?
По умолчанию выбран 2020-12. Доступны также Draft 7 и 2019-09 — выбирайте версию вашего валидатора. Обычная форма массивов, создаваемая здесь, одинакова для трёх версий.
Как определяются обязательные свойства при генерации схемы?
В общем режиме ключ должен присутствовать в каждом объекте на этой позиции. null считается присутствующим значением. Можно также сделать обязательными все наблюдаемые свойства или ни одного.
Выводит ли генератор форматы строк вроде email или date?
Нет. Даты и электронные адреса остаются строками. При реальном требовании добавьте format вручную и проверьте, как ваш валидатор обрабатывает эту аннотацию.
Как он выводит схему для массивов?
Все элементы объединяются в общий items. Если есть только пустые массивы, items будет {}. Порядок примеров не превращается в фиксированные позиции кортежа.
Можно ли сразу использовать полученную схему в рабочей системе?
Сначала проверьте требования. Примеры не доказывают полный набор допустимых значений и запрет дополнительных полей. Дополните ограничения и протестируйте корректные и некорректные данные валидатором проекта.
Нашли спорный результат вывода типов?
Проверьте контракт перед внедрением
Используйте Генератор JSON Schema для обычных ответов и пограничных случаев, затем дополните результат действительными требованиями проекта.