Tipi supportati e schemi JSON
In questa pagina
I mattoni fondamentali dei tuoi schemi
Per definire la struttura delle tue risposte, hai a disposizione sette tipi JSON. Ognuno risponde a un’esigenza specifica nella modellazione dei dati. Comprendere questi tipi è essenziale per progettare schemi efficaci.
I sette tipi supportati
string
Il tipo più comune. Si usa per nomi, descrizioni, identificatori e qualsiasi contenuto testuale.
{
"type": "object",
"properties": {
"name": { "type": "string" },
"description": { "type": "string" }
}
}
number
Copre sia gli interi che i decimali. Non esiste distinzione tra integer e float: un unico tipo number gestisce entrambi.
{
"properties": {
"price": { "type": "number" },
"quantity": { "type": "number" }
}
}
boolean
Vero o falso. Perfetto per flag, validazioni e decisioni binarie.
{
"properties": {
"in_stock": { "type": "boolean" },
"express_delivery": { "type": "boolean" }
}
}
object
Ti permette di annidare strutture. Un oggetto può contenere altri oggetti, array o scalari, senza limiti di profondità.
{
"type": "object",
"properties": {
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"postal_code": { "type": "string" }
}
}
}
}
array
Liste di elementi dello stesso tipo. Puoi avere array di stringhe, numeri, oggetti o persino altri array.
{
"properties": {
"skills": {
"type": "array",
"items": { "type": "string" }
}
}
}
enum
Un insieme finito di valori consentiti. Essenziale per categorizzazioni e classificazioni.
{
"properties": {
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"]
}
}
}
anyOf
Ti permette di definire unioni di tipi. Un campo può accettare diverse strutture. Utile quando un singolo campo può assumere forme variabili.
{
"properties": {
"contact": {
"anyOf": [
{
"type": "object",
"properties": {
"email": { "type": "string" }
}
},
{
"type": "object",
"properties": {
"phone": { "type": "string" }
}
}
]
}
}
}
Combinare i tipi
La potenza degli schemi risiede nel combinare questi tipi. Ecco uno schema realistico per analizzare un prodotto:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"price": { "type": "number" },
"in_stock": { "type": "boolean" },
"category": {
"type": "string",
"enum": ["electronics", "clothing", "grocery", "other"]
},
"tags": {
"type": "array",
"items": { "type": "string" }
},
"manufacturer": {
"type": "object",
"properties": {
"name": { "type": "string" },
"country": { "type": "string" }
}
}
}
}
Questo schema mescola scalari, un enum, un array e un oggetto annidato. Il modello rispetterà ogni vincolo a ogni chiamata.
Campi opzionali
Per rendere un campo opzionale, usa anyOf con null:
{
"properties": {
"phone": {
"anyOf": [
{ "type": "string" },
{ "type": "null" }
]
}
}
}
In Pydantic, questo corrisponde a phone: str | None.
Punti chiave
- Sette tipi disponibili:
string,number,object,array,boolean,enum,anyOf - I tipi si combinano liberamente per modellare strutture complesse
- I campi opzionali usano
anyOfconnull - Nessuna distinzione tra intero e decimale: un unico tipo
number enumimpone valori predefiniti per le classificazioni