Как создать JSON Schema из примера JSON

Что делает генератор и какие данные ему нужны

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

В основной ввод передаётся строка с JSON. Можно указать объект, массив, строку, число, логическое значение или null. Отдельно доступно необязательное поле заголовка. Если его не заполнить, используется название «Generated Schema». Пустой основной ввод имеет особое поведение: при наличии подходящего значения в одном из альтернативных полей инструмент может взять его оттуда. Если пригодных данных нет, операция завершается ошибкой.

Как создать схему из примера JSON

1. Подготовьте небольшой, но содержательный пример JSON. Для объекта включите поля, которые хотите увидеть в схеме; для массива добавьте элементы, по которым можно судить о структуре. Проверьте синтаксис: имена свойств должны быть заключены в двойные кавычки, а значения должны соответствовать JSON.

2. Вставьте пример в основное поле для образца данных. Если интерфейс предлагает альтернативные поля, используйте их только при необходимости. Когда основная строка пуста, инструмент может выбрать первое подходящее значение из полей json, data, text, input, value или sample.

3. При желании укажите заголовок схемы. Пустой заголовок не создаёт пустое имя: вместо него применяется «Generated Schema». Затем запустите создание схемы обычной кнопкой действия в интерфейсе.

4. Изучите сформированный JSON Schema. Для объекта проверьте перечень свойств, обязательность наблюдавшихся имён и настройку дополнительных свойств. Для массива посмотрите, как описаны элементы. Если образец содержит разные формы элементов, сравните варианты в объединении anyOf.

5. Если результат не появился, сначала исправьте входные данные и повторите действие. Некорректный JSON отклоняется, а не преобразуется в схему. Также выбранные данные не должны превышать 1 000 000 байт в кодировке UTF-8. При пустом основном поле убедитесь, что альтернативное значение действительно пригодно для разбора.

Как читать результат и понимать его границы

Схема описывает тип и структуру значения, которые удалось вывести из образца. Объект получает тип object, отдельную схему для каждого наблюдавшегося свойства, список этих имён в required и запрет дополнительных свойств. Поэтому поле, отсутствующее в вашем примере, не следует автоматически считать необязательным: оно просто не было показано генератору.

Массив получает тип array. У пустого массива схема элементов остаётся без заданного ограничения, поскольку образец не содержит элементов для анализа. Если элементы имеют разные схемы, варианты объединяются через anyOf, а повторяющиеся варианты удаляются. Это полезно прочитать перед использованием результата для данных, где допустимы несколько форм элемента.

Для простых значений применяются типы null, boolean, integer и number для нулевого значения, логического значения, целого и числа с плавающей точкой соответственно. Строка получает тип string; при совпадении с распознаваемым шаблоном ей может быть добавлен формат email, uuid, uri, ipv4, date-time, date или time. Наличие формата означает результат распознавания по шаблону, а не подтверждение вашего бизнес-правила.

В сформированном документе присутствует идентификатор JSON Schema draft-07. Используйте результат как отправную точку для описания показанного образца и вручную проверьте ограничения, которых в примере не было: диапазоны чисел, длины строк, взаимозависимости полей и допустимые будущие варианты. Генератор не исправляет повреждённый JSON и не гарантирует, что вывод охватывает замысел всей модели данных.

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

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

Вставьте JSON-объект с name и email в поле образца, оставьте заголовок пустым и запустите создание схемы. После этого проверьте структуру объекта и выведенные характеристики строковых значений.

Для объекта с полями name и email результат имеет тип object, схемы для обоих свойств, эти имена в required и запрет дополнительных свойств; строка email может получить формат email, если совпадёт с распознаваемым шаблоном.

Ограничения

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

Частые ошибки

• Ошибка возникает, когда в поле вставлен JSON с нарушенным синтаксисом или не передано пригодное значение. Проверьте кавычки, запятые, скобки и фактическое содержимое основного либо альтернативного поля, затем запустите создание повторно.

Частые вопросы

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

Да, но только если основная строка образца пуста и в одном из поддерживаемых альтернативных полей есть пригодное значение. Инструмент может выбрать первое подходящее значение из полей json, data, text, input, value или sample; без пригодных данных операция завершается ошибкой.

Что получится, если примером будет пустой массив?

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

Почему у строки в результате появился формат?

Формат может появиться у строки, если её значение совпало с одним из распознаваемых шаблонов, например email, uuid, uri, date или date-time. Это вывод по образцу, поэтому дополнительные правила предметной области стоит проверить отдельно.