Les sorties structurées du LLM qui cassent : comment écrire vraiment un schéma pour le mode strict
L’essentiel : Activer strict sur un schéma JSON ordinaire renvoie le plus souvent un 400 : tous les champs requis, additionalProperties:false sur chaque objet, $ref et allOf rejetés d'emblée. Ce guide montre comment réécrire en lot un schéma laxiste en version compatible strict, avec unions nullables, limites dures et checklist de tri des refus.

À retenir : strict: true n'est pas un interrupteur « soyons un peu plus sérieux », c'est un contrat qui n'accepte qu'un sous-ensemble de JSON Schema. Tous les champs dans required, additionalProperties: false sur chaque objet, $ref et allOf rejetés d'emblée. Expédier un schéma non réécrit en mode strict, c'est obtenir un 400, pas une sortie plus fiable.
Le même schéma qui passe sans problème dans votre validateur local est renvoyé dès que vous attachez strict: true et l'envoyez à l'API du modèle. Le modèle n'est pas devenu plus bête : le fournisseur a tracé une frontière dure autour du sous-ensemble de schéma dont le décodage contraint a besoin, et votre schéma l'a franchie.
Ce que strict change vraiment : enfermer l'échantillonneur dans une grammaire
En mode ordinaire, le JSON produit par le modèle ne correspond à votre schéma que « probablement », soutenu par la ligne « réponds en JSON » dans le prompt. Sur les evals officiels d'OpenAI, gpt-4-0613 suivant des schémas complexes par prompt seul obtenait moins de 40 % ; avec strict activé, gpt-4o-2024-08-06 a atteint 100 % sur la même suite.
Le mécanisme est le décodage contraint (constrained decoding) : à la première requête, l'API compile votre schéma en un automate à états finis, et pendant le décodage chaque token doit être admis par cet automate. Le modèle ne peut pas émettre un token qui viole le schéma. Ce n'est pas un rappel — c'est un verrou physique. Le coût se paie en deux fois : la première compilation d'un nouveau schéma prend du temps supplémentaire (typiquement moins de 10 secondes, jusqu'à une minute pour les schémas complexes) et ajoute environ 5 à 8 % de latence au premier token ; les artefacts de compilation sont mis en cache, les requêtes suivantes ne paient plus rien.
Soyez clair sur ce qui est garanti et ce qui ne l'est pas : syntaxe et forme sont verrouillées, la sémantique ne l'est pas. Le modèle peut toujours remplir estimate_hours avec 400 en toute confiance ou extraire la mauvaise adresse e-mail. La forme est un plancher, pas un plafond — la qualité sémantique reste à la charge d'un ensemble d'évals. En 2026, les modèles de pointe sous charge affichent encore environ 0,4 % de taux résiduel de malformation ; la boucle de réessai reste obligatoire.
Trois règles dures : tout requis, aucune clé en trop, nullable à la place d'optional
Le mode strict impose trois exigences de réécriture, chacune à contre-courant de l'intuition ordinaire du JSON Schema :
- Chaque champ doit figurer dans required. Le mode strict n'a pas de concept de champ optionnel. Pour exprimer « facultatif », gardez le champ dans required mais déclarez le type comme union nullable —
"type": ["string", "null"]— et laissez le modèle renvoyer null en cas d'absence. C'est exactement l'inverse de la pratique standard où required ne liste que les champs vraiment nécessaires. - Chaque objet doit déclarer explicitement additionalProperties: false. Dans les schémas ordinaires on laisse souvent ce mot-clé de côté (voir notre article sur le comportement d'additionalProperties selon les runtimes), mais en mode strict c'est une condition d'admission : sans lui, la requête échoue. La raison est brutale — l'automate ne peut générer que les clés déclarées, donc toute clé non déclarée est inatteignable par construction.
- Le piège Python : Pydantic retire les champs à valeur par défaut de required. Un
priority: str = "low"fait disparaître une entrée du required du schéma généré, et strict le refuse. Supprimez le défaut ou comblez en masse avec le script ci-dessous.
Les trois règles doivent s'appliquer récursivement à chaque objet imbriqué. Corriger le niveau supérieur en laissant les objets enfants intacts produit quand même un 400. Exemple minimal conforme :
{
"type": "object",
"properties": {
"intent": { "type": "string", "enum": ["book", "cancel", "question", "other"] },
"note": { "type": ["string", "null"] }
},
"required": ["intent", "note"],
"additionalProperties": false
}
Ces écritures tombent d'emblée : mots-clés interdits et mots-clés muets
Le mode strict ne supporte qu'un sous-ensemble de JSON Schema. Répartissez les mots-clés en deux seaux et traitez-les différemment :
| Seau | Mots-clés | Comportement en mode strict |
|---|---|---|
| Rejeté d'emblée | références $ref / $defs, allOf, not, dependentRequired, dependentSchemas, if/then/else |
L'API renvoie une erreur ; la requête échoue |
| Silencieusement non appliqué | pattern, minLength, maxLength, format, minimum, maximum, multipleOf (modèles fine-tuned) |
Ni erreur ni application — les contraintes regex à revalider vous-même dans la couche applicative |
Le traitement diffère : le premier seau doit être réécrit — dépliez les $ref en ligne et fusionnez allOf dans properties. Le second peut rester (certaines configurations les acceptent), mais ne le traitez jamais comme une défense. Compter sur "pattern": "^v\\d+\\.\\d+\\.\\d+$" pour garantir le format de version, c'est courir à poil sous strict ; relancez une validation explicite sur chaque réponse. Une règle de plus tout en haut : la racine du schéma ne peut être ni un tableau ni une union nue — enveloppez-la dans un object.
Limites dures : 5 000 propriétés, 10 niveaux d'imbrication, 120 000 caractères
Même avec tous les mots-clés conformes, dépasser les limites de taille fait échouer. Les chiffres officiels d'OpenAI :
- au plus 5 000 propriétés d'objets sur toute la schéma, au plus 10 niveaux d'imbrication (chez Anthropic la limite est d'environ 6 niveaux) ;
- longueur totale des chaînes des noms de propriétés, noms de définitions, valeurs d'enum et de const plafonnée à 120 000 caractères ;
- au plus 1 000 valeurs d'enum au total ; un enum de chaînes comptant plus de 250 valeurs ne peut pas dépasser 15 000 caractères.
On y touche rarement, mais « prendre tout le dictionnaire de l'entreprise comme enum » et « comprimer un graphe d'objets à trois niveaux en un seul » sont deux vraies scènes d'accident. Face à ça, découpez : scindez le schéma géant en plusieurs appels ou aplanissez la structure. Effet utile en bonus : les clés de sortie suivent l'ordre des clés du schéma ; les parseurs en aval qui dépendent d'un ordre fixe peuvent considérer ça comme une fonctionnalité.
Un script qui réécrit en lot un schéma laxiste en forme strict
Éditer à la main couche par couche garantit des oublis. Le script récursif ci-dessous (le patron publié dans le guide 2026 de DevToolLab) ajoute en un passage « chaque objet fermé, chaque clé requise » :
def make_strict(schema: dict) -> dict:
"""additionalProperties:false + chaque clé requise, à chaque niveau."""
if isinstance(schema, dict):
if schema.get("type") == "object" and "properties" in schema:
schema["additionalProperties"] = False
schema["required"] = list(schema["properties"].keys())
for value in schema["properties"].values():
make_strict(value)
elif isinstance(schema, dict):
for value in schema.values():
make_strict(value)
elif isinstance(schema, list):
for item in schema:
make_strict(item)
return schema
Le flux de travail associé : d'abord inférer un squelette de schéma depuis un échantillon JSON (la page d'outil /convert/schema de ce site fait une inférence unidirectionnelle de JSON vers Schema), prendre le squelette comme point de départ, le serrer avec les trois règles strict, puis passer make_strict comme dernier filet. Attention : le script ne corrige que la forme — unions nullables, enums et champs sémantiques restent des décisions humaines ; tout schéma contenant des $ref doit être déplié en ligne avant de passer dedans.
L'équivalent chez Anthropic : tool-as-schema
Anthropic n'a pas d'interrupteur strict: true. Le patron canonique de 2026 consiste à attacher le schéma de réponse comme input_schema d'un outil et à forcer le modèle à l'appeler via tool_choice :
await anthropic.messages.create({
model: "claude-sonnet-4-6",
tools: [{ name: "emit", description: "Emit final summary", input_schema: schema }],
tool_choice: { type: "tool", name: "emit" },
messages,
});
Le canal d'appel d'outils valide lui-même le JSON, donc l'effet équivaut au mode strict. Les différences vivent dans les détails : limite d'imbrication d'Anthropic d'environ 6 niveaux, support de .nullable() plutôt que .optional() ; les trois fournisseurs (OpenAI, Anthropic, Gemini) acceptent des sous-ensembles de schéma légèrement différents. Réutiliser un même schéma sans modification entre fournisseurs n'est pas fiable — revalidez à chaque changement de modèle.
Trier refusal, troncature et timeouts avant de parler de réessais
Quand le mode strict vous rend quelque chose d'invalide, il n'y a que trois causes, chacune exigeant une réaction différente :
- Refusal : le modèle a refusé d'exécuter (requête non sûre, etc.). Le champ
refusalde la réponse est vrai — lire le JSON à ce stade n'a aucun sens ; passez à l'humain ou reformulez la requête. - Troncature :
finish_reasonvautlength, max_tokens était insuffisant, la sortie est physiquement incomplète. Les contraintes du schéma ne sauvent pas une sortie tronquée ; augmentez le budget ou comprimez la structure. Identification et récupération partielle dans notre article sur le diagnostic et la réparation du JSON tronqué. - Malformation : quand le fournisseur ne supporte pas complètement le sous-ensemble, un mauvais JSON peut quand même arriver. Ne réessayez pas avec un simple « réessaie » — remettez le texte exact de l'erreur de validation dans le prompt : « severity doit être low/medium/high/critical ; tu as produit urgent ; corrige et réémiss ». Les réessais avec le contexte d'erreur font tomber le nombre moyen de réessais de 3 à environ 1,5.
Mettez un plafond dur aux réessais (deux, disons) ; au-delà, dégradez vers un modèle plus petit pour la correction ou vers une file humaine. Ne laissez pas une seule mauvaise sortie paralyser toute la chaîne.
Checklist avant mise en production
| Vérification | Critère de passage |
|---|---|
| required | Chaque champ de chaque objet figure dans required |
| additionalProperties | false explicite sur chaque objet, jusqu'au niveau le plus profond |
| Sémantique facultative | Modélisée par des unions ["string", "null"] ; pas d'optional nu |
| Mots-clés interdits | Aucun $ref / allOf / if-then-else / dependentRequired |
| Mots-clés muets | pattern et format revalidés dans la couche applicative |
| Taille | ≤5 000 propriétés, ≤10 niveaux, ≤120 000 caractères de chaînes |
| Tri | refusal / length / erreur de parsing traités par voies séparées |
| Réessais | Avec le texte original de l'erreur, plafond 2, puis dégradation |
| Sémantique | Evals ou assertions de champ en dehors du schéma |
Une fois cette checklist passée, la fiabilité de forme est verrouillée. Pour la sémantique et l'évolution du contrat — versionner les schémas et faire rougir d'abord le CI quand un schéma casse — voyez souder les contrats de schéma dans le CI.
FAQ
Le mode strict garantit-il la justesse des valeurs de champs ?
Non. Il verrouille seulement syntaxe et forme au décodage : chaque clé présente, types corrects, enums légaux. Rien sur la justesse sémantique — le modèle peut toujours produire des données bien formées mais fausses. La couche sémantique s'appuie sur des évals ou des assertions par champ.
Pourquoi les champs facultatifs vont-ils aussi dans required ?
L'automate du mode strict exige que chaque propriété déclarée soit atteignable ; une entrée required manquante échoue à la validation. La facultativité est simulée par une union ["string", "null"] : le champ apparaît toujours, la valeur peut être null, et le code en aval traite null comme absent.
pattern et minLength sont-ils totalement inutiles ?
Sous les modèles fine-tuned et la plupart des configurations strict, ils ne sont pas appliqués. Ils ne provoquent pas d'erreur — et c'est ça qui les rend dangereux : vous croyez avoir une défense, elle n'existe pas. Validez explicitement avec ajv ou jsonschema les réponses qui dépendent de ces contraintes.
Le mode strict ralentit-il les réponses ?
Seule la première requête avec un nouveau schéma paie la compilation (typiquement moins de 10 secondes, jusqu'à une minute pour les complexes). Une fois les artefacts compilés mis en cache, les requêtes suivantes voient environ 5 à 8 % de latence supplémentaire au premier token. En régime stable c'est imperceptible ; le coût réel n'apparaît qu'avec des schémas qui changent souvent.
Que retester après un changement de version de modèle ?
Trois choses : si le sous-ensemble de schéma supporté par cette version a changé, si les champs refusal et finish_reason sont toujours là, si les limites d'imbrication et de taille se sont resserrées. Les fournisseurs acceptent des sous-ensembles différents ; avant de réutiliser un schéma entre modèles, vérifiez-le avec une requête minimale.