JSON-modus en schema-afdwinging
Op deze pagina
Les bijgewerkt op 3 november 2026 op basis van OpenAI-documentatie:
temperatureentop_pworden alleen geaccepteerd met een redeneerinspanning vannone, terwijl GPT-5.6-modellen standaard redeneren (medium). Aanroepen die deze parameters instellen, moeten daaromreasoning={"effort": "none"}(Responses API) ofreasoning_effort="none"(Chat Completions) specificeren. Bronnen: Using GPT-6 · GPT-5.6 Terra.
JSON-modus en schema-afdwinging
OpenAI’s Gestructureerde Output garandeert dat het antwoord van het model geldige JSON is die conform is aan een door u gedefinieerd schema. Geen kwetsbare parsing meer met regex of formatfouten; de beperking wordt al tijdens de generatie zelf toegepast.
Deze nuance is cruciaal en verandert alles voor een ontwikkelaar. Vragen om “in JSON te antwoorden” in de prompt is een smeekbede: het model gehoorzaamt meestal, maar op een dag prefixt het zijn antwoord met “Hier is de gevraagde JSON:”, voegt het Markdown-backticks toe, of vergeet het een komma, waardoor uw json.loads een uitzondering genereert in productie om 3 uur ‘s nachts tijdens de grootste batch van de week. Met Gestructureerde Output geldt de beperking tijdens het decoderen: tokens die ongeldige of niet-conforme JSON zouden produceren, kunnen eenvoudigweg niet worden gekozen. U stopt met smeken en begint af te dwingen.
JSON-modus versus Gestructureerde Output
OpenAI biedt twee niveaus van beperking, en het onderscheid hangt af van één woord. JSON-modus garandeert geldige JSON zonder structurele beperkingen; Gestructureerde Output garandeert JSON die conform is aan een door u geschreven JSON-schema.
JSON-modus lost de helft van het probleem op. U weet zeker dat u het antwoord kunt parseren, maar niet zeker wat het bevat: het model kan een veld annee noemen bij het ene verzoek en year bij het volgende, of zijn lijst verpakken in een resultats-object dat het de dag ervoor niet gebruikte. Voor een prototype of ruwe weergave bestemd voor een mens volstaat dit; zodra de output code voedt die velden op naam benadert, heeft u het tweede niveau nodig.
from openai import OpenAI
client = OpenAI()
# Eenvoudige JSON-modus (geldige JSON, vrije structuur)
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Always respond in JSON.",
input="List 3 programming languages with their year of creation.",
text={"format": {"type": "json_object"}}
)
import json
data = json.loads(response.output_text)
print(data)
Gestructureerde Output met JSON-schema
Dit is de krachtigste functie. U definieert een JSON-schema en de API garandeert dat de output hieraan voldoet. Het onderstaande voorbeeld analyseert het sentiment van een klantenrecensie en illustreert drie complementaire toepassingen van het schema.
De enum op sentiment verhindert dat het model een tussenliggende categorie bedenkt zoals “eerder positief”: het moet kiezen tussen de vier verstrekte waarden, waardoor de output direct bruikbaar is in een filter of dashboard. De description van het veld score fungeert als een lokale mini-prompt, die de verwachte schaal aangeeft zonder dat u dit in de algemene instructies hoeft uit te leggen, en het blijft aan het veld gekoppeld zelfs als de prompt evolueert. Tot slot stelt de aspects-array u in staat een tegenstrijdige recensie te ontleden—hier een product dat leuk werd gevonden maar waarbij de levering faalde—in plaats van die nuance te verpletteren tot één score die niemand helpt.
response = client.responses.create(
model="gpt-5.6-terra",
input="Analyze the sentiment of: 'The product is excellent "
"but the delivery was catastrophic.'",
text={
"format": {
"type": "json_schema",
"name": "sentiment_analysis",
"schema": {
"type": "object",
"properties": {
"sentiment": {
"type": "string",
"enum": ["positive", "negative", "mixed", "neutral"]
},
"score": {
"type": "number",
"description": "Score from -1.0 (very negative) to 1.0 (very positive)"
},
"aspects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"aspect": {"type": "string"},
"sentiment": {
"type": "string",
"enum": ["positive", "negative", "neutral"]
}
},
"required": ["aspect", "sentiment"],
"additionalProperties": False
}
},
"summary": {"type": "string"}
},
"required": ["sentiment", "score", "aspects", "summary"],
"additionalProperties": False
},
"strict": True
}
}
)
result = json.loads(response.output_text)
# Gegarandeerd: result heeft exact de gedefinieerde velden
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
print(f" - {aspect['aspect']}: {aspect['sentiment']}")
Regels voor strikte Gestructureerde Output
De modus strict: true legt zijn eigen beperkingen op aan het schema. Alle velden moeten voorkomen in required, en additionalProperties moet false zijn op elk object. Toegestane typen zijn string, number, integer, boolean, array, object en null, plus enum om waarden te beperken. Noch pattern, noch minLength/maxLength worden echter geaccepteerd: gedetailleerde validatie gebeurt aan de clientzijde.
Deze regels kunnen bij de eerste poging verrassend zijn omdat ze het optionele veld verbieden zoals gewoonlijk geschreven in JSON-schema. De afweging is comfortabel: uw code hoeft nooit te testen of een sleutel bestaat; deze is er altijd. Voor een veld dat legitiem leeg kan zijn—een telefoonnummer dat ontbreekt in een document, een einddatum voor een lopend contract—is het antwoord niet om het uit required te verwijderen, maar om toe te staan dat het null is. Wat het ontbreken van pattern en lengtebegrenzingen betreft, dit signaleert de volgende les: het schema garandeert de vorm, maar zakelijke validatie blijft uw taak zodra het antwoord is ontvangen.
Hulp bij het bouwen van schema’s
Het handmatig schrijven van het blok text.format voor elke aanroep wordt snel vervelend en gevoelig voor typefouten—een ontbrekende sleutel name, een misplaatste strict, en de fout komt terug van de API zonder aan te geven waar te zoeken. Een paar regels wrapper-code centraliseren de structuur, passen standaard een lage temperatuur toe (aangezien variabiliteit niets toevoegt aan extractie) en maken de aanroepplaats leesbaar.
def structured_query(prompt: str, schema: dict,
schema_name: str = "response",
model: str = "gpt-5.6-terra",
system: str = "") -> dict:
"""Wrapper voor Gestructureerde Output-verzoeken."""
response = client.responses.create(
model=model,
reasoning={"effort": "none"}, # temperatuur vereist effort none
instructions=system or "Respond in JSON according to the provided schema.",
input=prompt,
text={
"format": {
"type": "json_schema",
"name": schema_name,
"schema": schema,
"strict": True
}
},
temperature=0.1
)
return json.loads(response.output_text)
Voorbeeld: Gestructureerde data-extractie
Hier is de use case die alleen al het leren van deze techniek rechtvaardigt: het transformeren van een factuur die als platte tekst is ontvangen naar een object dat bruikbaar is voor uw boekhoudsysteem. Het schema beschrijft drie niveaus—de factuurkoptekst, een genest vendor-object en een lines-array waarbij elk element dezelfde vorm heeft. Het model moet daarom zowel informatie lokaliseren die verspreid is over het document als deze op de juiste plek plaatsen, ook voor een regel uitgedrukt in uren in plaats van eenheden, waarbij de eenheidsprijs wordt begrepen als een uurtarief.
Merk op dat totalen in het schema verschijnen als velden om te extraheren, niet om opnieuw te berekenen. We vragen het model om te lezen; controle van de rekenkunde gebeurt afterward in uw code, waar een eenvoudige vergelijking tussen de som van de regels en de geëxtraheerde total_ht documenten zal markeren voor menselijke review.
invoice_schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"date": {"type": "string"},
"vendor": {
"type": "object",
"properties": {
"name": {"type": "string"},
"siret": {"type": "string"},
"address": {"type": "string"}
},
"required": ["name", "siret", "address"],
"additionalProperties": False
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {"type": "string"},
"quantity": {"type": "integer"},
"unit_price_excl_tax": {"type": "number"},
"vat_percent": {"type": "number"}
},
"required": ["description", "quantity",
"unit_price_excl_tax", "vat_percent"],
"additionalProperties": False
}
},
"total_excl_tax": {"type": "number"},
"total_incl_tax": {"type": "number"}
},
"required": ["invoice_number", "date", "vendor",
"lines", "total_excl_tax", "total_incl_tax"],
"additionalProperties": False
}
invoice_text = """
Invoice No. 2026-0042
Date: 15/03/2026
Vendor: TechServ SARL, SIRET 123 456 789 00012
12 rue de la Paix, 75002 Paris
- REST API Development x1: 3500.00 EUR excl. tax (VAT 20%)
- Cloud hosting (3 months) x1: 450.00 EUR excl. tax (VAT 20%)
- Technical support x10h: 150.00 EUR excl. tax/h (VAT 20%)
Total excl. tax: 5450.00 EUR
Total incl. tax: 6540.00 EUR
"""
result = structured_query(
invoice_text,
invoice_schema,
schema_name="invoice",
system="Extract the data from this invoice."
)
Meten wat de beperking oplevert
Pas dit principe toe op een document dat u goed kent: definieer een JSON-schema om sleutelinformatie uit een cv te extraheren—naam, ervaring, vaardigheden, opleiding—en test het op drie cv’s in platte tekst die bewust zijn gekozen vanwege hun heterogene lay-outs. Verifieer dat de output het schema respecteert, zelfs wanneer een sectie volledig ontbreekt.
Herhaal vervolgens dezelfde extractie zonder Gestructureerde Output, vraag simpelweg om JSON in de prompt, en houd de zes outputs naast elkaar. Het vergelijken van de twee reeksen toont wat de beperking oplevert: het verschil ligt zelden in de geëxtraheerde inhoud, bijna altijd in de stabiliteit van veldnamen en de aanwezigheid van verwachte sleutels.
Belangrijkste punten
- Gestructureerde Output garandeert JSON conform het schema op generatieniveau
- Gebruik
strict: truevoor maximale conformiteit - Alle velden moeten
requiredzijn metadditionalProperties: false - Ideaal voor data-extractie, classificatie en verwerkingspipelines
- Gedetailleerde validatie (lengte, patroon) gebeurt aan de clientzijde na ontvangst