Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Output strutturato: JSON garantito

Lezione 9 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Output strutturato: JSON garantito
  2. Il problema che risolve
  3. Pydantic invece dello schema JSON scritto a mano
  4. Due casi d’uso comuni
  5. Cosa richiede la modalità strict
  6. Punti chiave

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
  • additionalProperties deve essere False
  • Tipi supportati: string, number, integer, boolean, array, object, null
  • Nessun oneOf o anyOf con 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: True per garantire la conformità allo schema
  • Ideale per estrazione dati, classificazione e generazione strutturata