2026 OpenAI Structured Outputs : JSON Schema stable, comment faire ?

Votre réponse est bien du JSON valide, mais un champ manque, une valeur est incohérente ou l’outil suivant échoue au moment de l’exécuter.

La solution la plus rapide consiste à utiliser OpenAI Structured Outputs avec un JSON Schema strict, puis à ajouter une validation applicative, une gestion explicite des refus et des sorties interrompues, ainsi qu’une suite de régression. Une simple consigne demandant « répondez en JSON » ne constitue pas un contrat de production.

Cet article s’adresse à vous si vous remplacez le JSON mode, si vous construisez une chaîne d’extraction vers une base de données ou si vous maintenez un système de Function Calling. Il vous aidera aussi à distinguer le schéma de la réponse finale des paramètres attendus par un outil.

Avant l’appel : concevez le contrat à partir du consommateur

La première erreur consiste à commencer par le texte de la consigne. Commencez plutôt par le système qui recevra la réponse. Une base de données, un logiciel de montage audio, un pipeline vidéo ou un exécuteur d’actions n’ont pas besoin d’un texte « propre » : ils ont besoin de champs prévisibles, de types contrôlés et de règles explicites.

Prenez un cas d’usage d’analyse de fichiers audio. Le modèle doit identifier le type de contenu, proposer des étiquettes et signaler les éléments qui nécessitent une revue humaine. Le contrat peut séparer clairement :

• media_type, avec une liste fermée comme audio, video ou image ;
• language, qui peut être une chaîne vide si la langue ne peut pas être déterminée ;
• labels, un tableau de valeurs normalisées ;
• review_required, un booléen ;
• review_reason, une chaîne vide lorsque la revue n’est pas nécessaire.

Cette séparation évite de placer la justification du modèle dans le même champ que la donnée consommée. Si un service aval attend une étiquette, il ne doit pas recevoir une phrase telle que « cette étiquette semble probable ». La justification peut exister dans un champ distinct, éventuellement destiné à l’interface humaine.

Décidez les valeurs obligatoires et les valeurs absentes

Un champ absent et un champ présent avec une valeur nulle ne signifient pas toujours la même chose. Dans un processus de facturation, l’absence de tax_rate peut indiquer un défaut de génération, tandis qu’une valeur nulle peut signifier « aucune taxe applicable ». Votre schéma doit refléter cette différence au lieu de la laisser à l’interprétation du modèle.

Pour chaque propriété, écrivez une décision opérationnelle :

• le champ est-il toujours obligatoire ?
• une chaîne vide est-elle autorisée ?
• la valeur null est-elle utile ou faut-il l’éviter ?
• l’ensemble des valeurs doit-il être fermé par une énumération ?
• le service aval peut-il ignorer une propriété inconnue ?
• les propriétés supplémentaires doivent-elles être refusées ?

Le choix d’additionalProperties est particulièrement important. L’autoriser peut faciliter une expérimentation, mais il réduit la capacité à détecter une dérive du contrat. Le refuser rend le schéma plus strict ; en contrepartie, vous devez ajouter explicitement chaque champ nécessaire.

La documentation officielle de Structured Outputs explique le principe selon lequel la réponse doit suivre le schéma fourni, tout en précisant les limites et les comportements à prendre en compte lors de l’intégration dans la présentation officielle d’OpenAI Structured Outputs.

JSON Schema trop complexe : quand faut-il le découper ?

Un schéma trop ambitieux devient difficile à maintenir et peut augmenter le risque d’incompatibilité avec les capacités prises en charge par l’interface ou le modèle sélectionné. Ne cherchez pas à décrire toute votre base de données dans une seule réponse.

Préférez plusieurs contrats lorsque les opérations sont distinctes :

• un schéma d’extraction brut ;
• un schéma de normalisation ;
• un schéma de décision ;
• un schéma de commande destiné à un outil.

Cette séparation est pertinente pour la création vidéo, par exemple. Une première étape extrait les scènes, une seconde propose des coupes, puis une troisième génère les paramètres d’un outil de rendu. Chaque étape possède un objectif et des erreurs propres. Vous pouvez donc tester et versionner les contrats sans mélanger les règles de production avec les métadonnées d’analyse.

Le découpage est également préférable lorsque certaines branches sont rarement utilisées. Un schéma plus petit permet de limiter les propriétés obligatoires et de réduire la quantité de logique qui doit être vérifiée dans le même appel.

Première étape : placez le mode strict au bon endroit

La configuration dépend de ce que vous voulez produire. Une réponse finale structurée et les arguments d’un outil ne se configurent pas au même endroit. Cette distinction est essentielle si vous migrez un projet existant vers la Responses API.

Pour une réponse finale, vous devez déclarer un format de sortie structuré dans la configuration de la requête, avec un nom de schéma, le JSON Schema et l’option stricte. Pour un appel d’outil, vous devez définir le schéma des paramètres dans la déclaration de la fonction, puis activer le mode strict à cet emplacement.

Le principe de décision peut être résumé ainsi :

Ne copiez pas un ancien exemple prévu pour une autre interface sans comparer les noms de paramètres avec la documentation actuelle. La référence officielle de la Responses API doit servir de point de contrôle pour les champs de réponse, les refus et le fonctionnement en diffusion progressive. Le guide officiel de première requête permet ensuite de vérifier la forme générale de l’appel.

Un squelette minimal doit rester lisible : le schéma doit être déclaré une seule fois, la requête doit transmettre une consigne métier précise et votre code doit conserver la réponse brute pour le diagnostic. Évitez de cacher la validation dans une fonction qui transforme immédiatement la sortie : vous perdriez les informations nécessaires pour comprendre une anomalie.

Attention : le mode strict garantit une conformité structurelle dans les cas pris en charge ; il ne garantit pas que le modèle a correctement interprété un nom de personne, une scène vidéo, un montant ou une relation entre deux champs.

Que garantit Structured Outputs par rapport au JSON mode ?

Le JSON mode vise principalement à obtenir un document JSON syntaxiquement exploitable. Il ne suffit pas, à lui seul, à imposer la présence d’un ensemble de propriétés, le type de chaque valeur, une énumération ou l’interdiction de champs supplémentaires.

Avec OpenAI Structured Outputs, vous fournissez un JSON Schema et demandez une sortie stricte. La garantie recherchée porte donc sur la forme décrite par ce contrat, sous réserve des limites documentées, de la réussite de la requête et de l’absence de refus ou d’interruption. Dans les deux approches, le modèle peut néanmoins produire une donnée fausse, incomplète sur le plan métier ou mal interprétée.

La migration depuis JSON mode doit donc être traitée comme une modification de contrat, pas comme un simple changement de paramètre. Vous devez :

• comparer les champs réellement utilisés par les consommateurs ;
• supprimer les explications mélangées aux données ;
• rendre les propriétés nécessaires explicitement obligatoires ;
• ajouter des règles d’énumération lorsque les valeurs sont fermées ;
• conserver une validation métier indépendante.

Pour un flux d’extraction de factures, un schéma peut imposer que invoice_number soit une chaîne et que items soit un tableau. Il ne peut pas confirmer que le numéro lu dans une image correspond réellement au document, ni que le total calculé par le modèle est exact. Cette seconde partie relève de votre code, de règles comptables ou d’une vérification humaine.

À la réception : séparez conformité et vérité métier

Votre traitement doit effectuer deux contrôles successifs. Le premier concerne l’état de la réponse et sa structure. Le second concerne le sens des données.

Première validation : état de l’API, refus et interruption

Avant de désérialiser la réponse, vérifiez que la requête a abouti et que la sortie contient bien le type d’élément attendu. Une réponse refusée ne doit pas être envoyée au même parseur que le résultat métier. Elle doit entrer dans une branche distincte, avec un statut interne tel que refused, une cause conservée et une action de reprise définie.

En diffusion progressive, vous devez également traiter une sortie interrompue. Une interruption peut empêcher la réception du document complet, même si les fragments déjà reçus semblent correctement formés. Ne transmettez pas un objet partiel à votre base ou à votre exécuteur. Accumulez les fragments, détectez la fin attendue et marquez l’opération comme incomplète si cette fin n’est pas reçue.

La documentation de référence sur les événements de refus dans la Responses API décrit les fragments associés à ce cas dans la référence officielle des refus en diffusion. Votre journal doit conserver l’identifiant de requête, le modèle utilisé, le nom et la version du schéma, ainsi que le statut final.

Deuxième validation : règles croisées et seuil de confiance

Un JSON Schema peut vérifier qu’un champ est un nombre, mais pas qu’il est compatible avec un autre champ. Ajoutez donc des contrôles tels que :

• start<em>time doit précéder end</em>time ;
• une liste de scènes ne doit pas contenir deux intervalles qui se chevauchent ;
• review_required doit être vrai lorsqu’un signal critique est présent ;
• une catégorie doit appartenir au catalogue interne chargé par votre application ;
• un identifiant extrait doit correspondre à une expression ou à une recherche existante.

Pour un logiciel de design, vous pouvez aussi refuser une palette dont une couleur ne correspond pas au profil accepté, même si la valeur est une chaîne parfaitement valide. Pour un montage audio, une durée négative ou une piste inexistante doit être rejetée par la logique applicative, pas seulement par le parseur.

C’est ici que se trouve la limite qu’il ne faut pas promettre à vos parties prenantes : la conformité au JSON Schema ne signifie pas que le contenu est exact à 100 %. Elle réduit une catégorie d’erreurs de format ; elle ne remplace ni les règles métier ni l’évaluation de la qualité.

Que faire quand strict: true échoue malgré tout ?

Un échec après l’activation du mode strict ne signifie pas nécessairement que le modèle « ignore » votre schéma. Plusieurs catégories doivent être distinguées, car chacune appelle une réponse différente.

Schéma non pris en charge

Certaines constructions ou combinaisons peuvent ne pas être acceptées par l’interface ciblée. Commencez par réduire le contrat : moins de niveaux imbriqués, moins de branches, des propriétés explicites et des types simples. Vérifiez ensuite la compatibilité avec la documentation de l’endpoint et du modèle, plutôt que de modifier la consigne au hasard.

La référence officielle des objets de modèle vous aide à confirmer les informations exposées par l’API sur le modèle réellement utilisé. Ne déduisez pas la prise en charge actuelle à partir d’un ancien billet ou d’un exemple conservé dans votre dépôt.

Délai de compilation ou première utilisation

Un nouveau schéma peut nécessiter une préparation interne avant que le traitement normal ne commence. Cette phase doit être observée séparément des erreurs de génération. Si votre système impose une latence stricte, préchauffez le chemin avec une requête contrôlée ou déployez progressivement le schéma avant d’augmenter le trafic.

Vous devez mesurer ce comportement dans votre environnement, car la durée dépend de la forme du schéma, de l’interface et du contexte d’exécution. Ne transformez pas une observation locale en garantie générale.

Sortie interrompue ou trop longue

Une interruption peut être liée à une limite de sortie, à une coupure réseau ou à un arrêt du traitement. Dans ce cas, ne tentez pas de « réparer » silencieusement la chaîne JSON. Marquez-la comme incomplète, conservez la trace et appliquez une stratégie de reprise : demande plus courte, entrée découpée ou traitement manuel.

Réduire la taille de l’entrée aide parfois, mais il faut préserver les éléments nécessaires au raisonnement. Pour des transcriptions audio ou des scripts vidéo, découpez par scène ou par segment sémantique plutôt que selon une longueur arbitraire.

Refus de sécurité

Un refus est une réponse métier particulière, pas un JSON vide. Votre contrat interne doit prévoir cette possibilité. Vous pouvez orienter le document vers une file de revue, demander une transformation autorisée ou expliquer au client que l’opération ne peut pas être exécutée. Il ne faut jamais remplacer automatiquement un refus par une valeur par défaut qui déclencherait une action.

La séparation entre refus, erreur technique et échec de validation rend les tableaux de bord exploitables et évite d’accuser le schéma d’un problème qui vient en réalité de la politique de sécurité.

Échec de validation métier

Lorsque le JSON est conforme mais que les relations entre champs sont fausses, envoyez la sortie vers une file de reprise ou de revue. Une seconde tentative peut utiliser une consigne plus ciblée, mais elle ne doit pas contourner les contrôles. Dans un outil qui supprime ou modifie des fichiers, la validation humaine reste préférable à une correction automatique non traçable.

Mise en production : construisez une régression qui ressemble à vos données

Avant le déploiement, préparez un corpus sans données sensibles qui couvre les situations réellement rencontrées. Il doit contenir des cas normaux, des champs absents, des valeurs vides, des entrées très longues, des caractères inhabituels et des demandes qui doivent être refusées.

Pour chaque cas, enregistrez :

• l’entrée anonymisée ou un identifiant de fixture ;
• le modèle et l’interface appelée ;
• le nom et la version du JSON Schema ;
• la version du parseur ou du validateur ;
• le statut de la réponse ;
• le résultat de la validation structurelle ;
• le résultat de la validation métier ;
• la décision finale : accepter, reprendre ou revoir manuellement.

Les tests doivent vérifier plus que la présence de clés. Ajoutez des assertions sur les énumérations, les limites, les relations entre champs et les effets potentiels sur le système aval. Un test utile est celui qui aurait échoué avant la correction d’un incident réel.

Le document officiel sur les modèles et leur usage peut aussi servir de référence pour contrôler que votre matrice de tests correspond bien à l’endpoint et au mode d’utilisation retenus. Les règles d’accès, de conservation et de traitement des données doivent être examinées avec votre politique interne avant la mise en production.

Une migration progressive vaut mieux qu’un basculement global

Conservez temporairement l’ancien chemin et comparez ses sorties avec le nouveau contrat sur un échantillon contrôlé. Le but n’est pas de choisir la réponse la plus longue, mais de détecter les différences qui affectent réellement les consommateurs : champ renommé, valeur vide, ordre des éléments ou changement de décision.

Quand le nouveau schéma devient la référence, bloquez les modifications directes en production. Toute évolution doit passer par une revue du contrat, une nouvelle série de cas limites et une vérification des systèmes qui lisent la réponse.

Maintenance : traitez le schéma comme une API publique

Un JSON Schema est un contrat d’intégration. Même s’il n’est utilisé que par votre équipe, une modification peut casser un import, un tableau de bord, un outil créatif ou une file d’automatisation.

Adoptez une convention de version claire et documentez les changements compatibles ou incompatibles. Ajouter un champ facultatif peut être acceptable si les consommateurs ignorent les propriétés inconnues. Renommer un champ obligatoire, changer son type ou remplacer une énumération nécessite généralement une nouvelle version ou une période de transition.

Chaque changement doit déclencher une vérification de quatre éléments :

• l’acceptation du schéma par l’interface ;
• le comportement de la première utilisation et des appels répétés ;
• la compatibilité du validateur local ;
• la capacité des systèmes aval à traiter les nouvelles données.

Ne laissez pas les journaux contenir des données métier en clair par défaut. Un identifiant de fixture, un condensat du schéma et les statuts de validation suffisent souvent pour diagnostiquer une régression. Pour les contraintes de traitement et de contrôle des données, reportez-vous aux informations officielles sur les politiques d’usage par endpoint, puis adaptez-les à vos exigences contractuelles.

Le choix d’environnement pour vos tests de régression

Un poste local reste adapté si vous testez quelques schémas, si vos données peuvent rester sur votre réseau et si vous avez besoin d’un accès direct à des périphériques audio, vidéo ou de design. En revanche, les tests de compatibilité répétés peuvent devenir pénibles lorsque l’équipe doit reproduire exactement un environnement, exécuter des lots pendant une période limitée ou partager une machine de validation sans modifier les postes de travail.

Dans ce cas, un Mac loué par l’intermédiaire de kvmboot peut servir d’environnement temporaire pour vos essais d’intégration : validation d’un client macOS, tests d’un workflow audiovisuel, exécution d’un lot de fixtures ou vérification d’un outil qui dépend de l’écosystème Apple. Vous gardez toutefois une décision honnête à prendre : l’achat d’un Mac est plus cohérent pour une charge stable et continue, tandis que la location convient mieux à une campagne de test, une migration ou un besoin ponctuel.

Votre solution actuelle peut présenter au moins trois inconvénients concrets : elle monopolise un poste de développeur, elle rend les essais difficiles à reproduire lorsque les versions diffèrent et elle oblige parfois à maintenir une machine dédiée qui reste inutilisée entre deux campagnes. Pour une équipe qui doit seulement vérifier un lot de réponses structurées, payer et administrer cette capacité en permanence n’est pas toujours rationnel. Vous pouvez consulter le centre d’aide de kvmboot pour examiner les conditions d’accès avant de planifier vos tests.

Avant de lancer le premier lot, préparez donc un paquet de fixtures sans données sensibles, verrouillez la version du schéma, séparez les refus des erreurs de validation et décidez à l’avance quels résultats doivent entrer dans une file humaine. Une fois ces garde-fous en place, OpenAI Structured Outputs devient une base solide pour alimenter une base de données ou un outil, mais jamais un substitut à la validation métier. Pour un besoin temporaire de calcul ou de test sur macOS, vous pouvez aussi évaluer une réservation de Mac pour votre campagne de validation, en comparant son coût et sa durée avec le maintien d’une machine locale.