Przejdź do głównej treści
Polski— Wybierz język
Menu

Walidacja za pomocą JSON Schema i Zod

Lekcja 11 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Walidacja za pomocą JSON Schema i Zod
  2. Dlaczego walidować po otrzymaniu danych
  3. Walidacja w Pythonie za pomocą jsonschema
  4. Walidacja za pomocą Pydantic
  5. Walidacja za pomocą Zod (TypeScript/Node.js)
  6. Wzorzec: ponowienie z korektą
  7. Stanowisko testowe dla zaproszeń kalendarzowych
  8. Kluczowe wnioski

Lekcja zaktualizowana 3 listopada 2026 r. na podstawie dokumentacji OpenAI: parametry temperature i top_p są akceptowane tylko przy wysiłku rozumowania (reasoning effort) ustawionym na none, podczas gdy modele GPT-5.6 domyślnie rozumują (medium). Wywołania ustawiające te parametry muszą zatem określać reasoning={"effort": "none"} (Responses API) lub reasoning_effort="none" (Chat Completions). Źródła: Using GPT-6 · GPT-5.6 Terra.

Walidacja za pomocą JSON Schema i Zod

Wyjście strukturyzowane (Structured Output) gwarantuje strukturę odpowiedzi, ale nie semantyczną poprawność danych. Pole „email“ może zawierać ciąg znaków, który nie jest prawidłowym adresem e-mail. Walidacja po stronie klienta przy użyciu JSON Schema lub Zod jest niezbędnym uzupełnieniem tworzącym solidny pipeline.

Dlaczego walidować po otrzymaniu danych

Przeanalizujmy, co gwarantuje API, a podział zadań stanie się jasny. Strukturyzowane wyjście OpenAI zapewnia, że JSON jest syntaktycznie poprawny, że zadeklarowane typy są przestrzegane – ciąg znaków pozostaje ciągiem, liczba całkowita liczbą całkowitą – że wszystkie wymagane pola są obecne, a wartości ograniczone przez enum należą do listy. W tych czterech kwestiach możesz pisać kod z pełnym zaufaniem.

Reszta leży po Twojej stronie i obejmuje cztery rodziny problemów. Ograniczenia formatu wymykają się ścisłej schemie: nic nie powstrzyma modelu przed zwróceniem jean.dupont(at)example.fr w polu email lub daty w formacie 15/03/2026, gdy oczekujesz ISO. Granice również nie są sprawdzane – ani długość ciągu, ani zakres liczby: wiek 350 lat przejdzie bez mrugnięcia okiem. Spójność między polami pozostaje poza zasięgiem – end_date wcześniejsza niż start_date to całkowicie poprawny JSON. Ważność biznesowa również nie dotyczy API: numer SIRET (francuski identyfikator firmy) musi mieć czternaście cyfr, ale to wiedza Twojej domeny, a nie dekodera.

Te cztery rodziny łączy jedna przerażająca cecha: nie powodują widocznych błędów. Źle sformatowany e-mail zapisany w bazie danych ujawni się dopiero, gdy kampania mailingowa zostanie odrzucona tygodnie później. Stąd zasada: waliduj przed trwałym zapisem, nigdy po.

Walidacja w Pythonie za pomocą jsonschema

Praktyczną konsekwencją jest potrzeba posiadania dwóch schematów dla tych samych danych. Pierwszy trafia do API – jest celowo odchudzony, ograniczony do tego, co tryb ścisły akceptuje. Drugi pozostaje u Ciebie i niesie drobne ograniczenia – format, pattern, minimum, maximum. Ta pozorna duplikacja to w rzeczywistości rozdzielenie odpowiedzialności: jeden ramuje generowanie, drugi broni Twojego magazynu danych. W poniższym przykładzie tylko wyliczenie enum dla roli pojawia się w obu schematach, ponieważ jest to jedyne ograniczenie, które oba poziomy mogą wyrazić.

import json
from jsonschema import validate, ValidationError

# Schemat dla OpenAI API (ścisły, bez format/pattern)
api_schema = {
    "type": "object",
    "properties": {
        "email": {"type": "string"},
        "age": {"type": "integer"},
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"],
    "additionalProperties": False
}

# Rozszerzony schemat do walidacji po stronie klienta
validation_schema = {
    "type": "object",
    "properties": {
        "email": {
            "type": "string",
            "format": "email",
            "pattern": r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z]{2,}$"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150
        },
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"]
}

def validate_response(data: dict) -> tuple[bool, str]:
    """Waliduje odpowiedź LLM względem rozszerzonego schematu."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Valid"
    except ValidationError as e:
        return False, f"Error: {e.message}"

Walidacja za pomocą Pydantic

Pydantic jest często wygodniejszy niż jsonschema do walidacji w Pythonie, a różnica polega na tym, co otrzymujesz na wyjściu. jsonschema mówi tylko „tak“ lub „nie“ i zostawia Cię ze słownikiem, którym manipulujesz przez data["email"] bez pomocy edytora. Pydantic zwraca typowany obiekt: działa autouzupełnianie, literówka w nazwie atrybutu zostanie wykryta już podczas pisania kodu, a dane krążą dalej bez konieczności konwersji.

Model ContactExtraction wyraża granice bezpośrednio w deklaracjach pól. Dekorator field_validator dla date_extraction obsługuje przypadek, którego żadna adnotacja typu nie wychwyci: ciąg jest rzeczywiście ciągiem, ale musi reprezentować rzeczywistą datę – 2026-02-31 spełnia każdy rozsądny pattern, a jednak nie istnieje. Funkcja ekstrakcji pokazuje pełny łańcuch: od odchudzonego schematu wysyłanego do API, aż po zwalidowaną instancję.

from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date

class ContactExtraction(BaseModel):
    """Schemat walidacji dla ekstrakcji kontaktów."""
    last_name: str = Field(min_length=2, max_length=100)
    first_name: str = Field(min_length=2, max_length=100)
    email: EmailStr
    phone: str = Field(pattern=r"^\+?[0-9\s\-\.]{10,15}$")
    company: str
    title: str
    extraction_date: str

    @field_validator("extraction_date")
    @classmethod
    def validate_date(cls, v):
        try:
            date.fromisoformat(v)
            return v
        except ValueError:
            raise ValueError(f"Invalid date: {v}")

def extract_and_validate(text: str) -> ContactExtraction:
    """Ekstrahuje kontakt i waliduje dane."""
    # Schemat dla API (bez drobnych ograniczeń)
    api_schema = {
        "type": "object",
        "properties": {
            "last_name": {"type": "string"},
            "first_name": {"type": "string"},
            "email": {"type": "string"},
            "phone": {"type": "string"},
            "company": {"type": "string"},
            "title": {"type": "string"},
            "extraction_date": {"type": "string"}
        },
        "required": ["last_name", "first_name", "email", "phone",
                      "company", "title", "extraction_date"],
        "additionalProperties": False
    }

    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Extract contact information. "
                     "Date format: YYYY-MM-DD.",
        input=text,
        text={
            "format": {
                "type": "json_schema",
                "name": "contact",
                "schema": api_schema,
                "strict": True
            }
        }
    )

    data = json.loads(response.output_text)
    # Walidacja Pydantic z drobnymi ograniczeniami
    return ContactExtraction(**data)

Walidacja za pomocą Zod (TypeScript/Node.js)

Jeśli Twój backend jest napisany w TypeScript, Zod jest narzędziem referencyjnym i wnosi przewagę, której Pydantic nie musi zapewniać: z.infer wyprowadza typ TypeScript bezpośrednio ze schematu walidacji. Opisujesz kształt raz, a kompilator zna następnie strukturę Invoice bez konieczności utrzymywania równoległego interfejsu, więc nie ma ryzyka rozbieżności.

Poniższy schemat faktury ilustruje podział zadań: po stronie API siret to po prostu ciąg znaków; po stronie Zod musi mieć dokładnie czternaście znaków i zawierać tylko cyfry. Końcowe wywołanie parse zgłosi wyjątek, jeśli dane nie pasują, i taki jest pożądany efekt – głośny błąd przerywający przetwarzanie dokumentu jest lepszy niż faktura z fikcyjnym numerem SIRET zapisana w bazie danych wśród dziesięciu tysięcy innych.

import { z } from "zod";
import OpenAI from "openai";

const client = new OpenAI();

// Schemat Zod z drobnymi walidacjami
const InvoiceSchema = z.object({
  number: z.string().regex(/^[A-Z]{2}-\d{4}-\d{4}$/),
  date: z.string().date(),
  amount_excl_tax: z.number().positive(),
  vat_rate: z.number().min(0).max(100),
  amount_incl_tax: z.number().positive(),
  supplier: z.object({
    name: z.string().min(2),
    siret: z.string().length(14).regex(/^\d+$/),
  }),
});

type Invoice = z.infer<typeof InvoiceSchema>;

async function extractInvoice(text: string): Promise<Invoice> {
  const response = await client.responses.create({
    model: "gpt-5.6-terra",
    instructions: "Extract invoice data.",
    input: text,
    text: {
      format: {
        type: "json_schema",
        name: "invoice",
        schema: {
          type: "object",
          properties: {
            number: { type: "string" },
            date: { type: "string" },
            amount_excl_tax: { type: "number" },
            vat_rate: { type: "number" },
            amount_incl_tax: { type: "number" },
            supplier: {
              type: "object",
              properties: {
                name: { type: "string" },
                siret: { type: "string" },
              },
              required: ["name", "siret"],
              additionalProperties: false,
            },
          },
          required: ["number", "date", "amount_excl_tax",
                     "vat_rate", "amount_incl_tax", "supplier"],
          additionalProperties: false,
        },
        strict: true,
      },
    },
  });

  const data = JSON.parse(response.output_text);

  // Walidacja Zod z drobnymi ograniczeniami
  return InvoiceSchema.parse(data);
}

Wzorzec: ponowienie z korektą

Gdy walidacja nie powiedzie się, odeślij błąd z powrotem do modelu w celu korekty. Ten odruch zmienia naturę awarii: data w złym formacie nie jest już wyjątkiem вспływającym do użytkownika, lecz dodatkową rundą trwającą kilkaset milisekund, której nikt nie zauważy. Mechanizm jest prosty – wstrzykujemy komunikat o błędzie walidacji do promptu następnej próby, dzięki czemu model wie dokładnie, co poszło nie tak, zamiast zgadywać w ciemno po raz drugi.

Ten komfort wymaga jednak granic. Ogranicz liczbę prób, inaczej niemożliwe do spełnienia ograniczenie – np. pattern zbyt ścisły dla numerów zagranicznych – kosztować Cię będzie pętlę wywołań. Monitoruj też wskaźnik ponowień: jeśli ćwierć Twoich ekstrakcji przechodzi przez retry, problem leży w początkowym prompcie lub schemacie, a nie w modelu.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Ekstrahuje i waliduje z automatycznym ponowieniem."""
    last_error = None

    for attempt in range(max_retries):
        input_text = prompt
        if last_error:
            input_text += (f"\n\nWARNING: Your previous response had "
                          f"this validation error: {last_error}\n"
                          f"Correct and try again.")

        response = client.responses.create(
            model="gpt-5.6-terra",
            reasoning={"effort": "none"},  # temperature requires effort none
            input=input_text,
            text={"format": {"type": "json_schema",
                             "name": "data",
                             "schema": schema,
                             "strict": True}},
            temperature=0.1
        )

        data = json.loads(response.output_text)
        is_valid, error = validator(data)

        if is_valid:
            return data
        last_error = error

    raise ValueError(f"Failed after {max_retries} attempts: {last_error}")

Stanowisko testowe dla zaproszeń kalendarzowych

Zbuduj schemat Pydantic do ekstrakcji wydarzeń – tytuł, data, godzina, lokalizacja, uczestnicy – a następnie podłącz go za wywołaniem Structured Output. Przetestuj go na pięciu e-mailach zawierających zaproszenia, upewniając się, że znajdziesz co najmniej jeden, w którym godzina jest zapisana słownie („czwartek późny poranek“) i jeden, w którym lokalizacja jest domyślna („jak zwykle w sali konferencyjnej“). To przypadki, które łamią walidację, a w prawdziwej skrzynce odbiorczej dominują.

Następnie dodaj automatyczne ponowienie i zmierz dwie wartości: wskaźnik sukcesu za pierwszym razem oraz wskaźnik po ponowieniach. Drugi powie Ci, co zyskujesz dzięki korekcie, pierwszy – czy powinieneś poprawić swoje instrukcje, zamiast liczyć na drugą szansę.

Kluczowe wnioski

  • Structured Output gwarantuje strukturę, ale nie semantyczną poprawność
  • Używaj dwóch schematów: jednego dla API (ścisły), drugiego do walidacji po stronie klienta
  • Pydantic (Python) i Zod (TypeScript) to narzędzia referencyjne
  • Wzorzec ponowienia z informacją zwrotną koryguje większość błędów walidacji
  • Zawsze waliduj po stronie klienta przed trwałym zapisem danych