JSON Toolkit

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.

Střední~8 min čteníPublikováno 2026-11-19Aktualizováno 2026-11-19
Diagram pravidel přepisu JSON Schema pro režim strict v LLM

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.

Zdroje

Související články

Kontraktní testování JSON Schema: svařte validační pravidla do CI

Schéma nekončí napsáním — tam začíná úpadek. Jedno překlepnutí potichu uvolní validaci, jeden refaktoring rozbije všechny fixture. Tato příručka rozebírá použitelné uspořádání kontraktního testování: pozitivní, negativní a snapshot fixture, lint samotného schématu, jednorázovou kompilaci s opakovaným použitím a čtyři brány CI, které promění porušení kontraktu v červený build.

Střední~8 min čteníAktualizováno 2026-11-05

Bez additionalProperties validace schématu nic nevaliduje

Úspěšná validace neznamená čistá data. Pydantic standardně ignoruje neznámá pole, Zod je odstraní, Ajv je pustí — vymyšlené parametry a překlepy projdou potichu. Článek ukazuje tři formy tiché acceptance a dává kompletní recepty: zavřít objekty, zkontrolovat koerci, dotáhnout každou úroveň zanoření.

Intermediate~8 min čteníAktualizováno 2026-11-02