Qu’est-ce que JSON Schema ? Pourquoi OpenAI, Gemini, Claude et MCP dépendent-ils de plus en plus de JSON Schema ?

Cet article explique pourquoi JSON Schema devient le contrat commun des agents IA, des API et des plateformes d’outils. Nous distinguons la syntaxe JSON, la validation de structure et la validation métier, puis comparons OpenAI, Gemini, Claude et MCP afin de proposer une méthode fiable de réutilisation et de maintenance.

Le site officiel de JSON Schema indique que la version de référence actuelle est le dialecte 2020-12. Ce point suffit à tirer une conclusion opérationnelle : JSON Schema pour un agent IA doit être traité comme un contrat de données, pas comme une simple consigne de formatage. Il décrit la structure et certaines contraintes, permet une validation automatique, mais chaque fournisseur n’en accepte qu’une partie. Nous conseillons donc de conserver un schéma principal en interne, puis de générer des versions adaptées pour OpenAI, Gemini, Claude et MCP. (json-schema.org)

Cette analyse s’adresse à trois profils. Les développeurs d’applications IA qui doivent stabiliser les réponses et les paramètres d’outils. Les ingénieurs de plateforme qui cherchent à réutiliser un même contrat entre plusieurs modèles. Les testeurs qui veulent automatiser les contrôles de structure, de compatibilité et de régression.

Le contrat de données

JSON est un format de sérialisation. Il peut représenter un objet, une liste, un nombre, une chaîne ou une valeur booléenne. Sa validité syntaxique ne dit toutefois rien de l’usage attendu par votre logiciel.

Cet objet est du JSON valide :

{
  "status": "ready",
  "duration": "fast"
}

Il peut pourtant être rejeté par votre application si celle-ci attend :

• un champ status limité à pending, running ou completed ;
• un champ duration numérique ;
• un identifiant obligatoire ;
• l’interdiction des propriétés inconnues.

JSON Schema ajoute ces informations sous une forme déclarative. Les mots-clés type, properties, required, enum, items et additionalProperties décrivent les limites que le validateur doit appliquer. La spécification sépare notamment le vocabulaire de base et les règles de validation. Le mot-clé $schema permet de déclarer le dialecte utilisé par le document. (json-schema.org)

La différence doit rester nette :

• JSON valide : les caractères et la structure respectent la syntaxe JSON ;
• JSON conforme au schéma : les champs, types et contraintes déclarés sont respectés ;
• donnée acceptable métier : la valeur correspond réellement à votre système, à votre utilisateur et à votre processus.

Cette troisième couche n’est pas couverte par JSON Schema seul. Un schéma peut imposer un identifiant de commande sous forme de chaîne, mais il ne sait pas, sans appel à votre base, si cette commande existe ou appartient au bon client.

Les sorties structurées

OpenAI Structured Outputs

Dans OpenAI Structured Outputs, le format json_schema sert à demander une réponse structurée selon un schéma fourni. La documentation distingue ce mécanisme de l’ancien mode json_object, qui vise principalement à obtenir du JSON valide. En mode strict, OpenAI précise cependant que seule une partie de JSON Schema est prise en charge. (platform.openai.com)

Pour un agent de production, le flux recommandé est donc :

1. définir un schéma de sortie interne ;
2. sélectionner les propriétés réellement indispensables ;
3. produire une variante compatible avec le mode strict ;
4. vérifier la réponse côté serveur ;
5. traiter séparément les refus, erreurs et données incomplètes.

Prenons un cas de postproduction vidéo. Un modèle analyse une séquence et renvoie :

{
  "scene_type": "interview",
  "speakers": 2,
  "has_music": false,
  "markers": [
    {
      "timecode": "00:03:12",
      "label": "cut"
    }
  ]
}

Le schéma peut imposer speakers comme entier, has_music comme booléen et scene_type comme énumération. Il ne prouve pas que le timecode correspond à une image existante dans le fichier vidéo. Cette vérification appartient à votre pipeline média.

Gemini Structured Output

Gemini Structured Output accepte également une définition de schéma pour guider la forme de la réponse. La documentation officielle précise que le mode structuré prend en charge un sous-ensemble de JSON Schema. Elle liste notamment les objets, tableaux, chaînes, nombres, entiers, booléens, valeurs nulles, propriétés, champs obligatoires, énumérations, références et certaines contraintes numériques. (ai.google.dev)

Cette liste a une conséquence directe. Un schéma interne riche, avec plusieurs compositions et contraintes avancées, ne doit pas être envoyé sans transformation. Même lorsqu’un mot-clé apparaît dans la documentation, son interprétation peut différer de celle d’un validateur généraliste.

Pour un outil de design génératif, vous pouvez demander une structure de brief :

• format de sortie : image, vidéo ou audio ;
• ratio : 16:9, 1:1 ou 9:16 ;
• nombre de variantes ;
• palette dominante ;
• éléments à éviter.

Le modèle peut respecter la forme, mais il ne garantit pas que le moteur de rendu acceptera réellement chaque paramètre. Votre adaptateur doit donc filtrer les valeurs, convertir les noms internes et vérifier les limites de l’API cible.

Claude et les paramètres d’outils

Dans l’API Claude, la définition d’un outil comprend notamment name, description et input_schema. Ce schéma décrit les paramètres transmis à l’outil. Anthropic insiste aussi sur la précision des descriptions : le modèle doit comprendre ce que l’outil fait, quand l’utiliser, quand ne pas l’utiliser et ce que chaque paramètre signifie. (docs.anthropic.com)

Cela montre une distinction importante. JSON Schema décrit la forme. La description explique l’intention. Un champ project_id de type chaîne ne dit pas si l’outil attend un identifiant local, un identifiant distant ou un nom lisible. Si cette ambiguïté reste dans le contrat, l’agent peut produire un JSON valide mais appeler le mauvais service.

Attention : un schéma conforme ne donne aucun droit d’accès. Il ne vérifie ni l’identité de l’utilisateur, ni la propriété d’une ressource, ni l’autorisation d’exécuter une action destructive.

Les appels d’outils

Dans un appel de fonction, JSON Schema ne sert pas d’abord à formater la réponse finale. Il décrit les paramètres que le modèle doit proposer à l’exécuteur.

Le flux comporte quatre responsabilités :

• le modèle choisit éventuellement un outil ;
• le schéma décrit les arguments attendus ;
• l’exécuteur valide les arguments reçus ;
• le service métier décide si l’action est autorisée et réalisable.

Cette séparation évite deux erreurs fréquentes.

La première consiste à croire que required signifie « valeur correcte ». Un champ order_id peut être obligatoire tout en contenant un identifiant inexistant. La seconde consiste à croire que enum suffit à contrôler une transition métier. Une valeur cancelled peut être autorisée par le schéma, alors que la commande est déjà expédiée.

Pour un outil de montage audio, le schéma peut imposer :

{
  "type": "object",
  "properties": {
    "track_id": {
      "type": "string"
    },
    "start_ms": {
      "type": "integer",
      "minimum": 0
    },
    "operation": {
      "type": "string",
      "enum": ["cut", "fade_in", "fade_out"]
    }
  },
  "required": ["track_id", "operation"]
}

Le validateur peut bloquer une valeur négative ou une opération inconnue. Il ne sait pas si track_id appartient au projet ouvert. L’exécuteur doit charger le projet, vérifier les droits, contrôler l’état de la piste et seulement ensuite modifier le fichier.

OpenAI documente également l’usage de schémas JSON pour les paramètres de fonctions et précise que le mode strict ne couvre pas l’intégralité de JSON Schema. (platform.openai.com)

MCP et les résultats structurés

MCP ajoute une couche de protocole. Il standardise la manière dont un serveur expose ses outils et dont un client les découvre et les appelle. Il ne remplace pas le mécanisme de sélection du modèle.

Dans la spécification des outils MCP :

• inputSchema décrit les paramètres attendus ;
• outputSchema est facultatif et décrit la structure du résultat ;
• structuredContent transporte le résultat structuré ;
• content peut contenir une représentation lisible ou sérialisée pour la compatibilité.

La spécification indique qu’un serveur doit fournir un résultat conforme à outputSchema lorsqu’il en publie un, tandis que le client devrait valider ce résultat. Elle recommande aussi, pour la compatibilité, de renvoyer le JSON sérialisé dans un bloc textuel lorsqu’un résultat structuré est fourni. (modelcontextprotocol.io)

Le modèle mental correct est donc :

1. MCP expose un catalogue d’outils ;
2. le modèle reçoit les noms, descriptions et schémas ;
3. le modèle propose un appel ;
4. le client ou l’orchestrateur contrôle les arguments ;
5. le serveur exécute l’action ;
6. le résultat est validé avant d’être réinjecté dans le contexte.

Il faut aussi distinguer la spécification publiée et les propositions d’évolution. Une proposition MCP de 2026 vise à rapprocher inputSchema, outputSchema et structuredContent de JSON Schema 2020-12, avec des possibilités plus larges pour les références, les compositions et les résultats non objets. Il s’agit d’une proposition, pas d’une preuve que tous les clients existants acceptent déjà ces formes. (modelcontextprotocol.io)

La compatibilité entre fournisseurs

Une définition interne peut contenir des références, des unions, des contraintes conditionnelles ou des propriétés supplémentaires. Une API de modèle peut n’en accepter qu’une sélection. Nous recommandons d’éviter la stratégie « un fichier unique envoyé partout ».

Comparaison décisionnelle

Schéma principal interne — note : 5/5

• conserve la sémantique métier complète ;
• sert de référence pour les tests ;
• peut utiliser $defs, $ref, des règles documentées et des exemples ;
• ne doit pas être transmis automatiquement à chaque fournisseur.

Version OpenAI — note : 4/5

• adaptée à json_schema et au mode strict ;
• nécessite une réduction des mots-clés non pris en charge ;
• doit être testée avec le modèle et l’interface réellement utilisés ;
• convient aux réponses structurées et aux paramètres de fonctions.

Version Gemini — note : 4/5

• construite à partir de la liste officielle des propriétés acceptées ;
• permet des objets, tableaux, énumérations, références et contraintes sélectionnées ;
• exige une attention particulière aux références cycliques et aux propriétés non standard ;
• convient aux sorties analytiques, créatives et multimédias structurées.

Version Claude — note : 3/5

• efficace pour décrire les arguments d’outils ;
• dépend fortement de la qualité des descriptions ;
• ne doit pas être considérée comme une validation métier ;
• doit être vérifiée avec l’API et le modèle ciblés. (docs.anthropic.com)

Version MCP — note : 4/5

• pertinente pour l’exposition d’outils et la circulation des résultats ;
• associe inputSchema à l’entrée et outputSchema à la sortie ;
• dépend de la compatibilité du client et du serveur ;
• ne choisit pas l’outil à la place du modèle. (modelcontextprotocol.io)

La note n’est pas une mesure de qualité des fournisseurs. Elle indique seulement l’effort d’adaptation requis pour un contrat partagé.

La validation métier

JSON Schema ne doit pas porter seul la confiance de votre application. Nous séparons habituellement trois niveaux.

Niveau syntaxique. Le parseur accepte le document.

Niveau structurel. Le document respecte le schéma : champs obligatoires, types, énumérations, tableaux et contraintes déclarées.

Niveau métier. Les valeurs sont compatibles avec l’état réel du système.

Exemples :

• une date respecte le format attendu, mais elle peut être impossible dans votre calendrier ;
• un montant est un nombre positif, mais il peut dépasser le plafond du compte ;
• un identifiant de client a la bonne forme, mais il peut appartenir à une autre organisation ;
• un statut figure dans l’énumération, mais la transition demandée peut être interdite ;
• un chemin de fichier est une chaîne valide, mais il peut sortir du répertoire autorisé.

La validation métier doit être exécutée après la validation JSON Schema et avant l’action externe. Pour une plateforme audio ou vidéo, cette étape peut vérifier l’existence du média, les droits du projet, la durée réelle d’une piste et la capacité du moteur de rendu. Pour un outil de design, elle peut contrôler les formats disponibles, l’espace de stockage et les limites du service d’export.

FAQ technique

JSON et JSON Schema

JSON transporte les données. JSON Schema décrit les données attendues et leurs contraintes. Un parseur peut accepter un objet JSON que votre schéma ou votre logique métier rejettera ensuite.

Outils et modèles

Les modèles utilisent les schémas pour produire des arguments plus prévisibles. L’exécuteur doit toujours revérifier ces arguments, car le schéma ne remplace ni les permissions ni l’accès aux données réelles.

Compatibilité complète

OpenAI, Gemini et Claude ne garantissent pas une prise en charge universelle de tous les dialectes et mots-clés. La bonne méthode consiste à tester une version adaptée à chaque interface.

MCP

MCP utilise inputSchema pour les paramètres et peut utiliser outputSchema avec structuredContent pour les résultats. Le protocole organise l’exposition et l’appel des outils, sans imposer la décision du modèle.

Réutilisation

Une définition principale est utile, mais son envoi direct partout est fragile. Les variantes doivent être générées, versionnées, testées et associées à un fournisseur, une interface et une version de modèle.

La gouvernance en production

Un schéma devient un composant logiciel dès qu’il est partagé par plusieurs équipes. Nous recommandons une gouvernance minimale.

Nommer les contrats. Utilisez des noms explicites comme media-analysis-result ou order-action-input, plutôt qu’un fichier générique appelé response.json.

Versionner les changements. L’ajout d’un champ optionnel est généralement moins risqué que le changement d’un type, la suppression d’une propriété ou la modification d’une énumération. Chaque transformation fournisseur doit également posséder sa version.

Conserver des exemples. Un schéma sans exemples laisse trop de place aux interprétations. Ajoutez un cas nominal, un cas minimal, un cas refusé et un cas de compatibilité ancienne.

Tester les sous-ensembles. Incluez au minimum des objets, tableaux, énumérations, références et propriétés supplémentaires. Enregistrez le dialecte, le modèle, l’API et la date de vérification. Les conclusions de compatibilité ne doivent pas être présentées comme éternelles.

Préparer le retour arrière. Si une plateforme modifie son sous-ensemble accepté, vous devez pouvoir revenir à la variante précédente sans réécrire le modèle interne.

Pour les équipes qui exécutent ces validations dans une chaîne macOS, l’automatisation peut inclure la génération des variantes, l’appel de plusieurs API, la validation locale et l’archivage des différences. Les contraintes contractuelles et opérationnelles doivent également être documentées avant de partager l’environnement entre plusieurs développeurs.

Le pipeline recommandé

Nous proposons une mise en œuvre en sept étapes.

1. Définir le contrat métier principal. Décrivez les données que votre application veut réellement recevoir, indépendamment de l’API choisie.

1. Séparer les couches. Placez dans JSON Schema les types, champs, énumérations et contraintes structurelles. Gardez les permissions, les recherches de ressources et les transitions d’état dans le code métier.

1. Créer les variantes fournisseurs. Supprimez ou transformez les mots-clés non pris en charge par l’interface ciblée. Ne modifiez pas silencieusement la sémantique : conservez une règle de conversion lisible.

1. Valider avant l’appel. Contrôlez les arguments produits par le modèle avant toute écriture, suppression, facturation ou exécution de commande.

1. Valider après l’outil. Si MCP ou votre propre protocole fournit un résultat structuré, vérifiez-le avant de le présenter au modèle ou à l’utilisateur.

1. Tester les cas négatifs. Simulez un champ manquant, une valeur inconnue, une référence inaccessible, un montant invalide et une transition interdite.

1. Automatiser la régression. Exécutez ces tests à chaque changement de schéma, d’API, de modèle ou d’adaptateur.

Nous déconseillons de considérer la réussite d’un seul appel comme une preuve de compatibilité. Un test utile doit comparer le schéma envoyé, la réponse reçue, l’erreur éventuelle et la décision de l’exécuteur.

Le choix d’une infrastructure d’exécution

Un pipeline de validation peut fonctionner sur un poste local, une machine virtuelle ou un nœud distant. Le poste local est souvent suffisant pour un développement ponctuel. Il devient moins pratique lorsque les tests doivent s’exécuter sur une chaîne macOS spécifique, avec des outils audio, vidéo, Xcode, des simulateurs ou des dépendances graphiques.

Une machine virtuelle générique présente alors plusieurs limites : accès matériel restreint, configuration macOS difficile à reproduire, intégration imparfaite avec les outils natifs et maintenance séparée des environnements. Les services cloud généralistes ajoutent parfois de la latence, des permissions complexes et des variations de disponibilité.

Une machine Mac distante apporte un environnement plus proche de la cible lorsque votre pipeline dépend réellement de macOS. Cela ne signifie pas qu’elle soit toujours le meilleur choix. Un besoin de charge lourde permanente peut justifier un achat ou une infrastructure dédiée. En revanche, pour une phase de test, une validation multi-modèles ou une intégration CI/CD temporaire, la location permet d’éviter un investissement matériel immédiat.

Si vous devez comparer plusieurs régions d’exécution, vous pouvez consulter les options de location de Mac dans la région est des États-Unis et vérifier ensuite la latence, les accès nécessaires et la durée prévue du projet.

Le point important reste l’ordre des décisions : d’abord le contrat JSON Schema, ensuite les adaptateurs, puis la régression automatisée, et seulement après le choix du nœud d’exécution.

Notre recommandation finale est donc pragmatique. Ne commencez pas par envoyer le même schéma complet à OpenAI, Gemini, Claude et MCP. Construisez un contrat principal, réduisez-le par fournisseur, testez les résultats et ajoutez la validation métier. Votre environnement actuel peut fonctionner, mais il impose souvent un poste dédié allumé, une configuration macOS difficile à partager et une maintenance manuelle des versions. Une solution Mac distante avec ZekVPS devient plus intéressante lorsque les tests doivent être répétés, accessibles à plusieurs développeurs ou intégrés à une chaîne de validation continue. Elle reste moins pertinente pour une charge stable et permanente ou pour un besoin nécessitant des interfaces physiques locales. Pour une campagne temporaire de tests Schema, d’intégration d’agents IA ou de CI/CD macOS, vous pouvez examiner les possibilités proposées par ZekVPS après avoir défini vos critères techniques.