Ranger une sortie de modèle en JSON analysable bloque rarement sur l'obéissance du modèle, plutôt sur l'origine du Schema et la façon de le verrouiller. On commence par ce qu'est Structured Output et pourquoi inverser depuis un vrai JSON, puis types, required et extra fields, les enveloppes OpenAI / Claude / Gemini, enfin recette et pièges.
Les enveloppes plateforme changent ; l'ordre de verrouillage d'un JSON Schema reste assez stable. Posez d'abord les concepts et le chemin depuis l'échantillon, puis comment habiller chaque fournisseur.
Qu'est-ce qu'un Structured Output Schema ?
Un Structured Output Schema est un JSON Schema qui contraint la forme de sortie d'un grand modèle. Il dit au modèle quels champs renvoyer, de quel type, et quels absents font échouer. OpenAI l'emballe dansjson_schema, Gemini utiliseresponseSchema, Claude et MCP se rapprochent plutôt duinput_schema d'un outil.
Contrairement à un simple « formater le JSON », l'objectif ici est un parse stable. Un Schema flou fait dériver ensemble validation, Mock, Zod et Function Calling.
Pourquoi inverser un Schema depuis un échantillon JSON ?
La doc d'API est souvent en retard sur l'implémentation. Une réponse de prod vous dit si le prix est199 ou"199.00", si un tableau peut être vide, si un objet imbriqué perd une couchedata. Ces détails décident si Structured Output tient — pas « le nom de champ a l'air juste ».
Partir d'un échantillon, ce n'est pas laisser l'outil décider le produit. L'inférence auto ne lit que la structure présente ;required,enum et « peut-on ajouter des champs » restent des décisions métier.
Trois verrous : types, required, extra fields
Un Schema utilisable commence par ces trois points. pattern, format, description peuvent attendre ; si ceux-là sont faux, toute la chaîne dérive.
1. Inférer les types depuis un vrai JSON
Regardez d'abord si le champ est string, number, integer, boolean, array ou object. E-mail, URL, date peuvent aussi porterformat, mais n'en faites pas la contrainte principale.
L'inférence de l'espace de travail (au 27/08/2026) a trois détails à connaître :
- Dans le JSON,
199.00se parse en entier199, et sera marquéinteger, pasnumberd'un outil. - Un tableau ne sonde que les 5 premiers éléments avant de fusionner les types. Si le 6e devient soudain un objet, la génération ne le voit pas.
- Les chaînes tentent de reconnaître email, URL http(s) et une date commençant par
YYYY-MM-DD.
2. Marquer les vrais champs requis
Required, ce n'est pas « présent dans cet échantillon », c'est « inutilisable sans ça côté métier ». N° de commande, SKU, prix : souvent requis ; tag marketing, sous-titre : souvent optionnels.
Pour un brouillon qui tourne, le générateur met toutes les clés de l'échantillon dansrequired. C'est un brouillon, pas une décision produit. Avant la prod, retirez les champs qui peuvent manquer.
3. Décider si des champs extra sont autorisés
Pour une sortie LLM, fermez d'abordadditionalProperties. Le modèle aime glisser en plussummary,note,explanation. Dès que ces champs entrent dans la réponse, le parse en aval devient instable.
Séparez les faits du comportement de l'outil.Le strict Structured Outputs officiel d'OpenAI exige que l'objet déclareadditionalProperties: false. Le brouillon généré ici depuis du JSON ne l'ajoute pas tout seul : ajoutez-le avant la prod.
Un échantillon produit suffisant pour générer un Schema
La réponse ci-dessous suffit déjà pour un brouillon OpenAI / Claude / Gemini. Écrivezprice en nombre, pas en"199.00" d'un outil.
{
"name": "无线耳机",
"price": 199.5,
"sku": "HP-1024",
"inStock": true,
"tags": ["audio", "bluetooth"]
}
Selon les règles d'inférence actuelles du site, cet échantillon donne :
| Champ | Inférer les types | À faire après génération |
|---|---|---|
name |
string | Ajouter description ; confirmer s'il est requis |
price |
number | Écrire 199.5 pour garder la décimale ; 199.00 devient integer |
sku |
string | Pour une contrainte de format, ajoutez ensuite pattern |
inStock |
boolean | Ne laissez pas le modèle renvoyer la chaîne “true” |
tags |
string[] | Confirmez si un tableau vide est licite ; ne figez pas l'énum d'un coup |
L'échantillon prêt, générez les enveloppes plateforme en un clic dansl'outil Structured Output, puis ajoutez description selon le métier.
En quoi les enveloppes OpenAI, Claude, Gemini, MCP diffèrent-elles ?
Il ne doit y avoir qu'un Schema cœur. L'écart plateforme est surtout l'enveloppe, pas « name est-il string ».
| Plateforme | Champ d'emballage | À surveiller à l'écriture |
|---|---|---|
| OpenAI | type: json_schema + json_schema.schema |
en mode strict, l'objet doit en général avoiradditionalProperties: false, et les propriétés déclarées entrer dans required |
| Gemini | responseSchema + responseMimeType: application/json |
Assurez d'abord un MIME JSON, ensuite les contraintes de champs |
| Claude | Leinput_schema |
d'un outil se rapproche de Function Calling : d'abord ce que fait l'outil, ensuite la contrainte d'entrée |
| MCP | inputSchema |
L'Agent voit une description de capacité + une structure d'entrée : ne jetez pas un Schema nu |
| JSON Schema générique | L'objet Draft-07 lui-même | Idéal pour valider d'abord, puis passer à Zod / OpenAPI |
La forme d'emballage OpenAI courante est ci-dessous. C'est un schéma de structure ;additionalProperties est à ajouter selon les exigences strict officielles :
{
"type": "json_schema",
"json_schema": {
"name": "response_schema",
"strict": true,
"schema": {
"type": "object",
"additionalProperties": false,
"required": ["name", "price", "sku", "inStock", "tags"],
"properties": {
"name": { "type": "string" },
"price": { "type": "number" },
"sku": { "type": "string" },
"inStock": { "type": "boolean" },
"tags": {
"type": "array",
"items": { "type": "string" }
}
}
}
}
}
Quels pièges courants à la génération d'un Structured Output Schema ?
Un nombre écrit en chaîne
Si l'échantillon a"199.00", le type sera inféré string : calculs et validations échoueront ensuite. Prix, quantités, notes : mettez des nombres dans l'échantillon.
enum trop étroit ou trop large
Trop peu de valeurs d'énum : le modèle devine dans un ensemble trop étroit ; trop : plus de contrainte. Partez des vraies valeurs métier, n'écrivez pas d'un coup « les statuts qu'on aura peut-être un jour ».
null et un champ absent, ce n'est pas la même chose
Champ optionnel (peut manquer) et champ nullable (la clé est là, la valeur estnull) : ce n'est pas la même chose. Beaucoup de parseurs utilisentif (obj.price) et blessent à la fois0 etnull.
Types d'éléments de tableau hétérogènes
Ne laissez pas[1, "2"] se glisser dans l'échantillon. L'inférence de ce site ne voit que les 5 premiers éléments ; un mix de types peut aussi se fondre en contrainte vide. Pour comparer deux réponses, utilisezComparaison JSON : chemins d'abord, puis corrigez l'échantillon.
Comment recetter après génération ?
Ne vous arrêtez pas à « est-ce que ça parse ». Parcourez plutôt cette chaîne :
- Générez le brouillon avecJSON → Schema ou l'outil Structured Output.
- Vérifiez à la main required, number / integer, additionalProperties.
- Passez une deuxième vraie réponse dansla validation Schema. Le premier échantillon est toujours trop optimiste.
- Si le front utilise Zod, enchaînez versZod Schema, pour ne pas écrire deux jeux de règles.
- Si la doc d'API doit suivre, exportezOpenAPI 3.1, ajoutez description et codes d'erreur.
Si la validation échoue, corrigez d'abord l'échantillon ou required ; n'ajoutez pas une pile deanyOf pour assouplir le Schema.
Quel lien avec Function Calling, Zod et OpenAPI ?
Cet article ne règle qu'une chose :comment obtenir depuis du JSON un Schema qui contraint la sortie du modèle. Les capacités voisines peuvent réutiliser la même structure cœur, sans devenir un autre tutoriel complet.
- Function Calling : on contraint l'entrée d'outil, pas le texte de réponse finale.
- MCP Tool : on standardise une capacité d'outil ; l'entrée reste un JSON Schema.
- Zod / OpenAPI : la même structure sert la validation front et la doc d'API.
Dites d'abord à quoi ressemble la sortie, puis choisissez l'enveloppe d'export.
Quelle est la suite ?
Si vous avez déjà une vraie réponse : ouvrezla page de l'outil Structured Output, collez le JSON, choisissez OpenAI / Gemini / Claude / MCP, puis ne changez à la main que trois points — required, additionalProperties, description. Tout se traite dans le navigateur, rien n'est envoyé au serveur.
Sans vraie réponse, n'inventez pas l'« objet parfait ». Une entrée minimale utilisable vaut mieux qu'un faux exemple complet empilé de commentaires.
FAQ
Qu'est-ce qu'un Structured Output Schema ?
C'est un JSON Schema qui contraint la forme de sortie d'un grand modèle. Le modèle doit renvoyer du JSON selon les champs, types et required déclarés — pas du texte libre.
Pourquoi générer le Schema depuis un échantillon JSON, plutôt qu'à la main ?
Une vraie réponse expose les détails que la doc rate souvent. Inverser depuis l'échantillon, puis figer required et additionalProperties à la main, tient en général mieux qu'écrire de tête.
Quelle différence entre Structured Output chez OpenAI, Claude et Gemini ?
Le fond est un JSON Schema, les champs d'emballage diffèrent. OpenAI utilisejson_schema, Gemini utiliseresponseSchema, Claude / MCP se rapprochent d'une structure d'entrée d'outil. Écrivez d'abord le Schema cœur, puis l'enveloppe.
Un Schema auto-généré peut-il aller en prod tel quel ?
Non. Le générateur marque required toutes les clés de l'échantillon, n'écrit pas additionalProperties par défaut, et ne voit que les premiers éléments d'un tableau. Il faut une relecture humaine et une validation sur une deuxième réponse.
additionalProperties : ouvert ou fermé ?
Pour une sortie LLM, fermez d'abord. Le mode strict OpenAI exige aussi que l'objet déclareadditionalProperties: false d'un outil.
En résumé
Pour générer un Structured Output Schema depuis un échantillon JSON, l'ordre juste est : vraie réponse → types → required → fermer extra fields → enveloppe plateforme → valider avec une autre donnée. L'outil raccourcit le brouillon, il ne décide pas le métier. Un seul Schema cœur ; OpenAI, Claude, Gemini, Zod et OpenAPI en descendent.