Strukturované výstupy LLM, které se láme: jak opravdu psát Schema pro režim strict
Shrnutí: Zapnutí strict na libovolné JSON Schema skončí téměř vždy chybou 400: všechna pole required, additionalProperties:false na každém objektu, $ref a allOf jsou okamžitě odmítnuty. Tento průvodce ukazuje, jak přepsat liberální schéma na verzi kompatibilní se strict — s nullable spojeními, tvrdými limity a checklistem pro refusal.

To podstatné: strict: true není vypínač „buď víc vážný" — je to smlouva, která přijímá jen podmnožinu JSON Schema. Všechna pole required, additionalProperties: false na každém objektu, $ref a allOf hned zakázány. Pošlete-li schéma v režimu strict bez přepisu, odpovědí je 400, ne spolehlivý výstup.
V každodenní praxi se scéna opakuje: tým má dobře navržené schéma s nepovinnými poli, znovupoužitelnými $defs a otevřeným additionalProperties kvůli kompatibilitě. Pak někdo přidá "strict": true k volání API, přesvědčený, že teď model schéma „bude respektovat". Okamžitým výsledkem je chyba 400 s dlouhou zprávou, nebo hůř — přijaté schéma, které produkuje nečekaný výstup. Režim strict neinterpretuje schéma s tolerancí: přepisuje ho do gramatiky, kterou generátor může dodržovat doslova, a vše, co se do ní nevejde, je odmítnuto nebo tiše ignorováno. Pochopení toho, která pravidla skutečně platí, ještě před odesláním požadavku, je rozdíl mezi stabilním pipeline a týdnem ladění.
Režim strict = vaše JSON Schema je zkompilována do gramatiky, kterou musí model následovat slovo za slovem. Vše, co gramatika nedokáže vyjádřit, je při odeslání odmítnuto nebo tiše ignorováno — a v obou případech se problém projeví poté, co ho uživatel už viděl.
Jak motor strict mode skutečně funguje
Modely nečtou vaši JSON Schema jako běžný validátor. Když je strict: true aktivní, schéma se transformuje na omezenou gramatiku — konečný automat, který token po tokenu rozhoduje, která pokračování jsou legální. Model generuje jen přechody povolené automatem; žádná post-generační kontrola výstup neopravuje, správnost je strukturální.
Tato architektura vysvětluje všechno chování, které působí záhadně. Není-li pole zahrnuto v required, musí se automat rozhodnout, kdy zastavit: jediné bezpečné řešení je dát modelu svobodu emitovat null, takže efektivní schéma, které motor dostane, bude mít toto pole vždy přítomné. Dovoluje-li objekt dodatečné vlastnosti, automat nemůže předvídat, jaké klíče se objeví, takže každý objekt se musí tvrdě uzavřít. Každý „zakázaný" prvek v dokumentaci vyrůstá z konkrétního omezení tohoto automatu, ne ze stylistické volby OpenAI.
Druhý důsleb je záludnější: některá klíčová slova JSON Schema (jako pattern, minLength, maximum) jsou pro schéma platná, ale gramatika je nevynucuje. Schéma je přijato, odpověď přijde čistá, ale omezení nikdy nebylo dodrženo. Je to nejtišší způsob, jak rozbít pipeline: následná validace selže v produkci a žádný log neukáže chybu schématu.
Tři pravidla, o kterých se nedá vyjednávat
Pokud máte čas opravit jen jednu věc, opravte tyto tři. Vyřeší převážnou většinu chyb 400.
1. Všechna pole v required, vždy. V režimu strict musí být každý klíč deklarovaný v properties uveden i v required — i nepovinné. Oficiální trik, jak říci „nepovinné", je nullable spojení:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
Tak automat přesně ví, kdy je klíč legální, a model vyjadřuje „slevový kód chybí" hodnotou null místo vynechání klíče.
2. additionalProperties: false na každém objektu. Nejen na kořenovém: každý vnořený objekt, bez výjimek. Jediná otevřená úroveň učiní celé schéma nevyhovujícím.
3. $ref a allOf jsou zakázány. Žádné odkazy, žádné $defs, žádná kompozice. Schéma musí být zcela rozvinuté — jediný samostatný strom. if/then/else a oneOf v kořeni sdílejí stejný osud.
Tabulka zakázaných a neúčinných termínů
| Klíčové slovo | Výsledek v režimu strict | Doporučená náhrada |
|---|---|---|
$ref, $defs |
Odmítnuto s 400 | Plné rozvinutí schématu |
allOf |
Odmítnuto s 400 | Ruční sloučení vlastností |
if/then/else |
Odmítnuto s 400 | enum + zpracování na klientovi |
oneOf v kořeni |
Problémy / nevyhovující odpověď | Jen jeden kořenový objekt |
Pole mimo required |
Změněno na vždy povinné | Nullable spojení ["string", "null"] |
pattern, minLength |
Schéma přijato, ale omezení ignorováno | Explicitní validace po odpovědi |
maximum, format |
Schéma přijato, ale omezení ignorováno | Kontrola na straně aplikace |
Nejnebezpečnější je poslední pár: schéma projde validací, ale omezení neexistuje. Pokud vaše logika věří pattern, stavíte na písku.
Tvrdé limity, které nikdo nečte
Před psaním schématu ověřte, že zůstáváte v těchto hranicích — jejich překročení způsobuje obecné chyby těžko diagnostikovatelné:
| Omezení | Maximum |
|---|---|
| Celkem vlastností na schéma | 5000 |
| Hloubka zanoření | 10 úrovní |
| Velikost řetězce schématu | 120 000 znaků |
| Celkem hodnot enum | 1000 |
Schémata generovaná automaticky z frameworků nebo definic OpenAPI často tyto limity překračují, aniž by si to kdokoli všiml: 6000 vlastností celkem, 12 úrovní zanoření, 1500 roztroušených hodnot enum. Chybová zpráva API zřídka uvádí, který práh byl překročen, proto je lepší zkontrolovat to samému před odesláním.
Automatický přepis: skript make_strict
Pro velká schémata není ruční přepis praktický. Tento skript v Pythonu prochází strom a rekurzivně aplikuje tři pravidla:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# každá vlastnost se stává required
node["required"] = list(props.keys())
node["additionalProperties"] = False
# „nepovinná" pole musíte označit jako nullable sami, předem
# odstranit to, co strict nepřijímá
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))
Dvě upozornění. První: skript neodhaduje, která pole byla nepovinná — nullable spojení musíte označit sami, ideálně ve zdrojovém schématu, ne ve výsledku. Druhé: po transformaci vždy spusťte zkušební požadavek: rozvinutí může překročit limity velikosti nebo počtu vlastností, které jste dříve dodržovali.
Ekvivalentní cesta v Anthropic
Anthropic nevystavuje příznak strict, ale k témuž výsledku dochází mechanismem tool: definice nástroje slouží jako schéma a model je vázán na její tvar. Přístup je prakticky identický:
const tool = {
name: "extract_invoice",
description: "Vytáhne údaje faktury z textu",
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
}
};
// model odpovídá vyhovujícím voláním tool
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 }]
});
Praktické pravidlo je stejné: i u Anthropic potřebuje každý objekt kompletní required a additionalProperties: false. Rozdíl je v kanálu odpovědi — tool_use místo textového obsahu — a v tom, že pole refusal je specifické pro OpenAI.
Refusal, oříznutí a rozbitý tvar: tři poruchy, tři léky
I s bezchybným schématem může výstup selhat ze tří různých důvodů a záměna mezi nimi je nejrychlejší cesta ke ztrátě dne:
1. Neprázdný refusal. OpenAI v režimu strict může vrátit pole refusal s důvodem, proč žádost odmítla. Není to chyba schématu — model úlohu sémanticky odmítl. Lékem je revize promptu nebo politiky, ne schématu.
2. Oříznutí kvůli max_tokens. Generace se přeruší uprostřed řetězce a JSON se neuzavře. V režimu strict je odpověď, pokud dorazí, vyhovující — ale pokud vyprší rozpočet tokenů, dorazí oříznutá. Zvyšte max_tokens nebo zmenšete očekávaný rozsah výstupu. Pro opakované scénáře nabízí automatická oprava oříznutého JSON hotové vzory.
3. Rozbitý nevyhovující tvar. Schéma bylo otevřené (dovolené dodatečné vlastnosti, pole mimo required) a strict nebyl aktivní: model produkuje platný JSON, který nesplňuje kontrakt. Lékem je přepsat schéma jako v tomto průvodci, ne přidávat post-generační kontroly.
Správná diagnostika vždy začíná rozlišením těchto tří případů: podívat se na pole finish_reason, přítomnost refusal a porovnat odpověď se schématem, které bylo skutečně odesláno.
Závěrečný checklist před nasazením do produkce
| Bod kontroly | Co ověřit |
|---|---|
Kompletní required |
Každá deklarovaná vlastnost je v required |
| Explicitní nullable | Nepovinná pole jsou spojení ["...", "null"] |
additionalProperties: false |
Na každém objektu, ne jen na kořeni |
Nula $ref / allOf / if-then-else |
Schéma zcela rozvinuto |
| Limity dodrženy | ≤ 5000 vlastností, ≤ 10 úrovní, ≤ 120k znaků |
| Neúčinná omezení přesunuta | pattern/format se ověřují v aplikaci |
Zpracování refusal |
Kód rozlišuje odmítnutí od chyby schématu |
| Test reálným požadavkem | Zkušební odpověď validována před deployem |
Pokud chcete pochopit, proč je additionalProperties: false tak ústřední, hloubková analýza klíčového slova additionalProperties ukazuje, jak každý otevřený objekt rozšiřuje prostor generace. K začlenění schématu do CI pipeline s automatickými kontraktními testy slouží tok popsaný v JSON Schema contract testing, který zavírá tiché regrese. A když potřebujete postavit schéma z existujících JSON ukázek, nástroj konverze do JSON Schema na platformě vás startuje od reálných dat — i když pro režim strict budete stejně potřebovat přepis z tohoto průvodce.
FAQ
Proč dokumentace vyžaduje, aby všechna pole byla required, i nepovinná?
Protože konečný automat musí předem rozhodovat, kdy je každý klíč legální. „Nepovinnost" se vyjadřuje hodnotou null, ne absencí klíče: nullable spojení je oficiální způsob, jak to říci.
Schéma bylo přijato, ale pattern nefunguje. Je to bug?
Ne. V režimu strict nejsou pattern, minLength, maximum ani format vynucovány generující gramatikou. Schéma je syntakticky platné, ale omezení neexistuje: kontrolujte na straně aplikace.
Mohu použít $ref, když deklaruji i $defs?
Ne, v obou případech je to zakázáno. Schéma musí být jediný strom, zcela rozvinutý. Skripty automatického přepisu rozvinutí zajistí.
Jaký je rozdíl mezi refusal a chybou schématu? Refusal je vyhovující odpověď, ve které model sémanticky deklaruje, že úlohu nechce provést. Chyba schématu je 400 při odeslání nebo nevyhovující výstup. Jsou to různé problémy s různými léky.
Jak hluboko mohu vnořovat objekty? Maximálně 10 úrovní zanoření a 5000 vlastností celkem na schéma. Automaticky generovaná schémata tyto limity často překračují: ověřte před odesláním.
Závěr
Režim strict není kosmetická volba: je to přechod od „doufám, že model schéma respektuje" k „gramatika fyzicky neumožňuje nevyhovující výstup". Cena je tvrdá podmnožina JSON Schema — kompletní required, uzavřené objekty, žádné odkazy — a několik omezení, která nenápadně projdou, ale nevynutí se. Věnujte půl hodiny přepisu skriptem make_strict, rozumně označte nullable spojení a vždy testujte reálným požadavkem před deployem: pipeline, která z toho vznikne, je kvalitativně jiná než taková postavená na retraiích a následných opravách.