Een JSON-schema ontwerpen

Als je gegarandeerd gestructureerde uitvoer wilt, laat dat dan niet aan het toeval over. Stel tool_choice in om een toolaanroep af te dwingen:

• "auto" — het model kiest tekst of een tool
• "any" — het model MOET een tool aanroepen (garandeert gestructureerde uitvoer)
• {"type":"tool","name":"X"} — dwingt één specifieke tool af

Voor extractie met één schema is het afdwingen van de exacte tool op naam de meest eenvoudige weg naar een deterministische structuur.

De belangrijkste schemaregel: markeer een veld ALLEEN als required wanneer het altijd in de bron aanwezig is. Maak een veld nooit verplicht als het kan ontbreken.

Waarom? Een verplicht veld dwingt het model om een waarde te produceren. Als de gegevens er niet zijn, zal Claude er één verzinnen om aan het contract te voldoen. Optioneel en afwezig is eerlijk; verplicht maar ontbrekend leidt tot hallucinaties.

Voor velden die wel of niet kunnen voorkomen — een kortingsregel, een tweede contactpersoon, een vervaldatum — laat je ze WEG uit required. Beschrijf ze duidelijk, zodat Claude ze alleen invult wanneer de gegevens echt aanwezig zijn.

Een goede beschrijving vertelt het model in welk formaat de invoer staat en wanneer het veld moet ontbreken, zodat het het veld weglaat in plaats van iets te verzinnen.

Wanneer een veld een vaste woordenschat heeft — status, categorie, prioriteit — gebruik je een enum. Daarmee breng je rommelige vrije tekst ("paid", "PAID", "settled") terug tot één canonieke waarde waarop je code kan schakelen.

Enumwaarden verminderen ook hallucinaties: het model moet kiezen uit de opgegeven reeks in plaats van een label te verzinnen.

Strikte enumwaarden breken wanneer de werkelijkheid een nieuw geval oplevert. Het patroon van een architect: voeg een waarde "other" toe aan de enum EN een vrij tekstveld detail om vast te leggen wat "other" precies was.

Zo blijft je schema geldig voor onvoorziene invoer, verlies je geen informatie en kun je het detailveld analyseren om te bepalen of een nieuwe enumwaarde gerechtvaardigd is.

Veldbeschrijvingen zijn miniprompts. Vage sleutels leveren vage uitvoer op. Vermeld het formaat, geef een voorbeeld en beschrijf hoe je met randgevallen omgaat, rechtstreeks in het schema.

Dit is voor gestructureerde uitvoer het equivalent van expliciete criteria die beter werken dan vage instructies: "ISO 8601-datum, weglaten als deze ontbreekt" werkt elke keer beter dan een kale due_date: string.

Goede schema's helpen je fouten op te sporen. Om berekeningen te controleren, extraheer je zowel een berekende als een vermelde waarde en vergelijk je die vervolgens in code.

Leg bijvoorbeeld stated_total vast (afgedrukt op het document), naast de regelitems die je zelf kunt optellen. Een verschil markeert een extractie- of documentfout voordat die verderop gevolgen heeft.

Het schema garandeert de JSON-structuur, niet de juistheid volgens de bedrijfsregels. Voeg validatie in Pydantic-stijl toe. Wanneer die faalt door een formaat-, structurele of rekenkundige fout, probeer je het opnieuw — maar geef het model door wat er misging.

Stuur het oorspronkelijke document, de verkeerde uitvoer en de exacte validatiefout. Dat is opnieuw proberen met feedback. Let op: opnieuw proberen helpt NIET wanneer informatie simpelweg ontbreekt in de bron — hoe vaak je het ook opnieuw vraagt, ontbrekende gegevens verschijnen niet ineens.

Voor extracties die je later moet kunnen verdedigen, ontwerp je velden die de herkomst bewaren: waar elke bewering vandaan komt. Houd koppelingen tussen beweringen en bronnen bij — bronnaam, citaat, pagina of datum.

Zo wordt een extractie uit een zwarte doos controleerbaar en kun je tegenstrijdige waarden (vaak een datumverschil) annoteren in plaats van stilzwijgend één waarde te kiezen.

Belangrijkste lessen voor het ontwerpen van een JSON Schema:

• tool_use + JSON Schema voorkomt syntaxisfouten en dwingt vereiste velden af.
• Dwing de structuur af met tool_choice: "any" voor een willekeurige tool, {"type":"tool","name":"X"} voor een specifieke tool.
• Markeer required ALLEEN voor velden die altijd aanwezig zijn — een ontbrekend veld verplicht maken leidt tot verzinning.
• Gebruik enumwaarden voor vaste woordenschatten; voeg "other" en een detailveld toe voor uitbreidbaarheid.
• Beschrijvingen leggen formaat, voorbeelden en randgevallen uit.
• Extraheer zowel berekende als vermelde waarden voor zelfcontrole; valideer en probeer daarna opnieuw met feedback bij forma atfouten (niet bij ontbrekende informatie).
• Leg de herkomst vast voor controleerbare en verdedigbare extracties.