Я отправил достаточно API, чтобы знать точный момент, когда проекту нужна схема JSON. Это никогда не бывает в начале. Это три недели, когда вторая команда начинает потреблять вашу конечную точку, кто-то отправляет неверный корпус запроса и a null проскальзывает в поле, которое все предполагали, всегда было строкой. Внезапно вам нужен контракт - документ, в котором говорится, что в форме, которую машина может обеспечить, " вот как выглядит действительная полезная нагрузка." Этот документ представляет собой схему JSON, и написание одного вручную с конечной точки, которая уже возвращает реальные данные, является одной из наиболее утомительных работ в серверной работе.
TL;DR: Вставьте образец JSON в Генератор схемы JSON, выберите Draft-07 или 2020-12, и он выводит схему - типы,
requiredполя, объединенные элементы массива и строковые форматы, такие какdate-timeаuuid. Он полностью работает в вашем браузере, поэтому полезные нагрузки, содержащие токены и персональные данные, никогда не покидают страницу. Относитесь к выводу как к сильному первому черновику, а затем ужесточайте его с помощью ограничений, которые только вы знаете.
Я построил этот инструмент для Toolz.dev, потому что я продолжал делать то же самое вручную: открывать тело ответа, щуриться на него и транскрибировать его форму в предложение схемы за предложением. это повторяется, и повторяющаяся транскрипция - это то, где скрываются ошибки. Это руководство объясняет, что делает генератор, где вывод надежен, где ему нужно ваше суждение и как сгенерированная схема вписывается в реальный рабочий процесс проверки.
Что такое схема JSON и зачем генерировать ее на основе данных?
JSON Schema - это словарь для описания структуры JSON, поддерживаемый как спецификация сама по себе а не как соглашение. схема сама по себе является документом JSON, который объявляет ожидаемый тип каждого поля, какие поля требуются, какую форму принимают вложенные объекты и массивы, и - с ключевыми словами типа pattern, enum, minimum, и format - какие значения на самом деле разрешены. Проверяющие почти на каждом языке читают схему и сообщают вам, соответствует ли данный документ. Это самое близкое к системе типов, которая перемещается через границы обслуживания, в мире JSON.
Причина для генерации схемы из образца, а не записи ее с нуля, заключается в том, что большая часть схемы механическая Ходьба полезной нагрузки и запись & quot;это строка, это целое число, этот объект имеет эти ключи& quot; это именно тот вид работы, который должна выполнять машина. что есть не механический - это семантический слой: знание этого status может быть только одной из четырех строк age не может быть отрицательным, это email должен соответствовать реальному шаблону адреса. поколение обрабатывает механические леса, чтобы вы могли потратить свое внимание на ограничения, которые имеют значение. вы начинаете с документа, который уже соответствует реальности, и добавляете правила, вместо того, чтобы начинать с пустого файла и надеяться, что вы запомнили каждое поле.
Есть измерение доверия тоже Когда вы вводите схему вручную, вы кодируете то, что вы верить конечная точка возвращается.Убеждения отклоняются от реальности - добавляется поле, целое число становится недействительным, конечная точка, которая вернула один объект, начинает возвращать массив. схема, созданная на основе фактического ответа, привязана к тому, что действительно отправила служба в день, когда вы ее захватили. Этот якорь стоит многого, когда вы отлаживаете, почему проверка проходит в стадии и терпит неудачу в производстве.
Как генератор выводит схему
Движок анализирует ваш JSON и рекурсивно обходит значение, излучая узел схемы для каждой части структуры. правила намеренно консервативны, потому что слишком свободная схема бесполезна, а слишком строгая схема отвергает действительные данные.
Для скаляров это различает integer из number -- 42 становиться integer, 4.2 становиться number - потому что это различие имеет смысл для валидаторов и всех, кто читает схему. Булевы и null сопоставить с их собственными типами. строки становятся type: string, и если включено определение формата, механизм проверяет значение по набору хорошо известных шаблонов и отмечает его: date-time, date, time, email, uri, uuid, и ipv4, йо-
Для объектов он записывает каждый ключ, выводит схему для каждого значения и - if required вывод включен - отмечает ключ, необходимый, когда он присутствует в каждом объекте в этой позиции. Для одного объекта, который означает все ключи; интересный случай - массивы.
Для массивов объектов генератор делает нечто более полезное, чем наивная прогулка Вместо того, чтобы испускать отдельную схему для каждого элемента или разрастание anyOf имея почти идентичные формы, он объединяет все объекты массива в один items схема, описывающая один элемент Требуется ключ, присутствующий в каждом элементе; ключ, присутствующий только в некоторых элементах, оставлен необязательным Это отражает то, как ведут себя реальные коллекции API: список с разбивкой по страницам, где большинство записей несут avatarUrl но некоторые не.Объединенная схема захватывает & quot;эти поля всегда появляются, эти иногда появляются & quot; в одном читаемом определении. это можно увидеть во встроенном образце, где members массив имеет два объекта - один с active поле и единица без - и сгенерированные метки схемы элемента id а role требуется, но уходит active опционально.
Для массивов смешанных скаляров двигатель сводит типы элементов в один type массив - ["integer", "string", "boolean"] - а не многословное объединение. Когда формы объектов и необъектов действительно смешиваются в одном массиве, это возвращается к anyOf, которая является правильной конструкцией схемы JSON для & quot; одной из этих альтернатив.& quot;
Как использовать генератор схем JSON
Шаг 1: Вставьте репрезентативный образец
Забросьте ответ API, приспособление, файл конфигурации или тело веб-крючка. Самое главное, что вы можете сделать для точности, - это вставить a представитель образец. если у вас есть несколько записей из реального ответа, включите их все внутрь массива - генератор объединит их и правильно сделает вывод об опциональности. образец с одной записью сообщает движку, что каждое поле, которое он видит, всегда присутствует, что часто неверно. Сначала загрузите встроенный образец, чтобы увидеть, как обрабатываются вложенные объекты, массивы объектов и отформатированные строки, прежде чем вставлять свои собственные.
Шаг 2: Выберите диалект
Выберите Draft-07 для самой широкой совместимости между библиотеками проверки или 2020-12 для текущей спецификации. Инструмент записывает правильно $schema идентификатор на корень, чтобы ваш валидатор применял правильные правила. для объектов и форм массива, которые создает этот генератор, структурный вывод одинаков для обоих диалектов; видимая разница - это идентификатор. если вы не уверены, какой инструмент поддерживает, Draft-07 является безопасным по умолчанию - он имеет самую широкую библиотечную поддержку среди всех версий.
Шаг 3: Установите свои параметры
Добавить а title если вы хотите, чтобы схема самодокументировалась. Решите, следует ли излучать required - большую часть времени вы хотите, но во время раннего исследования вы можете предпочесть более свободную схему. Продолжайте определять формат, если вы не видите ложных срабатываний. И включите строгий режим (additionalProperties: false) когда схема охраняет что-то, что вы полностью контролируете, например файл конфигурации или тело запроса, и вы хотите, чтобы неожиданные ключи были отклонены, а не проигнорированы.
Шаг 4: Создавайте, проверяйте и экспортируйте
Нажмите "Создать", затем критически прочитайте выходные данные. Проверьте это required соответствует вашему намерению, что целое число против числа вышло правильно, и что любые обнаруженные форматы являются правильными, а не случайными. Когда это выглядит правильно, скопируйте схему или загрузите ее как a .json файл готов к попаданию в ваш валидатор или репозиторий.
Работающий пример
Рассмотрим этот ответ из гипотетического /projects конечная точка:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
Генератор создает схему где id является строкой с format: "uuid", createdAt является строкой с format: "date-time", score является а number (не целое число из-за десятичной дроби), и members является массивом, чей items схема требует id а role но не active. Последняя деталь - это выигрыш: из двух примеров участников было правильно сделано такое заключение active не является обязательным. выполнение этого рассуждения вручную с большой полезной нагрузкой - это именно та тщательная и скучная работа, которую удаляет генератор.
Где заканчивается вывод и начинается ваше суждение
Я хочу быть прямым о пределах, потому что сгенерированная схема, переданная прямо в производство, является ошибкой. Вывод видит типы и структуру; он не может видеть намерение.
Оно не может этого знать role является перечислением owner, editor, и viewer - из образца он только знает role является строкой. Он не может знать, что score колеблется от 0 до 5, что name имеет максимальную длину, или что код, который выглядит как UUID, на самом деле является непрозрачным идентификатором, который должен оставаться простой строкой. Это делает вывод required от присутствия, так что необязательное поле, которое случайно появится в вашем образце, будет помечено, как требуется, пока вы не исправите его. И это работает на основе данных, которые вы ему даете: если ваш образец никогда не включает a null для поля с возможностью обнуления схема не будет знать, что поле может быть нулевым.
Правильная ментальная модель - это строительные леса Генератор строит фрейм точно - каждое поле, его тип, вложение, формы массива, требуемый список на основе присутствия Затем вы добавляете семантические ограничения: перечисления, шаблоны, числовые границы, и любые форматы, которые движок не мог видеть по одному значению Это быстрее и менее подвержено ошибкам, чем начинать с нуля, потому что утомительная структурная транскрипция уже сделана и исправлена.
Драфт-07 против 2020-12: какой выбрать?
| любовное | Черновик-07 | 2020-12 |
|---|---|---|
| Поддержка библиотек | Широчайший; поддерживается практически везде | Растущий; проверьте свой валидатор |
| состояние | Широко развернутый, стабильный | Текущая спецификация |
$schema стоимость |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| Ключевые слова элемента массива | items для одноэлементных схем |
items / prefixItems раскол для кортежей |
| Лучшее, когда | Максимальная совместимость имеет значение | Вам нужны новейшие функции спецификации |
Для схем, которые генерирует этот инструмент - объекты, обязательные списки, массивы одной формы элемента - оба диалекта выражают одну и ту же структуру. практическое решение сводится к тому, что поддерживает ваша библиотека проверки. если вы подключаете схему в установленный стек, совпадайте с версией ваших документов валидатора. если вы начинаете заново и у вас нет ограничений, Draft-07 остается прагматичным выбором для его непревзойденной поддержки экосистемы.
Общие варианты использования
Документирование существующего API. Когда вы наследуете конечную точку без схемы, генерация одной из реального ответа дает вам точный стартовый документ за секунды. Затем вы уточняете его в опубликованный контракт. Это естественным образом сочетается с генерацией типов для вашего клиентского кода - тот же образец может подавать json в машинописный инструмент, позволяющий заключить контракт с сервером и использовать типы клиентов из одного и того же источника истины.
Проверка органов запросов. Для тела запроса, которым вы управляете, сгенерируйте схему из допустимого примера, включите строгий режим, чтобы отклонить неожиданные ключи, и добавьте перечисления и границы, которые обеспечивает ваша конечная точка. Теперь неверные запросы терпят неудачу на краю с явной ошибкой проверки вместо того, чтобы вызывать запутанные сбои глубоко в вашем обработчике.
Проверка файла конфигурации. Приложения, которые читают конфигурацию JSON, получают огромную выгоду от схемы. Создайте его из конфигурации с известным хорошим качеством, затяните его и проверьте при запуске, чтобы опечатка в клавише конфигурации громко не удавалась вместо того, чтобы молча отключать функцию.
Испытания и приспособления. Схема одновременно служит тестовым активом. Проверьте свои приспособления против него в CI, чтобы приспособление, которое выходит из формы, было поймано до того, как оно вызовет вводящий в заблуждение зеленый тест.
Тестирование контрактов между службами. Когда две службы согласовывают полезную нагрузку, общая схема - это контракт. Создание его из реального сообщения и его уточнение дает обеим командам документ, по которому они могут проверить независимо.
Конфиденциальность: почему это работает в вашем браузере
Образцы API являются одними из наиболее чувствительных текстов, которые обрабатывает разработчик. Они обычно содержат токены доступа, идентификаторы сеансов, адреса электронной почты, идентификаторы внутренних записей, а иногда и личные данные, которые никогда не должны быть вставлены в случайную веб-форму. Именно поэтому JSON Schema Generator выполняет всю свою работу на стороне клиента. Анализ, вывод и сериализация происходят в JavaScript в вашем браузере. Ничего не загружается, не регистрируется и не сохраняется на сервере. Вы можете проверить это, открыв вкладку сети во время генерации, или отключившись от Интернета - инструмент все еще работает. Меня это волнует, потому что я не буду использовать инструмент, который отправил свои полезные нагрузки кому-то другому и #39;s сервер, и я бы не просил вас ни о том, ни о другом. Тот же принцип проходит через весь инструментz.dev, который является аргументом, который я подробно приводим в Конфиденциальность данных в онлайн-инстру писать.
Как он подходит для более широкого набора инструментов JSON
Схема - это один артефакт в более крупном рабочем процессе JSON. Прежде чем создать схему, она помогает иметь чистый и действительный вход - the Форматтер JSON отформатирует и проверит полезную нагрузку, чтобы вы не подавали искаженный текст в генератор. после того, как у вас есть схема, вам часто нужны типы для кода вашего приложения, и это где json в машинописный входит. И если ваш конвейер перемещается между форматами, json в yaml конвертер обрабатывает преобразование, которого ожидают многие системы конфигурации и CI. Я написал о том, как эти части соединяются в Полное руководство по инструментам JSONи о сборке более широкого комплекта Набор инструментов для веб-разработчиков обзор. смысл подключенного инструментария в том, что один образец может проходить через несколько инструментов - схему, типы, преобразование формата - никогда не выходя из браузера.
часто задаваемые вопросы
Как сгенерировать схему JSON из JSON?
Вставьте свой JSON в редактор, выберите Draft-07 или 2020-12 и нажмите Generate. инструмент выводит тип каждого поля, извлекает необходимые ключи и выводит схему, которую вы можете скопировать прямо в валидатор. Ничего не загружается - вывод полностью выполняется в вашем браузере.
В чем разница между драфтом-07 и 2020-12?
Это две версии спецификации JSON Schema.Draft-07 имеет самую широкую поддержку в библиотеках и является безопасным по умолчанию.2020-12 является текущим выпуском и изменяет, как массивы и подсхемы выражаются, среди прочего. для объектов и форм массивов этот инструмент производит структуру является одинаковым; основное видимое отличие является $schema идентификатор.
Как инструмент решает, какие поля нужны?
Ключ помечается, когда он появляется в каждом объекте, который видит генератор. Для одного объекта, обозначающего каждый ключ, для массива объектов это означает, что ключи присутствуют во всех элементах. Ключи, которые появляются только в некоторых записях, не содержат обязательных, что отражает то, как API необсуждают необязательные поля. Вы можете полностью отключить обнаружение необходимого поля.
Что происходит с массивом объектов?
Объекты слиты в один items схема, описывающая один элемент, и свойство набирается как массив из него. клавиши, присутствующие в каждом элементе, становятся обязательными; клавиши, присутствующие только в некоторых, остаются необязательными. это сохраняет схему читаемой вместо того, чтобы создавать большой anyOf почти идентичных форм.
Какие строковые форматы он обнаруживает?
Оно признает date-time, date, time, email, uri, uuid, и ipv4 строки и добавляет сопоставление format ключевое слово. обнаружение - это лучшая попытка из одной выборки, поэтому просмотрите результаты - код, который выглядит как UUID, будет помечен как один. Вы можете отключить обнаружение формата, если предпочитаете простые типы строк.
Могу ли я сгенерировать схему из одной выборки?
Да, но один образец показывает только одну возможную форму Поле, которое является числом в вашей выборке может быть нулевым или строкой в другом месте, и необязательное поле, которое случайно присутствует, будет помечено необходимым. чем более репрезентативна выборка - в идеале несколько реальных записей - тем точнее предполагаемые типы и необходимый список.
Готова ли сгенерированная схема к производству?
Относитесь к нему как к сильной отправной точке, а не к готовому документу. вывод точно фиксирует типы, структуру и требуемые поля, но семантические ограничения - перечисления, строковые шаблоны, числовые минимумы и максимумы, форматы, которые он не может видеть из одного значения - все равно необходимо добавлять вручную. создание удаляет утомительные леса, чтобы вы могли сосредоточиться на этих правилах.
Мой json загружен на сервер?
Нет. весь механизм вывода работает как JavaScript в вашем браузере. Ничего не передается, не регистрируется и не сохраняется. Вы можете подтвердить это, наблюдая за вкладкой сети во время генерации, или отключившись от Интернета - инструмент все еще работает.
