Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Tipi non supportati e limitazioni

Lezione 3 di 12 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Cosa non possono fare gli schemi
  2. Le tre principali restrizioni
  3. Altre limitazioni da conoscere
  4. La strategia: schema + prompt
  5. Punti chiave

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:

  1. Lo schema garantisce la struttura: nomi dei campi, tipi, annidamento
  2. 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, minItems e maxItems non sono supportati
  • Anche i vincoli pattern, default e if/then/else non sono supportati
  • Usa anyOf al posto di allOf quando possibile
  • Delega i vincoli sul contenuto al prompt
  • Combinare schema (struttura) + prompt (contenuto) è la strategia ottimale