BroadRouter
Начать

JSON Schema (JSON-схема)

Обновлено

JSON Schema — это словарь, записанный на самом JSON, для описания и валидации структуры JSON-данных: типов, обязательных полей, допустимых значений и вложенности. Текущая версия — 2020-12. API языковых моделей используют его, чтобы задать параметры инструментов и точную форму структурированного вывода.

Также называют: JSON-схема, схема JSON, json schema валидация, json_schema, JSON Schema, JSON Schema draft 2020-12

Промпт «ответь в JSON» оставляет форму ответа на волю случая. JSON Schema записывает эту форму так, чтобы её могла проверить программа.

Как это работает

Спецификация состоит из двух основных частей: Core, которая “defines the basic foundation of JSON Schema” (перевод: «задаёт базовую основу JSON Schema»), и Validation, которая “defines the validation keywords” (перевод: «определяет ключевые слова валидации»). Текущая версия — 2020-12, предыдущая — 2019-09.

{
  "type": "object",
  "properties": {
    "name":    {"type": "string"},
    "amount":  {"type": "number", "minimum": 0},
    "currency": {"type": "string", "enum": ["SAR", "AED", "USD"]},
    "note":    {"type": ["string", "null"]}
  },
  "required": ["name", "amount", "currency", "note"],
  "additionalProperties": false
}

API языковых моделей используют схемы в двух местах. Определение инструмента кладёт схему в parameters, чтобы описать аргументы. Структурированный вывод передаёт её в response_format как {"type": "json_schema", "json_schema": {...}}; по словам OpenAI, это “ensures the model will match your supplied JSON schema” (перевод: «гарантирует, что модель будет соответствовать переданной вами JSON-схеме»).

Строгий режим OpenAI принимает только подмножество. Из раздела о поддерживаемых схемах:

  • Типы: string, number, boolean, integer, object, array, enum и anyOf.
  • Корень должен быть объектом и не может использовать anyOf.
  • additionalProperties: false, и каждое поле указано в required; чтобы сделать поле необязательным, разрешите null, как у note выше.
  • До 5000 свойств объектов и до 10 уровней вложенности, а всего не более 1000 значений enum.
  • Не поддерживаются: allOf, not, dependentRequired, dependentSchemas, if, then, else.

Почему это важно

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

В BroadNet Inference

Справочник API BroadNet описывает вызов инструментов и структурированный вывод для GLM 5.3 и Qwen3.8 27B, но не говорит, какие ключевые слова схемы соблюдаются. Держитесь простого подмножества, описанного выше, и проверяйте каждый ответ. Составьте схему в генераторе JSON Schema, проверяйте ответы валидатором JSON-вывода LLM, а полный пример смотрите в статье о структурированном выводе. На других моделях просите JSON в промпте и проверяйте ответ; JSON mode в документации BroadNet не описан, поэтому протестируйте его, прежде чем на него полагаться.

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

  • Использовать allOf или условные ключевые слова и считать, что сервер их соблюдает.
  • Делать поля необязательными в строгом режиме, убирая их из required, вместо того чтобы разрешить null.

Вопросы и ответы

Поддерживают ли API языковых моделей JSON Schema целиком?

Нет. OpenAI поддерживает подмножество: например, корень должен быть объектом, каждое поле должно быть обязательным, additionalProperties должно быть false, а ключевые слова вроде allOf, not и if/then/else не поддерживаются.

Чем JSON Schema отличается от JSON mode?

JSON mode обещает только валидный JSON. JSON Schema сообщает модели и вашему валидатору, какие поля и типы должны быть в этом JSON.

Можно ли использовать JSON Schema с BroadNet Inference?

Параметры инструментов и структурированный вывод, которые используют схемы, описаны для GLM 5.3 и Qwen3.8 27B. BroadNet не указывает, какие ключевые слова схемы соблюдаются, поэтому проверяйте каждый ответ.

Открыть в MarkdownСпросить ChatGPTСпросить ClaudeСпросить Perplexity