JSON Schema nei prompt
Vincolare la struttura dell'output.
JSON Schema nei prompt è una lezione AI Prompt Engineering gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Prompt Engineering, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Prompt Engineering include 4 lezioni in totale.
Lo schema come contratto dell'output
Un JSON Schema descrive in modo dichiarativo la forma di un output valido: tipi, chiavi obbligatorie, vincoli sui valori e annidamento. Quando viene passato a un'API di output strutturato, diventa un contratto rigido; quando viene inserito in un prompt, diventa una guida forte.
Imparare a scrivere schemi è la competenza fondamentale della generazione strutturata.
Il flag strict cambia tutto
In modalità strict, i provider richiedono che ogni proprietà sia elencata in required e che additionalProperties sia impostato su false. I campi opzionali si esprimono come un'unione con null, non omettendoli.
{
'type': 'object',
'properties': {
'name': {'type': 'string'},
'nickname': {'type': ['string', 'null']}
},
'required': ['name', 'nickname'],
'additionalProperties': False
}Vincolare i valori scalari
Sposti la convalida nello schema invece di eseguirla nella post-elaborazione:
enumper le scelte prefissate.minimum/maximumper gli intervalli numerici.patternper le stringhe con convalida tramite regex.formatper indicazioni comedate-timeoemail.
{
'rating': {'type': 'integer', 'minimum': 1, 'maximum': 5},
'sku': {'type': 'string', 'pattern': '^[A-Z]{3}-[0-9]{4}$'},
'created': {'type': 'string', 'format': 'date-time'}
}Array e tuple
Usi items per gli array omogenei e aggiunga minItems/maxItems per limitarne la lunghezza. Per le tuple posizionali, fornisca un array di schemi tramite prefixItems.
{
'tags': {
'type': 'array',
'items': {'type': 'string'},
'minItems': 1,
'maxItems': 5
}
}Unioni discriminate con oneOf
Modelli i risultati polimorfici con oneOf e un campo discriminatore. Il modello sceglie esattamente un ramo e il deserializzatore usa il tag per decidere come procedere.
{
'oneOf': [
{'type': 'object', 'properties': {
'kind': {'const': 'email'},
'address': {'type': 'string', 'format': 'email'}},
'required': ['kind', 'address']},
{'type': 'object', 'properties': {
'kind': {'const': 'phone'},
'number': {'type': 'string'}},
'required': ['kind', 'number']}
]
}Generare schemi dai tipi
Scrivere gli schemi a mano è soggetto a errori. Li ricavi dai modelli tipizzati, così lo schema e il codice non potranno mai divergere.
from pydantic import BaseModel
class Invoice(BaseModel):
total: float
currency: str
paid: bool
schema = Invoice.model_json_schema()
# pass schema directly to response_formatAnche le descrizioni sono prompt
Ogni description nello schema viene letta dal modello. Le usi per guidare la semantica, non solo per documentare i campi.
Per esempio, una descrizione come 'codice paese ISO-3166 alpha-2, in maiuscolo' migliora concretamente l'accuratezza del campo. Consideri le descrizioni come micro-prompt incorporati nel contratto.
{
'country': {
'type': 'string',
'description': 'ISO-3166 alpha-2 code, uppercase, e.g. US, TR, DE'
}
}Incorporare lo schema nel prompt
Quando il provider non offre supporto nativo, incorpori lo schema nel prompt e richieda la conformità. Lo abbini a un unico esempio in-context e a un'istruzione esplicita: solo JSON, niente prosa.
SYSTEM = (
'You output ONLY JSON matching this schema. No markdown, no commentary.\n'
'Schema:\n' + json.dumps(schema) + '\n'
'If a value is unknown, use null.'
)Evitare l'eccessiva complessità dello schema
Gli schemi troppo profondi o con troppi rami confondono il modello e aumentano il costo in token. Linee guida:
- Mantenga l'annidamento ridotto; appiattisca la struttura dove possibile.
- Preferisca gli enum alle stringhe libere.
- Divida uno schema enorme in più chiamate mirate.
- Alcuni provider limitano la profondità dell'annidamento e il numero totale di proprietà; verifichi i limiti.
Riferimenti e riutilizzo
Usi $defs e $ref per riutilizzare i sotto-schemi, ad esempio un Address usato per la fatturazione e la spedizione. Tenga presente che alcune modalità strict limitano la profondità della ricorsione, quindi verifichi il supporto prima di affidarsi a ref autoriferiti.
{
'$defs': {
'Address': {'type': 'object', 'properties': {
'city': {'type': 'string'}}, 'required': ['city'],
'additionalProperties': False}
},
'type': 'object',
'properties': {
'billing': {'$ref': '#/$defs/Address'},
'shipping': {'$ref': '#/$defs/Address'}
},
'required': ['billing', 'shipping'],
'additionalProperties': False
}Convalidare lo schema stesso
Esiste una classe di bug più sottile: è lo schema a essere malformato, non l'output. Esegua il lint e convalidi gli schemi nella CI rispetto al meta-schema JSON Schema, quindi faccia passare un oggetto di esempio attraverso il validatore prima del rilascio.
import jsonschema
jsonschema.Draft202012Validator.check_schema(schema)
# also: validate a known-good sample
jsonschema.validate(sample_obj, schema)Verifica rapida
In modalità strict con JSON Schema di un provider, come si esprime correttamente un campo opzionale?
Riepilogo
Ora sa scrivere schemi precisi:
- la modalità strict richiede tutti i campi in required e additionalProperties false.
- Vincoli gli scalari con enum, intervalli, pattern e format.
- Modelli il polimorfismo con discriminatori oneOf.
- Generi gli schemi da modelli tipizzati e consideri le descrizioni come micro-prompt.
- Convalidi lo schema stesso nella CI.
Prossimo argomento: applicare gli schemi alle chiamate di tool e di funzione.
Impara AI Prompt Engineering con un tutor IA — gratis
Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.
- Corsi
- 53
- Lezioni
- 199
Domande Frequenti
La lezione «JSON Schema nei prompt» è gratuita?
Sì — il testo completo di «JSON Schema nei prompt» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Prompt Engineering, passa a CoddyKit PRO. Il corso AI Prompt Engineering include 4 lezioni in totale.
Cosa imparerò in «JSON Schema nei prompt»?
Vincolare la struttura dell'output. Eserciti AI Prompt Engineering con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Prompt Engineering?
Non è richiesta alcuna esperienza precedente. AI Prompt Engineering su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.
Quanto tempo richiede la lezione «JSON Schema nei prompt»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Prompt Engineering?
Sì. Ogni lezione AI Prompt Engineering include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Perché usare un output strutturato
- JSON Schema nei prompt
- Schema di tool e funzioni
- Cicli di correzione e validazione