Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Validatie met JSON Schema en Zod

Les 11 van 16 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Validatie met JSON Schema en Zod
  2. Waarom valideren na ontvangst
  3. Python-validatie met jsonschema
  4. Validatie met Pydantic
  5. Validatie met Zod (TypeScript/Node.js)
  6. Patroon: opnieuw proberen met correctie
  7. Een testbank voor agenda-uitnodigingen
  8. Belangrijkste punten

Les bijgewerkt op 3 november 2026 op basis van OpenAI-documentatie: temperature en top_p worden alleen geaccepteerd met een redeneerinspanning van none, terwijl GPT-5.6-modellen standaard redeneren (medium). Aanroepen die deze parameters instellen, moeten daarom reasoning={"effort": "none"} (Responses API) of reasoning_effort="none" (Chat Completions) specificeren. Bronnen: Using GPT-6 · GPT-5.6 Terra.

Validatie met JSON Schema en Zod

Gestructureerde Output garandeert de structuur van het antwoord, maar niet de semantische geldigheid van de gegevens. Een veld “email” kan een string bevatten die geen geldig e-mailadres is. Validatie aan de clientzijde met JSON Schema of Zod is de essentiële aanvulling voor een robuuste pipeline.

Waarom valideren na ontvangst

Neem de balans op van wat de API garandeert en de taakverdeling wordt duidelijk. OpenAI’s Gestructureerde Output zorgt ervoor dat de JSON syntactisch geldig is, dat gedeclareerde types worden gerespecteerd—een string blijft een string, een integer blijft een integer—dat alle verplichte velden aanwezig zijn en dat waarden beperkt door een enum tot de lijst behoren. Op deze vier punten kunt u uw code met vertrouwen schrijven.

Al het andere is aan u, en omvat vier families van problemen. Formaatbeperkingen ontglippen het strikte schema: niets weerhoudt het model ervan om jean.dupont(at)example.fr in een email-veld terug te geven, of een datum in het formaat 15/03/2026 wanneer u ISO verwacht. Grenzen worden ook niet gecontroleerd, noch voor stringlengte noch voor numeriek bereik: een leeftijd van 350 passeert zonder knipperen. Consistentie tussen velden blijft buiten bereik—een end_date eerder dan start_date is perfect geldige JSON. En zakelijke geldigheid heeft geen reden om de API te bekommeren: een SIRET (Frans bedrijfsnummer) moet veertien cijfers zijn, maar dat is kennis van uw domein, niet van de decoder.

Deze vier families delen een ontmoedigende eigenschap: ze veroorzaken geen zichtbare fouten. Een misvormd e-mailadres dat in de database wordt opgeslagen, manifesteert zich pas weken later wanneer de e-mailcampagne bounce. Vandaar de regel: valideer voordat u persisteert, nooit daarna.

Python-validatie met jsonschema

De praktische consequentie is dat u twee schema’s voor dezelfde gegevens nodig heeft. Het eerste gaat naar de API, bewust sober, beperkt tot wat de strikte modus accepteert. Het tweede blijft bij u en draagt de fijnmazige beperkingen—format, pattern, minimum, maximum. Deze schijnbare duplicatie is een scheiding van verantwoordelijkheden: het ene kadert de generatie, het andere verdedigt uw opslag. In het onderstaande voorbeeld verschijnt alleen de rol enum in beide, omdat dit de enige beperking is die beide niveaus kunnen uitdrukken.

import json
from jsonschema import validate, ValidationError

# Schema voor OpenAI API (strikt, geen 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
}

# Uitgebreid schema voor validatie aan de clientzijde
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]:
    """Valideert het LLM-antwoord tegen het uitgebreide schema."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Valid"
    except ValidationError as e:
        return False, f"Fout: {e.message}"

Validatie met Pydantic

Pydantic is vaak handiger dan jsonschema voor validatie in Python, en het verschil ligt in wat u als output krijgt. jsonschema vertelt u ja of nee en laat u achter met een dictionary, gemanipuleerd via data["email"] zonder editorondersteuning. Pydantic retourneert een getypt object: automatische aanvulling werkt, een typefout in een attribuutnaam wordt tijdens het schrijven gedetecteerd, en de gegevens circuleren daarna zonder conversie.

Het ContactExtraction-model drukt grenzen direct uit in de velddeclaraties. De field_validator op date_extraction behandelt het geval dat geen type-annotatie kan vangen: de string is inderdaad een string, maar moet een echte datum voorstellen—2026-02-31 voldoet aan elk redelijk pattern maar bestaat niet. De extractiefunctie toont de volledige keten, van het sobere schema dat naar de API wordt verzonden tot de gevalideerde instantiatie.

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

class ContactExtraction(BaseModel):
    """Validatieschema voor contactextractie."""
    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"Ongeldige datum: {v}")

def extract_and_validate(text: str) -> ContactExtraction:
    """Extraheert een contact en valideert de gegevens."""
    # Schema voor API (zonder fijnmazige beperkingen)
    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="Extraheer contactinformatie. "
                     "Datumformaat: YYYY-MM-DD.",
        input=text,
        text={
            "format": {
                "type": "json_schema",
                "name": "contact",
                "schema": api_schema,
                "strict": True
            }
        }
    )

    data = json.loads(response.output_text)
    # Pydantic-validatie met fijnmazige beperkingen
    return ContactExtraction(**data)

Validatie met Zod (TypeScript/Node.js)

Als uw backend in TypeScript staat, is Zod het referentietool, en het biedt een voordeel dat Pydantic niet hoeft te bieden: z.infer leidt het TypeScript-type direct af van het validatieschema. U beschrijft de vorm één keer, en de compiler kent vervolgens de structuur van Invoice zonder dat u een parallelle interface onderhoudt, zodat er geen risico op divergentie is.

Het onderstaande factuurschema illustreert de taakverdeling: aan de API-kant is siret gewoon een string; aan de Zod-kant moet het precies veertien tekens zijn en alleen cijfers bevatten. De uiteindelijke parse gooit een uitzondering als de gegevens niet passen, en dat is het gewenste gedrag—een luide fout die documentverwerking onderbreekt, is beter dan een fantasie-SIRET-factuur opgeslagen in de database tussen tienduizend anderen.

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

const client = new OpenAI();

// Zod-schema met fijnmazige validaties
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: "Extraheer factuurgegevens.",
    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);

  // Zod-validatie met fijnmazige beperkingen
  return InvoiceSchema.parse(data);
}

Patroon: opnieuw proberen met correctie

Wanneer validatie mislukt, stuurt u de fout terug naar het model voor correctie. Deze reflex verandert de aard van falen: een datum in het verkeerde formaat is niet langer een uitzondering die naar de gebruiker borrelt, maar een extra round-trip van enkele honderden milliseconden die niemand opmerkt. Het mechanisme is eenvoudig—we injecteren de validatiemelding opnieuw in de prompt van de volgende poging, zodat het model precies weet wat er misging in plaats van blindelings een tweede keer te raden.

Dit comfort vereist echter grenzen. Beperk het aantal pogingen, anders kost een onmogelijke beperking—een pattern die te strikt is voor buitenlandse nummers, bijvoorbeeld—u oproepen in een lus. En bewaak het retry-percentage: als een kwart van uw extracties via een retry gaat, ligt het probleem in de initiële prompt of het schema, niet in het model.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Extraheert en valideert met automatische retry."""
    last_error = None

    for attempt in range(max_retries):
        input_text = prompt
        if last_error:
            input_text += (f"\n\nWAARSCHUWING: Uw vorige antwoord had "
                          f"deze validatiefout: {last_error}\n"
                          f"Corrigeer en probeer opnieuw.")

        response = client.responses.create(
            model="gpt-5.6-terra",
            reasoning={"effort": "none"},  # temperature vereist 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"Mislukt na {max_retries} pogingen: {last_error}")

Een testbank voor agenda-uitnodigingen

Bouw een Pydantic-schema om evenementen te extraheren—titel, datum, tijd, locatie, deelnemers—en koppel het achter een Gestructureerde Output-aanroep. Test op vijf e-mails met uitnodigingen, zorg ervoor dat u er ten minste één opneemt waarbij de tijd uitgeschreven is (“donderdag laat in de ochtend”) en één waarbij de locatie impliciet is (“zoals gewoonlijk in de vergaderzaal”). Dit zijn de gevallen die validatie breken, en ze domineren in een echte inbox.

Voeg vervolgens automatische retry toe en meet twee cijfers: het slagingspercentage bij de eerste poging en het percentage na retry. Het tweede vertelt u wat correctie oplevert, het eerste of u uw instructies moet herwerken in plaats van te rekenen op een tweede kans.

Belangrijkste punten

  • Gestructureerde Output garandeert structuur, niet semantische geldigheid
  • Gebruik twee schema’s: één voor de API (strikt), één voor clientvalidatie
  • Pydantic (Python) en Zod (TypeScript) zijn de referentietools
  • Het retry-met-feedback-patroon corrigeert de meeste validatiefouten
  • Valideer altijd aan de clientzijde voordat u gegevens persisteert