Schémas JSON et validation
På denna sida
Schémas JSON et validation
Un schéma de fonction n’est pas de la plomberie de validation : c’est le seul contrat entre le modèle et ton code. Il n’existe aucun autre canal. Le modèle ne lit pas ton implémentation, ignore tes conventions internes et ne devinera pas qu’un champ date attend un format ISO plutôt qu’un format français.
Tout ce qui n’est pas écrit dans le schéma sera décidé par les inférences aléatoires du modèle. Cela explique le déséquilibre d’effort recommandé dans cette leçon : il vaut mieux passer dix minutes sur un schéma que deux heures à déboguer des arguments erratiques.
Structure du schéma de fonction
Chaque fonction déclarée dans tools suit le format JSON Schema. Voici la structure complète :
tool_definition = {
"type": "function",
"name": "creer_facture",
"description": "Create an invoice for an existing customer",
"parameters": {
"type": "object",
"properties": {
"client_id": {
"type": "string",
"description": "Unique customer identifier (format: CLI-XXXXX)"
},
"lignes": {
"type": "array",
"description": "List of billing line items",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Product or service description"
},
"quantite": {
"type": "integer",
"minimum": 1,
"description": "Number of units"
},
"prix_unitaire": {
"type": "number",
"minimum": 0,
"description": "Unit price excluding tax in euros"
}
},
"required": ["description", "quantite", "prix_unitaire"]
}
},
"devise": {
"type": "string",
"enum": ["EUR", "USD", "GBP"],
"default": "EUR"
},
"echeance_jours": {
"type": "integer",
"enum": [30, 45, 60, 90],
"description": "Payment deadline in days"
}
},
"required": ["client_id", "lignes"],
"additionalProperties": False
},
"strict": True
}
Mode strict
Le mode strict transforme une probabilité en garantie. Sans lui, le modèle produit généralement des arguments conformes — et tu découvres les exceptions en production, sur des cas limites. Avec lui, la conformité est assurée par construction au niveau du décodage. Active-le par défaut : les contraintes qu’il impose, détaillées ci-dessous, sont un faible prix à payer pour éliminer toute une classe de bugs.
tools = [{
"type": "function",
"name": "enregistrer_commande",
"description": "Record a new order",
"parameters": {
"type": "object",
"properties": {
"produit": {"type": "string"},
"quantite": {"type": "integer"},
"urgent": {"type": "boolean"}
},
"required": ["produit", "quantite", "urgent"],
"additionalProperties": False
},
"strict": True
}]
Contraintes du mode strict
En mode strict, certaines règles s’appliquent :
- Tous les champs doivent figurer dans
required additionalPropertiesdoit êtrefalse- Les types optionnels utilisent
anyOfavecnull - Pas de
pattern,minLength,maxLengthau niveau supérieur
# Champ optionnel en mode strict
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Validation côté client
Le mode strict garantit la forme, jamais le sens. Une date bien formée peut être dans le passé, un identifiant bien typé peut ne correspondre à aucun client, et un montant valide peut dépasser la limite autorisée. Ces règles relèvent de la logique métier : aucun schéma JSON ne les exprime, et elles doivent être vérifiées dans ton code — avec, en cas de rejet, un message d’erreur renvoyé au modèle expliquant ce qui s’est mal passé.
import json
from jsonschema import validate, ValidationError
SCHEMA_FACTURE = {
"type": "object",
"properties": {
"client_id": {"type": "string", "pattern": "^CLI-[0-9]{5}$"},
"lignes": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"description": {"type": "string", "minLength": 1},
"quantite": {"type": "integer", "minimum": 1},
"prix_unitaire": {"type": "number", "minimum": 0}
},
"required": ["description", "quantite", "prix_unitaire"]
}
}
},
"required": ["client_id", "lignes"]
}
def executer_fonction(name: str, arguments: str) -> str:
args = json.loads(arguments)
try:
validate(instance=args, schema=SCHEMA_FACTURE)
except ValidationError as e:
return json.dumps({"error": f"Invalid arguments: {e.message}"})
# Logique métier après validation
return creer_facture(**args)
Descriptions efficaces
Rédige la description d’une fonction comme des instructions pour un nouveau collègue : quand l’appeler, et surtout quand ne pas l’appeler. C’est cette seconde partie que l’on oublie systématiquement, alors qu’elle résout la plupart des appels erronés — « ne pas utiliser pour les commandes archivées » évite un aller-retour inutile que trois phrases de description positive n’auraient pas empêché.
# Mauvais : trop vague
{
"name": "get_data",
"description": "Retrieve data"
}
# Bon : spécifique et contextuel
{
"name": "rechercher_produits_catalogue",
"description": "Search for products in the e-commerce catalog. "
"Returns name, price, stock, and category. "
"Use for questions about availability or pricing."
}
Descriptions des paramètres
Au niveau des paramètres, l’ennemi est l’implicite. Une unité (euros ou centimes ?), un format (ISO ou local ?), une convention (ID interne ou référence client ?) qui ne sont pas écrits seront devinés — parfois correctement, parfois non, sans aucun signal dans un sens ou dans l’autre. L’enum est ton meilleur outil ici : il ne décrit pas la valeur attendue, il la contraint.
"properties": {
"date_debut": {
"type": "string",
"description": "Start date in ISO 8601 format (YYYY-MM-DD). "
"Defaults to today's date if not specified."
},
"statut": {
"type": "string",
"enum": ["actif", "inactif", "suspendu"],
"description": "Filter by account status. "
"'actif' = accounts in service, "
"'suspendu' = temporarily frozen accounts."
}
}
Schémas imbriqués et références
Un schéma profondément imbriqué est difficile à relire pour toi et à remplir correctement pour le modèle. Si tu atteins trois niveaux, la question à se poser n’est pas de savoir comment mieux l’écrire, mais si la fonction n’en fait pas trop : deux fonctions avec un périmètre clair sont presque toujours préférables à une fonction configurable couvrant les deux cas.
adresse_schema = {
"type": "object",
"properties": {
"rue": {"type": "string"},
"code_postal": {"type": "string"},
"ville": {"type": "string"},
"pays": {"type": "string", "enum": ["FR", "BE", "CH", "LU"]}
},
"required": ["rue", "code_postal", "ville", "pays"]
}
tools = [{
"type": "function",
"name": "creer_livraison",
"description": "Create a delivery with shipping and destination addresses",
"parameters": {
"type": "object",
"properties": {
"expedition": adresse_schema,
"destination": adresse_schema,
"poids_kg": {"type": "number", "minimum": 0.1}
},
"required": ["expedition", "destination", "poids_kg"],
"additionalProperties": False
},
"strict": True
}]
Viktiga punkter
- Active
strict: truepour garantir la conformité des arguments - Valide toujours côté client avec
jsonschemapour les règles métier - Rédige des descriptions précises : c’est le principal levier de qualité
- Utilise
enumpour contraindre les valeurs acceptées - Décompose les schémas complexes en sous-structures réutilisables