Output strutturato: JSON garantito
In questa pagina
Output strutturato: JSON garantito
L’output strutturato è una delle funzionalità più potenti delle Responses API. Invece di sperare che il modello restituisca un JSON valido, lo garantisci fornendo uno schema. Il modello viene quindi vincolato strutturalmente a seguirlo. Questo trasforma un modello linguistico da generatore di testo creativo a componente affidabile di una pipeline di elaborazione automatizzata.
Il problema che risolve
Chiedere JSON nel prompt funziona nella maggior parte dei casi, ed è proprio questo a rendere l’approccio pericoloso. Una volta su cento, il modello antepone alla risposta una frase introduttiva, racchiude tutto in un blocco di codice Markdown o rinomina un campo: il tuo json.loads() lancia un’eccezione in produzione su una richiesta che non riesci a riprodurre.
from openai import OpenAI
client = OpenAI()
# Senza struttura: il modello può restituire qualsiasi formato
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Risultato imprevedibile:
# A volte JSON valido, a volte testo contenente JSON,
# a volte un formato inaspettato...
Il parametro text cambia la natura della garanzia. Dichiarando un formato json_schema insieme allo schema atteso, l’output vi si conforma: la deserializzazione diventa un’operazione sicura.
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'])}")
# Risultato GARANTITO come JSON valido:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic invece dello schema JSON scritto a mano
Scrivere schemi a mano diventa rapidamente noioso e soggetto a errori di battitura. Pydantic ti permette di descriverli come classi Python, generare lo schema JSON con model_json_schema() e poi validare e tipizzare la risposta con model_validate_json(). Alla fine della catena, ottieni un oggetto Python completo con autocompletamento nell’editor, invece di un dizionario anonimo.
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()
}
}
)
# Analisi e validazione con 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'}")
# Risultato:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Nulla ti limita a strutture piatte. Componendo le classi, descrivi oggetti nidificati e liste di oggetti, necessari non appena crei un profilo cliente realistico: un’azienda contiene contatti e ogni contatto ha un indirizzo.
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}")
Due casi d’uso comuni
Il primo è l’estrazione: trasformare un testo scritto in un record utilizzabile. Un annuncio di conferenza scritto in linguaggio naturale diventa una riga di database con titolo, data, luogo e numero di partecipanti, senza espressioni regolari e senza rotture ogni volta che cambia la formulazione.
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)")
# Risultato: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Il secondo è la classificazione. Dichiarando un’enumerazione, restringi il modello a un vocabolario chiuso: non può rispondere «piuttosto positivo» o «positivo» quando il tuo codice si aspetta positive. Questa è la differenza tra un valore utilizzabile direttamente e un valore da normalizzare successivamente.
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%})")
# Risultato: Sentiment: positive (95%)
Cosa richiede la modalità strict
La garanzia ha un compromesso: quando strict: True, lo schema deve aderire a un sottoinsieme specifico di JSON Schema. Questi vincoli sono la causa principale degli errori 400 per i principianti, quindi è meglio conoscerli prima di incontrarli:
- Tutte le proprietà devono essere elencate in
required additionalPropertiesdeve essereFalse- Tipi supportati:
string,number,integer,boolean,array,object,null - Nessun
oneOfoanyOfcon tipi misti - Usa
Optional[str], che si traduce in{"anyOf": [{"type": "string"}, {"type": "null"}]}
La regola su required sorprende spesso: un campo opzionale non si esprime rimuovendolo dalla lista, ma permettendo il valore null, esattamente ciò che produce Optional[str] lato Pydantic.
Punti chiave
- L’output strutturato garantisce che la risposta aderisca al tuo schema JSON
- Usa
text={"format": {"type": "json_schema", ...}}nelle Responses API - Pydantic è lo strumento ideale per definire e validare gli schemi
- Abilita
strict: Trueper garantire la conformità allo schema - Ideale per estrazione dati, classificazione e generazione strutturata