Структурированные выводы LLM ломаются: как на самом деле писать Schema для режима strict
Главное: Включение strict на произвольной JSON Schema почти всегда возвращает 400: все поля required, additionalProperties:false на каждом объекте, $ref и allOf сразу отклоняются. Это руководство показывает, как переписать свободную схему в версию, совместимую с strict — с nullable-объединениями, жёсткими лимитами и чек-листом по refusal.

Суть: strict: true — не переключатель «быть посерьёзнее», а контракт, принимающий лишь подмножество JSON Schema. Все поля required, additionalProperties: false на каждом объекте, $ref и allOf запрещены сразу. Отправите схему в режиме strict без переписывания — получите 400, а не надёжный вывод.
В повседневной практике сцена повторяется одно и то же: у команды есть аккуратная схема с опциональными полями, переиспользуемыми $defs и открытым additionalProperties ради совместимости. Потом кто-то добавляет "strict": true в вызов API, уверенный, что теперь модель «будет уважать» схему. Немедленный результат — ошибка 400 с длинным сообщением, или хуже: схема принята, но вывод непредсказуем. Режим strict не интерпретирует схему с уступками: он переписывает её в грамматику, которую движок генерации может буквально соблюдать, и всё, что в эту грамматику не помещается, отклоняется или молча игнорируется. Понимание того, какие правила действительно действуют, до отправки запроса — разница между стабильным пайплайном и неделей отладки.
Режим strict = ваша JSON Schema компилируется в грамматику, которой модель обязана следовать слово за словом. Всё, что грамматика не может выразить, отклоняется при отправке или молча игнорируется — и в обоих случаях проблема проявляется после того, как её увидел пользователь.
Как на самом деле устроен движок strict mode
Модели не читают вашу JSON Schema как обычный валидатор. Когда strict: true включён, схема преобразуется в ограниченную грамматику — конечный автомат, который токен за токеном решает, какие продолжения допустимы. Модель порождает только разрешённые автоматом переходы; никакого пост-контроля, исправляющего вывод, нет — корректность структурная.
Эта архитектура объясняет всё поведение, которое кажется загадочным. Если поле не включено в required, автомат должен решить, когда остановиться: единственное безопасное решение — дать модели право выдавать null, поэтому эффективная схема, которую получает движок, будет содержать это поле всегда. Если объект допускает дополнительные свойства, автомат не может предсказать, какие ключи появятся, значит каждый объект должен жёстко закрываться. Каждый «запрет» в документации вырастает из конкретного ограничения этого конечного автомата, а не из стилистического выбора OpenAI.
Второе следствие коварнее: некоторые ключевые слова JSON Schema (как pattern, minLength, maximum) валидны для схемы, но не применяются грамматикой. Схема принимается, ответ приходит чистым, но ограничение никогда не соблюдалось. Это самый тихий способ сломать пайплайн: последующая валидация падает в продакшене, и ни один лог не показывает ошибку схемы.
Три правила, которые нельзя обойти
Если есть время починить только одну вещь — почините эти три. Они решают подавляющее большинство 400.
1. Все поля в required, всегда. В режиме strict каждый ключ, объявленный в properties, должен появиться в required — даже опциональные. Официальный способ сказать «опционально» — nullable-объединение:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
Так автомат знает, когда ключ допустим, а модель выражает «купон отсутствует» значением null, а не отсутствием ключа.
2. additionalProperties: false на каждом объекте. Не только на корневом: каждый вложенный объект, без исключений. Один открытый уровень делает всю схему несоответствующей.
3. $ref и allOf запрещены. Никаких ссылок, никаких $defs, никакой композиции. Схема должна быть полностью развёрнута — единое самостоятельное дерево. if/then/else и oneOf в корне разделяют ту же судьбу.
Таблица запрещённых и бездействующих терминов
| Ключевое слово | Результат в strict mode | Рекомендуемая замена |
|---|---|---|
$ref, $defs |
Отклонение с 400 | Полное разворачивание схемы |
allOf |
Отклонение с 400 | Ручное объединение свойств |
if/then/else |
Отклонение с 400 | enum + обработка на клиенте |
oneOf в корне |
Проблемы / несоответствующий ответ | Один корневой объект |
Поле вне required |
Становится всегда обязательным | Nullable-объединение ["string", "null"] |
pattern, minLength |
Схема принята, но ограничение игнорируется | Явная валидация после ответа |
maximum, format |
Схема принята, но ограничение игнорируется | Проверка на стороне приложения |
Самая опасная строка — последняя пара: схема проходит валидацию, но ограничения не существует. Если ваша логика доверяет pattern, вы строите на песке.
Жёсткие лимиты, которые никто не читает
Перед написанием схемы убедитесь, что вы внутри этих границ — их превышение порождает общие ошибки, которые трудно диагностировать:
| Ограничение | Максимум |
|---|---|
| Всего свойств на схему | 5000 |
| Глубина вложенности | 10 уровней |
| Размер строки схемы | 120 000 символов |
| Всего значений enum | 1000 |
Схемы, автоматически генерируемые фреймворками или определениями OpenAPI, часто превышают эти лимиты незаметно: 6000 свойств суммарно, 12 уровней вложенности, 1500 разбросанных значений enum. Сообщение об ошибке API редко указывает, какой порог превышен, поэтому стоит проверить самому до отправки.
Автоматическое переписывание: скрипт make_strict
Для больших схем ручное переписывание непрактично. Этот скрипт на Python обходит дерево и рекурсивно применяет три правила:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# каждое свойство становится required
node["required"] = list(props.keys())
node["additionalProperties"] = False
# «опциональные» поля нужно заранее пометить nullable
# удалить то, что strict не принимает
for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
node.pop(k, None)
return {k: make_strict(v) for k, v in node.items()}
if isinstance(node, list):
return [make_strict(v) for v in node]
return node
schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))
Два предупреждения. Первое: скрипт не угадывает, какие поля были опциональными — nullable-объединения придётся помечать самому, желательно в исходной схеме, а не в результате. Второе: после преобразования всегда выполняйте пробный запрос: разворачивание может превысить лимиты размера или свойств, которые раньше соблюдались.
Эквивалентный путь в Anthropic
Anthropic не предоставляет флаг strict, но достигает того же результата механизмом tool: определение инструмента выступает схемой, и модель связана её формой. Подход практически идентичен:
const tool = {
name: "extract_invoice",
description: "Извлекает данные счёта из текста",
input_schema: {
type: "object",
properties: {
invoiceNumber: { type: "string" },
totalAmount: { type: ["number", "null"] },
lineItems: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" }
},
required: ["description", "quantity"],
additionalProperties: false
}
}
},
required: ["invoiceNumber", "totalAmount", "lineItems"],
additionalProperties: false
}
};
// модель отвечает соответствующим вызовом инструмента
const response = await anthropic.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
tools: [tool],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: invoiceText }]
});
Практическое правило то же: и в Anthropic каждый объект требует полного required и additionalProperties: false. Разница — в канале ответа (tool_use вместо текстового содержимого) и в том, что поле refusal специфично для OpenAI.
Refusal, обрыв и сломанная форма: три неисправности, три средства
Даже с идеальной схемой вывод может провалиться по трём разным причинам, и путать их — самый быстрый способ потерять день:
1. Непустой refusal. OpenAI в режиме strict может вернуть поле refusal с причиной, по которой отклонила запрос. Это не ошибка схемы — модель семантически отказалась от задачи. Средство — пересмотреть промпт или политику, не схему.
2. Обрыв из-за max_tokens. Генерация прерывается посреди строки, и JSON не закрывается. В режиме strict ответ, если приходит, соответствует схеме — но если бюджет токенов исчерпан, приходит обрезанным. Увеличьте max_tokens или уменьшите ожидаемый объём вывода. Для повторяющихся сценариев автоматический починка обрезанного JSON предлагает готовые паттерны.
3. Сломанная несоответствующая форма. Схема была открытой (допускались дополнительные свойства, поля вне required), а strict не был включён: модель выдаёт валидный JSON, не соблюдающий контракт. Средство — переписать схему, как в этом руководстве, а не добавлять пост-валидацию.
Правильная диагностика всегда начинается с различения этих трёх случаев: посмотреть поле finish_reason, наличие refusal и сравнить ответ со схемой, которая была действительно отправлена.
Финальный чек-лист перед выводом в продакшен
| Точка проверки | Что проверять |
|---|---|
Полный required |
Каждое объявленное свойство есть в required |
| Явный nullable | Опциональные поля — объединения ["...", "null"] |
additionalProperties: false |
На каждом объекте, не только на корневом |
Ноль $ref / allOf / if-then-else |
Схема полностью развёрнута |
| Лимиты соблюдены | ≤ 5000 свойств, ≤ 10 уровней, ≤ 120k символов |
| Бездействующие ограничения перенесены | pattern/format проверяются на стороне приложения |
Обработка refusal |
Код отличает отказ от ошибки схемы |
| Тест реальным запросом | Пробный ответ провалидирован до деплоя |
Если хотите понять, почему additionalProperties: false так центрально, глубокий разбор ключевого слова additionalProperties показывает, как каждый открытый объект расширяет пространство генерации. Чтобы встроить схему в CI-пайплайн с автоматическими контрактными тестами, поток, описанный в JSON Schema contract testing, закрывает тихие регрессии. А если нужно построить схему из существующих JSON-примеров, инструмент конвертации в JSON Schema платформы стартует от реальных данных — хотя для режима strict всё равно потребуется переписывание из этого руководства.
FAQ
Почему документация требует, чтобы все поля были required, даже опциональные?
Потому что конечный автомат должен заранее решать, когда каждый ключ допустим. «Опциональность» выражается через null, а не отсутствием ключа: nullable-объединение — официальный способ это сказать.
Схема принята, но pattern не работает. Это баг?
Нет. В strict mode pattern, minLength, maximum и format не применяются грамматикой генерации. Схема синтаксически валидна, но ограничения не существует: проверяйте на стороне приложения.
Могу ли я использовать $ref, если объявлю и $defs?
Нет, в обоих случаях запрещено. Схема должна быть единым деревом, полностью развёрнутым. Скрипты автоматического переписывания справляются с разворачиванием.
В чём разница между refusal и ошибкой схемы? Refusal — соответствующий ответ, где модель семантически заявляет, что не хочет выполнять задачу. Ошибка схемы — это 400 при отправке или несоответствующий вывод. Это разные проблемы с разными средствами.
Насколько глубоко можно вкладывать объекты? Максимум 10 уровней вложенности и 5000 свойств суммарно на схему. Автогенерируемые схемы часто превышают эти лимиты: проверяйте до отправки.
Заключение
Режим strict — не косметическая опция: это переход от «надеюсь, модель соблюдает схему» к «грамматика физически не допускает несоответствующий вывод». Плата — жёсткое подмножество JSON Schema — полный required, закрытые объекты, никаких ссылок — и несколько ограничений, которые незаметно проходят, но не применяются. Потратьте полчаса на переписывание скриптом make_strict, разумно пометьте nullable-объединения и всегда тестируйте реальным запросом до деплоя: пайплайн, построенный так, качественно отличается от построенного на ретраях и последующих исправлениях.