JSON Toolkit

Ustrukturyzowane wyniki LLM, które się łamią: jak naprawdę pisać Schema dla trybu strict

Podsumowanie: Włączenie strict na dowolnym JSON Schema prawie zawsze kończy się błędem 400: wszystkie pola required, additionalProperties:false na każdym obiekcie, $ref i allOf od razu odrzucane. Ten przewodnik pokazuje, jak przepisać liberalny schemat na wersję zgodną ze strict — z uniami nullable, twardymi limitami i checklistą dla refusal.

Średni~8 min czytaniaOpublikowano 2026-11-19Zaktualizowano 2026-11-19
Diagram reguł przepisywania JSON Schema dla trybu strict w LLM

Sedno: strict: true nie jest przełącznikiem „bądź bardziej poważny" — to kontrakt, który akceptuje tylko podzbiór JSON Schema. Wszystkie pola required, additionalProperties: false na każdym obiekcie, $ref i allOf od razu zakazane. Wyślesz schemat w trybie strict bez przepisania — odpowiedzią jest 400, a nie niezawodny wynik.

W codziennej praktyce scena powtarza się identycznie: zespół ma dobrze zaprojektowany schemat z polami opcjonalnymi, reużywalnymi $defs i otwartym additionalProperties dla kompatybilności. Potem ktoś dodaje "strict": true do wywołania API, przekonany, że teraz model „będzie respektował" schemat. Natychmiastowym rezultatem jest błąd 400 z długim komunikatem, albo gorzej — przyjęty schemat, który produkuje nieoczekiwany wynik. Tryb strict nie interpretuje schematu z pobłażliwością: przepisuje go od zera do gramatyki, którą silnik generowania może stosować dosłownie, a wszystko, co nie mieści się w tej gramatyce, jest odrzucane albo po cichu ignorowane. Zrozumienie, które reguły naprawdę obowiązują, jeszcze przed wysłaniem żądania, to różnica między stabilnym pipeline a tygodniem debugowania.

Tryb strict = Twoja JSON Schema jest kompilowana do gramatyki, której model musi przestrzegać słowo w słowo. Wszystko, czego gramatyka nie może wyrazić, jest odrzucane przy wysyłce albo po cichu ignorowane — a w obu przypadkach problem ujawnia się po tym, jak zobaczył go użytkownik.

Jak silnik trybu strict naprawdę działa

Modele nie czytają Twojej JSON Schema jak zwykły walidator. Gdy strict: true jest włączone, schemat jest przekształcany w ograniczoną gramatykę — automat skończony, który token po tokenie decyduje, jakie kontynuacje są legalne. Model generuje tylko przejścia dozwolone przez automat; nie ma kontroli po generowaniu, która poprawia wynik — poprawność jest strukturalna.

Ta architektura wyjaśnia wszystkie zachowania, które wydają się zagadkowe. Jeśli pole nie jest zawarte w required, automat musi zdecydować, kiedy się zatrzymać: jedynym bezpiecznym rozwiązaniem jest danie modelowi swobody emisji null, więc efektywny schemat, który otrzymuje silnik, będzie zawierał to pole zawsze. Jeśli obiekt dopuszcza dodatkowe właściwości, automat nie może przewidzieć, jakie klucze się pojawią, więc każdy obiekt musi się twardo zamykać. Każdy „zakaz" w dokumentacji wyrasta z konkretnego ograniczenia tego automatu, a nie ze stylistycznego wyboru OpenAI.

Druga konsekwencja jest bardziej podstępna: niektóre słowa kluczowe JSON Schema (jak pattern, minLength, maximum) są ważne dla schematu, ale niewymuszane przez gramatykę. Schemat jest przyjęty, odpowiedź przychodzi czysta, ale ograniczenie nigdy nie było respektowane. To najcichszy sposób zepsucia pipeline: kolejna walidacja pada w produkcji, a żaden log nie pokazuje błędu schematu.

Trzy reguły bez negocjacji

Jeśli masz czas naprawić tylko jedną rzecz, napraw te trzy. Rozwiązują zdecydowaną większość błędów 400.

1. Wszystkie pola w required, zawsze. W trybie strict każdy klucz zadeklarowany w properties musi pojawić się w required — także opcjonalne. Oficjalnym trikiem na „opcjonalność" jest unia nullable:

{
  "type": "object",
  "properties": {
    "couponCode": { "type": ["string", "null"] }
  },
  "required": ["couponCode"],
  "additionalProperties": false
}

W ten sposób automat wie dokładnie, kiedy klucz jest legalny, a model wyraża „brak kuponu" wartością null zamiast pominięcia klucza.

2. additionalProperties: false na każdym obiekcie. Nie tylko na korzeniu: każdy zagnieżdżony obiekt, bez wyjątków. Jedyny otwarty poziom czyni cały schemat niezgodnym.

3. $ref i allOf zakazane. Żadnych odwołań, żadnych $defs, żadnej kompozycji. Schemat musi być w pełni rozłożony — jedno samodzielne drzewo. if/then/else i oneOf w korzeniu dzielą ten sam los.

Tabela terminów zakazanych i nieskutecznych

Słowo kluczowe Rezultat w trybie strict Zalecany zamiennik
$ref, $defs Odrzucenie z 400 Pełne rozłożenie schematu
allOf Odrzucenie z 400 Ręczne połączenie właściwości
if/then/else Odrzucenie z 400 enum + obsługa po stronie klienta
oneOf w korzeniu Problemy / niezgodna odpowiedź Tylko jeden obiekt korzeniowy
Pole poza required Zamienione na zawsze wymagane Unia nullable ["string", "null"]
pattern, minLength Schemat przyjęty, lecz ograniczenie ignorowane Jawna walidacja po odpowiedzi
maximum, format Schemat przyjęty, lecz ograniczenie ignorowane Weryfikacja po stronie aplikacji

Najgroźniejszy jest ostatni przypadek: schemat przechodzi walidację, ale ograniczenie nie istnieje. Jeśli Twoja logika ufa pattern, budujesz na piasku.

Twarde limity, których nikt nie czyta

Przed napisaniem schematu sprawdź, czy mieścisz się w tych granicach — ich przekroczenie daje ogólne błędy trudne do zdiagnozowania:

Ograniczenie Maksimum
Łączna liczba właściwości na schemat 5000
Głębokość zagnieżdżenia 10 poziomów
Rozmiar ciągu schematu 120 000 znaków
Łączna liczba wartości enum 1000

Schematy generowane automatycznie z frameworków lub definicji OpenAPI często przekraczają te limity niezauważone: 6000 właściwości łącznie, 12 poziomów zagnieżdżenia, 1500 rozproszonych wartości enum. Komunikat błędu API rzadko wskazuje, który próg został przekroczony, więc warto sprawdzić samodzielnie przed wysyłką.

Automatyczne przepisywanie: skrypt make_strict

Dla dużych schematów ręczne przepisywanie jest niepraktyczne. Ten skrypt w Pythonie obchodzi drzewo i rekurencyjnie stosuje trzy reguły:

import json

def make_strict(node):
    if isinstance(node, dict):
        if node.get("type") == "object":
            props = node.get("properties", {})
            # każda właściwość staje się required
            node["required"] = list(props.keys())
            node["additionalProperties"] = False
            # pola „opcjonalne" musisz oznaczyć jako nullable sam, z wyprzedzeniem
        # usuń to, czego strict nie akceptuje
        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))

Dwa ostrzeżenia. Pierwsze: skrypt nie zgaduje, które pola były opcjonalne — unie nullable musisz oznaczyć sam, najlepiej w źródle schematu, nie w wyniku. Drugie: po transformacji zawsze uruchom żądanie próbne: rozłożenie może przekroczyć limity rozmiaru lub liczby właściwości, których wcześniej przestrzegałeś.

Równoważna droga w Anthropic

Anthropic nie udostępnia flagi strict, ale osiąga ten sam rezultat mechanizmem tool: definicja narzędzia pełni rolę schematu, a model jest związany jej kształtem. Podejście jest praktycznie identyczne:

const tool = {
  name: "extract_invoice",
  description: "Wyciąga dane faktury z tekstu",
  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 odpowiada zgodnym wywołaniem narzędzia
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 }]
});

Reguła praktyczna jest ta sama: także u Anthropic każdy obiekt wymaga pełnego required i additionalProperties: false. Różnica tkwi w kanale odpowiedzi — tool_use zamiast treści tekstowej — oraz w tym, że pole refusal jest specyficzne dla OpenAI.

Refusal, ucięcie i złamana forma: trzy usterki, trzy lekarstwa

Nawet z bezbłędnym schematem wynik może zawieść z trzech różnych powodów, a mylenie ich to najszybszy sposób na stracenie dnia:

1. Niepusty refusal. OpenAI w trybie strict może zwrócić pole refusal z powodem, dla którego odmówiła żądania. To nie jest błąd schematu — model semantycznie odmówił zadania. Lekarstwem jest rewizja promptu lub polityki, nie schematu.

2. Ucięcie przez max_tokens. Generowanie przerywa się w połowie ciągu i JSON się nie zamyka. W trybie strict odpowiedź, jeśli przychodzi, jest zgodna — ale jeśli budżet tokenów się skończy, przychodzi ucięta. Podnieś max_tokens lub zmniejsz oczekiwany rozmiar wyniku. Dla powtarzalnych scenariuszy automatyczna naprawa uciętego JSON ma gotowe wzorce.

3. Złamana niezgodna forma. Schemat był otwarty (dodatkowe właściwości dozwolone, pola poza required), a strict nie był włączony: model produkuje poprawny JSON, który nie spełnia kontraktu. Lekarstwem jest przepisanie schematu jak w tym przewodniku, nie dodawanie kontroli po generowaniu.

Właściwa diagnoza zawsze zaczyna się od rozróżnienia tych trzech przypadków: spojrzeć na pole finish_reason, obecność refusal i porównać odpowiedź ze schematem, który został naprawdę wysłany.

Finałowa checklista przed wdrożeniem na produkcję

Punkt kontroli Co sprawdzać
Pełny required Każda zadeklarowana właściwość jest w required
Jawny nullable Pola opcjonalne to unie ["...", "null"]
additionalProperties: false Na każdym obiekcie, nie tylko na korzeniu
Zero $ref / allOf / if-then-else Schemat w pełni rozłożony
Limity dotrzymane ≤ 5000 właściwości, ≤ 10 poziomów, ≤ 120k znaków
Nieskuteczne ograniczenia przeniesione pattern/format weryfikowane w aplikacji
Obsługa refusal Kod rozróżnia odmowę od błędu schematu
Test rzeczywistym żądaniem Próbna odpowiedź zwalidowana przed deployem

Jeśli chcesz zrozumieć, dlaczego additionalProperties: false jest tak centralne, dogłębna analiza słowa kluczowego additionalProperties pokazuje, jak każdy otwarty obiekt rozszerza przestrzeń generowania. Aby wpleść schemat w pipeline CI z automatycznymi testami kontraktowymi, przepływ opisany w JSON Schema contract testing zamyka ciche regresje. A jeśli musisz zbudować schemat z istniejących przykładów JSON, narzędzie konwersji do JSON Schema na platformie startuje od realnych danych — choć dla trybu strict i tak będziesz potrzebować przepisania z tego przewodnika.

FAQ

Dlaczego dokumentacja wymaga, żeby wszystkie pola były required, nawet opcjonalne? Ponieważ automat skończony musi z góry decydować, kiedy każdy klucz jest legalny. „Opcjonalność" wyraża się przez null, nie przez brak klucza: unia nullable to oficjalny sposób, by to powiedzieć.

Schemat został przyjęty, ale pattern nie działa. To bug? Nie. W trybie strict pattern, minLength, maximum i format nie są wymuszane przez gramatykę generowania. Schemat jest składniowo ważny, ale ograniczenia nie ma: weryfikuj po stronie aplikacji.

Mogę użyć $ref, jeśli zadeklaruję też $defs? Nie, w obu przypadkach jest to zakazane. Schemat musi być jednym drzewem, w pełni rozłożonym. Skrypty automatycznego przepisywania załatwiają rozłożenie.

Jaka jest różnica między refusal a błędem schematu? Refusal to zgodna odpowiedź, w której model semantycznie deklaruje, że nie chce wykonać zadania. Błąd schematu to 400 przy wysyłce albo niezgodny wynik. To różne problemy z różnymi lekarstwami.

Jak głęboko mogę zagnieżdżać obiekty? Maksymalnie 10 poziomów zagnieżdżenia i 5000 właściwości łącznie na schemat. Automatycznie generowane schematy często przekraczają te limity: sprawdź przed wysyłką.

Podsumowanie

Tryb strict nie jest opcją kosmetyczną: to przejście od „mam nadzieję, że model respektuje schemat" do „gramatyka fizycznie nie dopuszcza niezgodnego wyniku". Cena to twardy podzbiór JSON Schema — pełny required, zamknięte obiekty, żadnych odwołań — i kilka ograniczeń, które niezauważenie przechodzą, ale nie są wymuszane. Poświęć pół godziny na przepisanie skryptem make_strict, rozsądnie oznacz unie nullable i zawsze testuj rzeczywistym żądaniem przed deployem: pipeline, który z tego wynika, jakościowo różni się od takiego postawionego na retry i późniejszych poprawkach.

Źródła

Powiązane artykuły

Testowanie kontraktowe JSON Schema: przyspawaj reguły walidacji do CI

Schemat nie kończy się napisaniem — tam zaczyna się degradacja. Jedna literówka po cichu rozluźnia walidację, jeden refaktoryzing łamie wszystkie fixture. Ten przewodnik rozbiera użyteczny układ testowania kontraktowego: fixture pozytywne, negatywne i snapshoty, lint samego schematu, jednokrotną kompilację z ponownym użyciem oraz cztery bramy CI, które zamieniają zerwanie kontraktu w czerwony build.

Średni~8 min czytaniaZaktualizowano 2026-11-05

JSON od LLM został ucięty: najpierw sprawdź powód zatrzymania, potem mów o naprawie

Model zwraca JSON urwany w środku wartości, a parser podaje tylko numer kolumny. Domknięcie nawiasów znów pozwala go sparsować, ale każdy brakujący fragment chowa się w danych. Artykuł wyznacza granicę między tym, co naprawa ucięcia może uczciwie odzyskać, a tym, co trzeba zlecić ponownie.

Praktyka~5 min czytaniaZaktualizowano 2026-11-14

Bez additionalProperties walidacja schematu nic nie sprawdza

Zdana walidacja nie oznacza czystych danych. Pydantic domyślnie ignoruje nieznane pola, Zod je usuwa, Ajv przepuszcza — zmyślone parametry i literówki przechodzą po cichu. Artykuł pokazuje trzy formy cichej akceptacji i daje pełne przepisy: zamykać obiekty, kontrolować koercję, zaciskać każdy poziom zagnieżdżenia.

Intermediate~8 min czytaniaZaktualizowano 2026-11-02