ChatGPT JSON mode: output strutturati

JSON mode e Structured Outputs: dati affidabili da ChatGPT

Per integrare ChatGPT in software produttivo serve garanzia che la risposta sia JSON valido e conforme a uno schema. OpenAI offre due modalita: JSON mode e Structured Outputs.

JSON mode (legacy)

Attivabile con response_format={"type": "json_object"}. Garantisce che l'output sia JSON sintatticamente valido, ma non che rispetti uno schema specifico.

resp = client.chat.completions.create(
    model="gpt-5-mini",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Rispondi sempre in JSON."},
        {"role": "user", "content": "Dammi nome e città di 3 calciatori italiani."}
    ]
)

Devi includere la parola "JSON" nel prompt, altrimenti l'API restituisce errore.

Structured Outputs (consigliato)

Introdotti nel 2024, garantiscono che il JSON rispetti uno schema JSON Schema fornito da te. Niente più campi mancanti o tipi sbagliati.

schema = {
    "type": "object",
    "properties": {
        "nome": {"type": "string"},
        "eta": {"type": "integer"},
        "hobby": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["nome", "eta", "hobby"],
    "additionalProperties": false
}

resp = client.chat.completions.create(
    model="gpt-5-mini",
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "persona", "schema": schema, "strict": true}
    },
    messages=[...]
)

Modelli supportati

Structured Outputs sono disponibili su gpt-5, gpt-5-mini, gpt-5-nano, gpt-4o, gpt-4o-mini. Modelli più vecchi supportano solo JSON mode base.

Vincoli sullo schema

• additionalProperties: false obbligatorio in modalita strict
• Tutti i campi devono essere in required
• Profondita massima 5 livelli, max 100 proprietà
• Non supportati: oneOf, not, regex complesse, conditionals avanzati

Pydantic come bridge (Python)

L'SDK OpenAI accetta classi Pydantic e genera lo schema automaticamente:

from pydantic import BaseModel
class Persona(BaseModel):
    nome: str
    eta: int

resp = client.beta.chat.completions.parse(
    model="gpt-5-mini",
    response_format=Persona,
    messages=[...]
)
persona = resp.choices[0].message.parsed

Casi d'uso

• Estrazione dati da documenti (fatture, CV, ticket)
• Classificazione multi-label con confidence score
• Generazione configurazioni e payload API
• Risposte API REST in microservizi AI-powered

Pitfall comuni

• Schema troppo permissivo: aggiungi required a tutti i campi
• Enum mancanti: usa "enum": [...] per limitare valori
• Numeri come stringhe: specifica "type": "number"
• Date/datetime: usa format: "date-time"

Vuoi sviluppi su API ChatGPT con output strutturati ed affidabili? G Tech Group progetta integrazioni production-ready. Iniziamo.