Tipi non supportati e limitazioni
In questa pagina
Cosa non possono fare gli schemi
Comprendere i limiti degli output strutturati è importante quanto padroneggiarne le capacità. L’API di Grok non supporta alcuni vincoli di JSON Schema. Tentare di utilizzarli genererà un errore o causerà comportamenti imprevisti.
Le tre principali restrizioni
allOf — composizione non consentita
In JSON Schema, la parola chiave allOf combina più sottoschemi che un oggetto deve soddisfare simultaneamente. L’API di Grok non supporta questa funzionalità.
// DOES NOT WORK
{
"allOf": [
{ "properties": { "nom": { "type": "string" } } },
{ "properties": { "age": { "type": "number" } } }
]
}
Alternativa: usa un singolo oggetto con tutte le proprietà:
// WORKS
{
"type": "object",
"properties": {
"nom": { "type": "string" },
"age": { "type": "number" }
}
}
minLength / maxLength — nessun vincolo sulla lunghezza delle stringhe
Non puoi forzare il modello a produrre una stringa con una lunghezza minima o massima.
// DOES NOT WORK
{
"properties": {
"code": {
"type": "string",
"minLength": 3,
"maxLength": 10
}
}
}
Alternativa: specifica il vincolo nel prompt invece che nello schema:
messages=[{
"role": "user",
"content": "Generate a product code between 3 and 10 characters."
}]
Il modello seguirà l’istruzione nella maggior parte dei casi, ma non è garantito come lo sarebbe un vincolo di schema.
minItems / maxItems — nessun vincolo sulla dimensione degli array
Non puoi imporre un numero minimo o massimo di elementi in un array.
// DOES NOT WORK
{
"properties": {
"tags": {
"type": "array",
"items": { "type": "string" },
"minItems": 1,
"maxItems": 5
}
}
}
Alternativa: usa il prompt per guidare il modello:
messages=[{
"role": "user",
"content": "List between 1 and 5 relevant tags for this article."
}]
Altre limitazioni da conoscere
Nessuna espressione regolare (regex)
L’API non supporta i vincoli pattern sulle stringhe. Non puoi imporre un formato email, UUID o numero di telefono tramite lo schema.
// DOES NOT WORK
{
"properties": {
"email": {
"type": "string",
"pattern": "^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$"
}
}
}
Nessun valore predefinito
La parola chiave default non ha alcun effetto. Se un campo è presente nello schema, il modello lo popolerà sempre.
Nessuna condizionale
Le parole chiave di JSON Schema if, then ed else non sono disponibili.
La strategia: schema + prompt
L’approccio migliore combina entrambi:
- Lo schema garantisce la struttura: nomi dei campi, tipi, annidamento
- Il prompt guida il contenuto: lunghezze, formati specifici, regole di business
class Report(BaseModel):
title: str
summary: str
key_points: list[str]
score: float
category: str
messages=[{
"role": "user",
"content": """Analyze this text and produce a report.
- The summary must be 2-3 sentences.
- List exactly 5 key points.
- The score is between 0 and 10.
- Category among: positive, negative, neutral."""
}]
Lo schema garantisce tipi e struttura. Il prompt controlla i valori e i vincoli sul contenuto.
Punti chiave
allOf,minLength,maxLength,minItemsemaxItemsnon sono supportati- Anche i vincoli
pattern,defaulteif/then/elsenon sono supportati - Usa
anyOfal posto diallOfquando possibile - Delega i vincoli sul contenuto al prompt
- Combinare schema (struttura) + prompt (contenuto) è la strategia ottimale