Modalità JSON e applicazione dello schema
In questa pagina
Lezione aggiornata il 3 novembre 2026 in base alla documentazione OpenAI:
temperatureetop_psono accettati solo con uno sforzo di ragionamento pari anone, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificarereasoning={"effort": "none"}(API Responses) oreasoning_effort="none"(Chat Completions). Fonti: Using GPT-6 · GPT-5.6 Terra.
Modalità JSON e applicazione dello schema
L’output strutturato di OpenAI garantisce che la risposta del modello sia un JSON valido conforme a uno schema da te definito. Basta con il parsing fragile basato su regex o sugli errori di formato: il vincolo viene applicato direttamente a livello di generazione.
Questa sfumatura è critica e cambia tutto per uno sviluppatore. Chiedere «rispondi in JSON» nel prompt è una supplica: il modello obbedisce quasi sempre, ma un giorno potrebbe anteporre alla risposta «Ecco il JSON richiesto:», aggiungere backtick Markdown o dimenticare una virgola, facendo lanciare un’eccezione al tuo json.loads in produzione alle 3 di notte durante il batch più grande della settimana. Con l’output strutturato, il vincolo si applica durante la decodifica: i token che produrrebbero un JSON non valido o non conforme semplicemente non possono essere scelti. Smetti di supplicare e inizi a imporre.
Modalità JSON vs Output strutturato
OpenAI offre due livelli di vincolo e la distinzione ruota attorno a una singola parola. La modalità JSON garantisce un JSON valido senza vincoli strutturali; l’output strutturato garantisce un JSON conforme a uno schema JSON che hai scritto tu.
La modalità JSON risolve metà del problema. Sei sicuro di poter analizzare la risposta, ma non sai cosa conterrà: il modello potrebbe nominare un campo annee in una richiesta e year nella successiva, oppure racchiudere la sua lista in un oggetto resultats che non aveva usato il giorno prima. Per un prototipo o una visualizzazione grezza destinata a un umano, questo basta; non appena l’output alimenta codice che accede ai campi per nome, ti serve il secondo livello.
from openai import OpenAI
client = OpenAI()
# Semplice modalità JSON (JSON valido, struttura libera)
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)
Output strutturato con schema JSON
Questa è la funzionalità più potente. Definisci uno schema JSON e l’API garantisce che l’output vi aderisca. L’esempio seguente analizza il sentiment di una recensione di un cliente e illustra tre usi complementari dello schema.
L’enum su sentiment impedisce al modello di inventare una categoria intermedia come «piuttosto positivo»: deve scegliere tra i quattro valori forniti, rendendo l’output direttamente utilizzabile in un filtro o in una dashboard. La description del campo score agisce come un mini-prompt locale, indicando la scala attesa senza costringerti a spiegarla nelle istruzioni generali, e rimane associata al campo anche se il prompt evolve. Infine, l’array aspects ti permette di scomporre una recensione contraddittoria—qui, un prodotto apprezzato ma una consegna fallita—invece di schiacciare quella sfumatura in un unico punteggio che non aiuta nessuno.
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)
# Garantito: result ha esattamente i campi definiti
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
print(f" - {aspect['aspect']}: {aspect['sentiment']}")
Regole per l’output strutturato rigoroso
La modalità strict: true impone i propri vincoli allo schema. Tutti i campi devono apparire in required e additionalProperties deve essere false su ogni oggetto. I tipi consentiti sono string, number, integer, boolean, array, object e null, più enum per vincolare i valori. Tuttavia, né pattern né minLength/maxLength sono accettati: la validazione granulare avviene lato client.
Queste regole possono sorprendere al primo tentativo perché vietano il campo opzionale così come solitamente scritto nello schema JSON. Il compromesso è confortevole: il tuo codice non deve mai testare se una chiave esiste; è sempre lì. Per un campo che può legittimamente essere vuoto—un numero di telefono mancante da un documento, una data di fine per un contratto in corso—la risposta non è rimuoverlo da required, ma允许argli di essere null. Quanto all’assenza di pattern e dei limiti di lunghezza, segnala la prossima lezione: lo schema garantisce la forma, ma la validazione aziendale rimane compito tuo una volta ricevuta la risposta.
Helper per la costruzione di schemi
Scrivere manualmente il blocco text.format per ogni chiamata diventa rapidamente noioso e soggetto a errori di battitura: una chiave name mancante, un strict misplaced, e l’errore torna dall’API senza indicare dove guardare. Poche righe di codice wrapper centralizzano la struttura, applicano una temperatura bassa per impostazione predefinita (poiché la variabilità non aggiunge nulla all’estrazione) e rendono leggibile il sito di chiamata.
def structured_query(prompt: str, schema: dict,
schema_name: str = "response",
model: str = "gpt-5.6-terra",
system: str = "") -> dict:
"""Wrapper per richieste di Output Strutturato."""
response = client.responses.create(
model=model,
reasoning={"effort": "none"}, # temperature richiede 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)
Esempio: Estrazione di dati strutturati
Ecco il caso d’uso che da solo giustifica l’apprendimento di questa tecnica: trasformare una fattura ricevuta come testo semplice in un oggetto utilizzabile dal tuo sistema contabile. Lo schema descrive tre livelli: l’intestazione della fattura, un oggetto vendor annidato e un array lines dove ogni elemento ha la stessa forma. Il modello deve quindi sia individuare le informazioni sparse nel documento sia posizionarle nel punto giusto, anche per una riga espressa in ore invece che in unità, dove il prezzo unitario è inteso come tariffa oraria.
Nota che i totali appaiono nello schema come campi da estrarre, non da ricalcolare. Chiediamo al modello di leggere; il controllo aritmetico avviene successivamente nel tuo codice, dove un semplice confronto tra la somma delle righe e il total_ht estratto segnalerà i documenti per la revisione umana.
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."
)
Misurare cosa porta il vincolo
Applica questo principio a un documento che conosci bene: definisci uno schema JSON per estrarre le informazioni chiave da un curriculum—nome, esperienza, competenze, istruzione—e testalo su tre curriculum in testo semplice scelti deliberatamente per i loro layout eterogenei. Verifica che l’output rispetti lo schema anche quando una sezione è completamente assente.
Poi ripeti la stessa estrazione senza Output Strutturato, chiedendo semplicemente JSON nel prompt, e tieni i sei output affiancati. Confrontare le due serie mostra cosa porta il vincolo: la differenza risiede raramente nel contenuto estratto, quasi sempre nella stabilità dei nomi dei campi e nella presenza delle chiavi attese.
Punti chiave
- L’Output Strutturato garantisce un JSON conforme allo schema a livello di generazione
- Usa
strict: trueper la massima conformità - Tutti i campi devono essere
requiredconadditionalProperties: false - Ideale per l’estrazione di dati, la classificazione e le pipeline di elaborazione
- La validazione granulare (lunghezza, pattern) avviene lato client dopo la ricezione