Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Gestructureerde uitvoer: gegarandeerde JSON

Les 9 van 22 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Gestructureerde uitvoer: gegarandeerde JSON
  2. Het probleem dat dit oplost
  3. Pydantic in plaats van handgeschreven JSON-schema
  4. Twee veelvoorkomende use-cases
  5. Wat de strikte modus vereist
  6. Belangrijkste punten

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
  • additionalProperties moet False zijn
  • Ondersteunde typen: string, number, integer, boolean, array, object, null
  • Geen oneOf of anyOf met 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: True in voor gegarandeerde schema-naleving
  • Ideaal voor data-extractie, classificatie en gestructureerde generatie