Gestructureerde uitvoer: gegarandeerde JSON
Op deze pagina
Gestructureerde uitvoer: gegarandeerde JSON
Gestructureerde uitvoer is een van de krachtigste functies van de Responses API. In plaats van te hopen dat het model geldige JSON retourneert, garandeert u dit door een schema op te geven. Het model wordt vervolgens structureel gedwongen dit te volgen. Hiermee verandert een taalmodel van een creatieve tekstgenerator in een betrouwbaar onderdeel van een geautomatiseerde verwerkingspijplijn.
Het probleem dat dit oplost
Vragen om JSON in de prompt werkt de meeste keren, wat deze aanpak juist zo gevaarlijk maakt. Eén op de honderd keer voegt het model een inleidende zin toe, verpakt het alles in een Markdown-codeblok, of hernoemt het een veld—waardoor uw json.loads() in productie een uitzondering veroorzaakt bij een verzoek dat u niet kunt reproduceren.
from openai import OpenAI
client = OpenAI()
# Zonder structuur — het model kan elk formaat retourneren
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Onvoorspelbaar resultaat:
# Soms geldige JSON, soms tekst die JSON bevat,
# soms een onverwacht formaat...
De parameter text verandert de aard van de garantie. U declareert een json_schema-formaat samen met het verwachte schema, en de uitvoer voldoet hieraan: deserialisatie wordt een veilige bewerking.
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me information about Paris.",
text={
"format": {
"type": "json_schema",
"name": "city_info",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"country": {"type": "string"},
"population": {"type": "integer"},
"official_language": {"type": "string"},
"landmarks": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["name", "country", "population", "official_language", "landmarks"],
"additionalProperties": False
}
}
}
)
import json
data = json.loads(response.output_text)
print(f"City: {data['name']}")
print(f"Population: {data['population']:,}")
print(f"Landmarks: {', '.join(data['landmarks'])}")
# Resultaat GEGARANDEERD geldige JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic in plaats van handgeschreven JSON-schema
Het handmatig schrijven van schema’s wordt al snel omslachtig en gevoelig voor typefouten. Met Pydantic beschrijft u ze als Python-klassen, genereert u het JSON-schema met model_json_schema(), en valideert en typeert u vervolgens de respons met model_validate_json(). Aan het einde van de keten krijgt u een volledig Python-object met editor-autocompletion, in plaats van een anoniem woordenboek.
from pydantic import BaseModel
from typing import Optional
import json
class Product(BaseModel):
name: str
price: float
category: str
in_stock: bool
description: Optional[str] = None
response = client.responses.create(
model="gpt-5.6-terra",
input="Describe a high-end gaming laptop.",
text={
"format": {
"type": "json_schema",
"name": "product",
"strict": True,
"schema": Product.model_json_schema()
}
}
)
# Parseren en valideren met Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Product: {product.name}")
print(f"Price: {product.price} EUR")
print(f"In stock: {'Yes' if product.in_stock else 'No'}")
# Resultaat:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Niets beperkt u tot platte structuren. Door klassen te combineren, beschrijft u geneste objecten en lijsten van objecten, wat u nodig hebt zodra u een realistisch klantenprofiel maakt: een bedrijf bevat contactpersonen, en elke contactpersoon heeft een adres.
from pydantic import BaseModel
class Address(BaseModel):
street: str
city: str
postal_code: str
country: str
class Contact(BaseModel):
last_name: str
first_name: str
email: str
phone: str
address: Address
class Company(BaseModel):
name: str
sector: str
employees: int
contacts: list[Contact]
response = client.responses.create(
model="gpt-5.6-terra",
input="Generate a fictional company profile in the tech sector "
"with 2 contacts.",
text={
"format": {
"type": "json_schema",
"name": "company",
"strict": True,
"schema": Company.model_json_schema()
}
}
)
company = Company.model_validate_json(response.output_text)
print(f"Company: {company.name} ({company.sector})")
for c in company.contacts:
print(f" - {c.first_name} {c.last_name}: {c.email}")
Twee veelvoorkomende use-cases
De eerste is extractie: het omzetten van geschreven tekst naar een bruikbaar record. Een conferentieaankondiging in natuurlijke taal wordt een databaserij met een titel, datum, locatie en aantal deelnemers—zonder reguliere expressies, en zonder dat het faalt zodra de formulering verandert.
class Event(BaseModel):
title: str
date: str
location: str
attendees: int
text = """
The PyCon France 2026 conference will be held on November 15 and 16
at the Palais des Congrès in Lyon. More than 800 Python developers
are expected for this edition.
"""
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Extract the information from this event:\n{text}",
text={
"format": {
"type": "json_schema",
"name": "event",
"strict": True,
"schema": Event.model_json_schema()
}
}
)
evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} at {evt.location} ({evt.attendees} attendees)")
# Resultaat: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
De tweede is classificatie. Door een enumeratie te declareren, beperkt u het model tot een gesloten vocabulaire: het kan niet antwoorden met “eerder positief” of “positief” wanneer uw code positive verwacht. Dit is het verschil tussen een waarde die u direct kunt gebruiken en een waarde die u afterward moet normaliseren.
from enum import Enum
class Sentiment(str, Enum):
positive = "positive"
negative = "negative"
neutral = "neutral"
class Analysis(BaseModel):
sentiment: Sentiment
confidence: float
keywords: list[str]
response = client.responses.create(
model="gpt-5.6-terra",
input="Analyze this comment: 'Great service, fast delivery!'",
text={
"format": {
"type": "json_schema",
"name": "sentiment_analysis",
"strict": True,
"schema": Analysis.model_json_schema()
}
}
)
analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentiment: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Resultaat: Sentiment: positive (95%)
Wat de strikte modus vereist
De garantie komt met een afweging: wanneer strict: True is, moet het schema voldoen aan een specifieke subset van JSON Schema. Deze beperkingen zijn de belangrijkste oorzaak van 400-fouten voor beginners, dus is het beter ze te kennen voordat u ze tegenkomt:
- Alle eigenschappen moeten worden vermeld in
required additionalPropertiesmoetFalsezijn- Ondersteunde typen:
string,number,integer,boolean,array,object,null - Geen
oneOfofanyOfmet gemengde typen - Gebruik
Optional[str], wat vertaalt naar{"anyOf": [{"type": "string"}, {"type": "null"}]}
De regel over required verrast mensen vaak: een optioneel veld wordt niet uitgedrukt door het uit de lijst te verwijderen, maar door de waarde null toe te staan, precies wat Optional[str] aan de Pydantic-kant produceert.
Belangrijkste punten
- Gestructureerde uitvoer garandeert dat de respons voldoet aan uw JSON-schema
- Gebruik
text={"format": {"type": "json_schema", ...}}in de Responses API - Pydantic is het ideale hulpmiddel voor het definiëren en valideren van schema’s
- Schakel
strict: Truein voor gegarandeerde schema-naleving - Ideaal voor data-extractie, classificatie en gestructureerde generatie