Types non supportés et limites

Ce que les schémas ne peuvent pas faire

Connaître les limites des sorties structurées est aussi important que de maîtriser leurs capacités. Certaines contraintes JSON Schema ne sont pas supportées par l’API Grok. Tenter de les utiliser provoquera une erreur ou un comportement inattendu.

Les trois restrictions majeures

allOf — composition interdite

Le mot-clé allOf permet en JSON Schema de combiner plusieurs sous-schémas que l’objet doit satisfaire simultanément. Cette fonctionnalité n’est pas supportée par l’API Grok.

// NE FONCTIONNE PAS
{
  "allOf": [
    { "properties": { "nom": { "type": "string" } } },
    { "properties": { "age": { "type": "number" } } }
  ]
}

Alternative : utilisez un seul objet avec toutes les propriétés :

// FONCTIONNE
{
  "type": "object",
  "properties": {
    "nom": { "type": "string" },
    "age": { "type": "number" }
  }
}

minLength / maxLength — pas de contrainte sur la longueur des chaînes

Vous ne pouvez pas forcer le modèle à produire une chaîne d’une longueur minimale ou maximale.

// NE FONCTIONNE PAS
{
  "properties": {
    "code": {
      "type": "string",
      "minLength": 3,
      "maxLength": 10
    }
  }
}

Alternative : spécifiez la contrainte dans le prompt plutôt que dans le schéma :

messages=[{
    "role": "user",
    "content": "Génère un code produit entre 3 et 10 caractères."
}]

Le modèle suivra l’instruction dans la grande majorité des cas, mais ce n’est pas garanti comme le serait une contrainte de schéma.

minItems / maxItems — pas de contrainte sur la taille des tableaux

Impossible de forcer un nombre minimum ou maximum d’éléments dans un tableau.

// NE FONCTIONNE PAS
{
  "properties": {
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 5
    }
  }
}

Alternative : utilisez le prompt pour guider le modèle :

messages=[{
    "role": "user",
    "content": "Liste entre 1 et 5 tags pertinents pour cet article."
}]

Autres limitations à connaître

Pas de regex pattern

Les contraintes pattern sur les chaînes ne sont pas supportées. Vous ne pouvez pas forcer un format email, un UUID, ou un numéro de téléphone via le schéma.

// NE FONCTIONNE PAS
{
  "properties": {
    "email": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$"
    }
  }
}

Pas de valeurs par défaut

Le mot-clé default n’a aucun effet. Si un champ est dans le schéma, le modèle le remplira toujours.

Pas de conditionnels

Les mots-clés if, then, else de JSON Schema ne sont pas disponibles.

La stratégie : schéma + prompt

La meilleure approche combine les deux :

1. Le schéma garantit la structure : noms de champs, types, imbrication
2. Le prompt guide le contenu : longueurs, formats spécifiques, règles métier

class Rapport(BaseModel):
    titre: str
    resume: str
    points_cles: list[str]
    score: float
    categorie: str

messages=[{
    "role": "user",
    "content": """Analyse ce texte et produis un rapport.
    - Le résumé doit faire 2-3 phrases.
    - Liste exactement 5 points clés.
    - Le score est entre 0 et 10.
    - Catégorie parmi : positif, négatif, neutre."""
}]

Le schéma garantit les types et la structure. Le prompt contrôle les valeurs et les contraintes de contenu.

Points clés à retenir

• allOf, minLength, maxLength, minItems, maxItems ne sont pas supportés
• Les contraintes pattern, default, if/then/else non plus
• Utilisez anyOf au lieu de allOf quand c’est possible
• Déportez les contraintes de contenu dans le prompt
• La combinaison schéma (structure) + prompt (contenu) est la stratégie optimale