JSON Toolkit

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.

Intermédiaire~8 min de lecturePublié le 2026-11-19Mis à jour le 2026-11-19
Schéma des règles de réécriture JSON Schema pour le mode strict du LLM

À 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 :

  1. 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.
  2. 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.
  3. 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 refusal de la réponse est vrai — lire le JSON à ce stade n'a aucun sens ; passez à l'humain ou reformulez la requête.
  • Troncature : finish_reason vaut length, 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.

Références

Articles liés

Tests de contrat JSON Schema : soudez vos règles de validation dans la CI

Un schéma ne s'achève pas à l'écriture — c'est là que commence la dégradation. Une coquille assoupit silencieusement la validation, un refactoring casse toutes les fixtures. Ce guide présente un dispositif de test de contrat exploitable : fixtures positifs, négatifs et instantanés, lint du schéma lui-même, compilation unique réutilisée, et quatre portes de CI qui transforment la casse du contrat en build rouge.

Intermédiaire~8 min de lectureMis à jour le 2026-11-05

Le JSON d'un LLM est tronqué : regardez d'abord la raison d'arrêt, ensuite la réparation

Le modèle renvoie un JSON coupé au milieu, et le parseur ne vous donne qu'un numéro de colonne. Refermer les accolades le rend de nouveau analysable, mais chaque champ manquant disparaît dans les données. Cet article trace la frontière entre ce qu'une réparation de troncature peut honnêtement récupérer et ce qui doit être relancé : filtrage par stop_reason, dimensionnement du plafond, ordre des champs du schéma.

Pratique~5 min de lectureMis à jour le 2026-11-14

Sans additionalProperties, la validation de schéma ne valide rien

Une validation réussie ne garantit pas des données propres. Pydantic ignore les champs inconnus par défaut, Zod les supprime, Ajv les laisse passer — les paramètres hallucinés et les clés mal orthographiées traversent en silence. Cet article montre les trois formes d'acceptation silencieuse et donne les recettes complètes : fermer les objets, contrôler la coercition, serrer chaque niveau d'imbrication.

Intermediate~8 min de lectureMis à jour le 2026-11-02