Sorties structurées en IA : définir, valider et déployer un contrat JSON

Une sortie structurée est un contrat, pas une garantie de vérité

Une sortie structurée est une réponse d’un système d’IA présentée selon une forme de données convenue, par exemple un objet JSON comprenant des champs, des types et des valeurs autorisées. Dans une application, ce contrat permet d’analyser le résultat et de le transmettre à du code en aval sans devoir extraire des informations d’un paragraphe en texte libre. Il ne rend pas, à lui seul, le contenu vrai, complet ou approprié à l’exécution d’une action.

Cette distinction est importante. Le texte « la demande concerne mardi » peut être correctement transformé en une chaîne contenant une date ; l’application doit toutefois encore savoir de quel mardi il s’agit, si la personne a bien fourni cette date et si le résultat est cohérent avec le reste de la demande. La structure définit la manière de représenter une réponse. La justesse des données dépend aussi de l’entrée, de la tâche et des règles métier.

Il est donc utile de distinguer trois vérifications : peut-on lire la réponse comme du JSON ? Respecte-t-elle le schéma convenu ? Ses valeurs sont-elles cohérentes et étayées par les informations disponibles ? Une réponse peut réussir la première vérification et échouer aux deux autres. Elle peut également respecter le schéma tout en constituant une extraction erronée.

Ce guide s’appuie sur l’extraction fictive de demandes de congés pour illustrer la conception. L’exemple est une proposition de mise en œuvre locale, et non une affirmation selon laquelle une API imposerait ce format. Les fonctionnalités précises de chaque fournisseur, les noms de paramètres, les modèles compatibles et les états d’erreur doivent être vérifiés dans la documentation en vigueur du service choisi.

Décider si une structure est nécessaire

Imposez une sortie structurée lorsque le résultat doit alimenter une interface, une recherche, une file de traitement, une règle automatisée ou une base de données, et lorsque l’ensemble des champs attendus peut être décrit de manière stable. Par exemple, une application de gestion des demandes peut avoir besoin d’un statut, d’un type de demande et de dates identifiées de façon cohérente. Dans ce cas, demander du texte libre puis extraire les champs ajoute une étape d’interprétation et multiplie les points de défaillance.

Ce n’est pas toujours nécessaire. Si une personne souhaite simplement une explication, une réponse conversationnelle peut être plus claire qu’un objet de données. Si une transformation déterministe suffit — normaliser des espaces ou convertir une date dont le format est déjà sans ambiguïté, par exemple —, une fonction classique peut être plus simple et plus reproductible que de demander au modèle de s’en charger. Et si les champs ne sont pas encore définis, formaliser un schéma trop tôt peut masquer une tâche mal conçue.

La décision doit également tenir compte du coût d’une erreur. Si une réponse déclenche un paiement, modifie des autorisations, supprime des informations ou influence une décision sensible, le schéma n’est qu’un élément parmi les mesures de contrôle. L’application peut avoir besoin d’une confirmation humaine, d’autorisations supplémentaires ou d’une règle interdisant l’action tant qu’une ambiguïté n’a pas été résolue. Il est imprudent de déléguer ces décisions à une prétendue fiabilité du format.

Avant de concevoir le contrat, indiquez qui consomme chaque champ et dans quel but. Si aucun composant n’utilise un champ, il n’a peut-être pas sa place dans la sortie. Si un composant exige une précision que l’entrée ne garantit pas, définissez un état d’incertitude ou une question de clarification au lieu d’obliger le modèle à inventer une valeur.

Définir un contrat adapté à la tâche

Un contrat utile décrit la forme de chaque champ et les conditions d’utilisation de celui-ci. Commencez par identifier les champs indispensables, leur attribuer des types et décider lesquels sont obligatoires. Précisez ensuite les valeurs autorisées, la représentation des données manquantes et les relations entre les champs. Enfin, distinguez ces règles des instructions rédigées à l’intention du modèle : l’application doit conserver une définition vérifiable, qui peut être testée sans dépendre de ce que le modèle semble avoir compris.

Pour extraire les informations d’une demande de congés, un contrat trop simple pourrait toujours exiger une date de début et une date de fin. Pourtant, une demande telle que « j’aimerais prendre quelques jours le mois prochain » ne permet pas de déterminer des dates exactes. Obliger le système à renseigner ces dates l’incite à deviner. Une autre approche consiste à expliciter les états possibles de la tâche : demande complète, clarification nécessaire ou texte qui ne correspond pas à une demande. Les dates peuvent alors être absentes lorsqu’elles sont inconnues, et une question peut préciser l’information manquante.

Le schéma ci-dessous illustre un choix possible. La condition selon laquelle la date de fin ne peut précéder la date de début, ainsi que les relations entre le statut et les champs facultatifs, doivent également être vérifiées dans l’application. Ne supposez pas qu’un mode de génération ou un validateur accepte tous les mots-clés présentés ici : le schéma local et le format accepté par l’API ne sont pas nécessairement interchangeables. Si l’interface distante n’accepte qu’un sous-ensemble de ces règles, adaptez la représentation transmise et conservez les vérifications complètes dans votre code.

La convention utilisée pour représenter l’absence doit être sans équivoque. Dans cet exemple, une date inconnue est représentée par null, et non par une chaîne vide, « inconnu » ou une date inventée. Une seule convention cohérente facilite la validation et évite que différents consommateurs interprètent le même cas de façons différentes. L’application doit aussi décider si elle accepte les champs supplémentaires ou les rejette ; les autoriser sans examen peut masquer une erreur de version ou une sortie inattendue.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["status", "start_date", "end_date", "clarification_question"],
  "properties": {
    "status": {
      "type": "string",
      "enum": ["complete", "needs_clarification", "not_a_request"]
    },
    "start_date": {
      "type": ["string", "null"],
      "description": "Date ISO YYYY-MM-DD, uniquement si la demande l'étaye"
    },
    "end_date": {
      "type": ["string", "null"],
      "description": "Date ISO YYYY-MM-DD, uniquement si la demande l'étaye"
    },
    "clarification_question": {
      "type": ["string", "null"]
    }
  }
}

Distinguer format, schéma et sens

La première validation consiste à vérifier si les octets reçus peuvent être interprétés comme du JSON. Si la réponse contient une virgule finale, du texte ajouté hors de l’objet ou un guillemet non fermé, l’analyse peut échouer. La deuxième consiste à vérifier si la valeur analysée a la forme autorisée : un objet, les clés attendues et des valeurs des types appropriés. La troisième consiste à déterminer si les informations représentent correctement la demande et respectent les règles de l’application.

Par exemple, l’objet ci-dessous pourrait être du JSON valide et respecter les types fondamentaux du contrat : status indique que la demande est complète, les deux dates sont des chaînes et aucune clarification n’est demandée. Pourtant, si la personne a demandé des congés « du 12 juin au 10 juin », la réponse est incohérente. De même, la période peut être cohérente en elle-même sans être étayée par le texte. Une vérification de types ne remplace pas la vérification de la correspondance avec l’entrée.

Les règles sémantiques doivent être formulées explicitement et, si possible, sous la forme de tests reproductibles. Pour cet exemple : si status est complete, les deux dates doivent être présentes et correspondre à des dates calendaires valides ; la date de fin ne peut pas précéder la date de début ; si status est needs_clarification, il faut préciser quelle information manque ; et si status est not_a_request, le processus de congés ne doit pas démarrer. La politique précise peut varier, mais ne devrait pas dépendre de l’interprétation implicite du consommateur.

Il faut également distinguer une réponse invalide d’une réponse valide indiquant que la tâche ne peut pas être accomplie. needs_clarification peut être une réponse conforme au contrat, et non une erreur technique. Si l’API signale un refus, une erreur de génération ou une interruption sous une forme qui lui est propre, l’application doit traiter cet état conformément à la documentation du fournisseur. Il ne faut pas transformer toutes ces situations en un objet apparemment normal sans savoir ce qui s’est passé.

Choisir un mode sans supposer la compatibilité

Certaines API proposent des options spécifiques pour demander des sorties structurées, mais leurs noms, exigences et limites dépendent du produit et peuvent évoluer. La documentation officielle d’Amazon Nova présente la demande de sortie structurée et des formats tels que JSON. La documentation d’Anthropic décrit les sorties structurées avec un schéma JSON et le paramètre output_config. Google documente les résultats structurés pour Gemini API et mentionne les schémas JSON. OpenAI présente sa fonctionnalité de sorties structurées dans son API. Ces références concernent des produits précis : elles ne prouvent pas que ceux-ci partagent le même contrat, le même degré de contrainte ou la même gestion des erreurs.

Microsoft Learn comporte également une page consacrée aux sorties structurées pour les modèles de conversation, dans une documentation identifiée comme étant celle de Foundry classique. Cette délimitation compte : une page associée à un produit ou à un mode donné ne doit pas être considérée comme une spécification universelle de tous les services Microsoft. De même, la documentation de Claude Code et celle de Claude Platform concernent des produits différents ; une option décrite pour l’un ne doit pas être transposée automatiquement à l’autre.

Avant de choisir, vérifiez dans la documentation officielle en vigueur quel mode est proposé, quels modèles ou versions il couvre, quelle partie du schéma est acceptée, ce qui est prévu pour les champs facultatifs et les énumérations, comment sont représentés les refus ou les générations incomplètes, et quelle structure de réponse l’application reçoit. Notez la date et la version de la documentation consultée. Si une exigence de votre contrat n’est pas spécifiée, considérez-la comme une incertitude et vérifiez-la par des tests dans l’environnement concerné, au lieu de la tenir pour garantie.

Ne confondez pas le fait de demander du JSON avec l’obligation de respecter un schéma. Un mode qui produit une réponse syntaxiquement valide en JSON peut simplifier l’analyse, mais l’application doit toujours vérifier les clés, les types et les règles liées à la tâche. Même si la documentation d’un mode décrit des contraintes de schéma, conservez une validation locale : le contrat qui protège le système consommateur doit être vérifié à la frontière de confiance de l’application.

Mettre en œuvre la validation dans l’application

L’application doit analyser la réponse à un point contrôlé et la valider avant de la transmettre au composant suivant. Une séquence pratique consiste à recevoir le résultat de l’API ; vérifier d’abord les états de transport et de génération documentés ; extraire le contenu pertinent ; analyser le JSON ; vérifier que la racine est un objet contenant les clés autorisées ; valider les types et les valeurs ; puis appliquer les règles métier. Si une étape échoue, le flux doit conserver suffisamment d’informations pour diagnostiquer le problème, sans agir comme si le résultat était correct.

L’exemple ci-dessous est un code Python exécutable avec la bibliothèque standard. Il attend une chaîne JSON, n’autorise que quatre clés, vérifie les types, interprète les dates au format ISO et applique des relations entre le statut, les dates et la question. Il ne vérifie pas que la date figurait réellement dans le texte d’entrée : cela nécessite de conserver le texte, de définir une stratégie de vérification des éléments probants et de la tester séparément. Il ne remplace pas non plus la gestion des erreurs de l’API, qui doit être adaptée au service utilisé.

L’exemple rejette délibérément les champs supplémentaires. Cette politique évite qu’un changement inattendu passe inaperçu, même si un système dont l’évolution est contrôlée peut choisir une autre règle. L’important est de prendre cette décision explicitement et de versionner le contrat. Si une bibliothèque de validation externe est utilisée en production, fixez une version compatible, testez ses règles et traitez les erreurs du validateur comme faisant partie de l’interface interne, non comme une raison de contourner la vérification.

Ne transformez pas silencieusement une erreur en valeur par défaut. Si end_date manque, la remplacer par start_date peut changer le sens de la demande. Si une date est invalide, la traiter comme null peut effacer un signal d’échec utile. Il est préférable de renvoyer un résultat de validation typé — valide, clarification nécessaire ou invalide — puis de décider explicitement s’il faut réessayer, interroger la personne ou demander une révision.

import json
from datetime import date

REQUIRED = {
    "status",
    "start_date",
    "end_date",
    "clarification_question",
}
STATUSES = {"complete", "needs_clarification", "not_a_request"}


def validate(raw):
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as exc:
        raise ValueError("JSON invalide") from exc

    if not isinstance(data, dict) or set(data) != REQUIRED:
        raise ValueError("Objet avec des clés manquantes ou inattendues")
    if data["status"] not in STATUSES:
        raise ValueError("Statut non autorisé")

    for key in ("start_date", "end_date", "clarification_question"):
        value = data[key]
        if value is not None and not isinstance(value, str):
            raise ValueError(f"Type incorrect : {key}")

    dates = []
    for key in ("start_date", "end_date"):
        value = data[key]
        if value is None:
            dates.append(None)
            continue
        parsed = date.fromisoformat(value)
        if parsed.isoformat() != value:
            raise ValueError(f"Format de date incorrect : {key}")
        dates.append(parsed)

    start, end = dates
    if data["status"] == "complete":
        if start is None or end is None or end < start:
            raise ValueError("Intervalle complet absent ou incohérent")
        if data["clarification_question"] is not None:
            raise ValueError("Une demande complète ne doit pas demander de clarification")
    elif data["status"] == "needs_clarification":
        if not data["clarification_question"]:
            raise ValueError("Précisez l’information à clarifier")
    elif data["status"] == "not_a_request":
        if start is not None or end is not None:
            raise ValueError("Un texte sans rapport avec la demande ne doit pas inclure de dates")

    return data


if __name__ == "__main__":
    sample = '{"status":"complete","start_date":"2027-06-12","end_date":"2027-06-14","clarification_question":null}'
    print(validate(sample))

Définir la réponse à apporter à chaque erreur

Une politique de gestion des erreurs utile distingue au moins quatre catégories de situations. Premièrement, les erreurs de transport ou de service : aucune réponse exploitable n’a été obtenue. Deuxièmement, les erreurs de génération ou les refus : l’API peut signaler qu’elle n’a pas produit le résultat demandé. Troisièmement, les erreurs de format ou de schéma : le contenu ne peut pas être analysé ou ne respecte pas le contrat. Quatrièmement, les erreurs sémantiques : la forme passe les vérifications, mais le contenu est incomplet, contradictoire ou non étayé.

Chaque catégorie nécessite un résultat explicite. Une erreur temporaire documentée peut autoriser un nombre limité de nouvelles tentatives ; répéter une demande ambiguë ne crée pas les informations absentes de l’entrée. Un échec de schéma peut justifier une nouvelle tentative avec des instructions plus claires, uniquement si le nombre de tentatives est limité et si la réponse est à nouveau validée. Une incohérence sémantique peut nécessiter une question à la personne ou une révision humaine. Un refus doit être affiché ou traité conformément à la politique du produit et aux détails documentés par le fournisseur.

Fixez des limites pour éviter les boucles de nouvelles tentatives et évitez de réparer automatiquement des valeurs d’une manière qui en changerait le sens. Si une nouvelle tentative produit une sortie différente, ne choisissez pas silencieusement celle qui paraît la plus commode. Conservez l’état de validation, la version du contrat et la catégorie de la cause. Pour les opérations ayant des conséquences, envisagez une étape de confirmation avant l’exécution effective.

Les journaux techniques doivent permettre de diagnostiquer les problèmes en exposant le moins de données possible. Conservez les identifiants de corrélation, la version du contrat, la catégorie de l’erreur et les mesures nécessaires. Évaluez s’il est indispensable de conserver le texte d’entrée ou la sortie complète ; si ce n’est pas le cas, ne les journalisez pas par défaut. Si vous les conservez, définissez les accès, la durée de conservation et le traitement appropriés à leur sensibilité.

Tester des entrées réelles et des cas limites

Les tests doivent vérifier le comportement, et pas seulement la possibilité d’analyser la réponse d’exemple. Préparez un petit ensemble maintenable d’entrées représentatives, de résultats attendus et de règles à respecter. Incluez des cas ordinaires, ambigus, incomplets, contradictoires et sans rapport avec la tâche. Pour chaque cas, testez à la fois la sortie jugée acceptable et la décision que l’application prend après l’avoir reçue.

Pour une demande de congés, une entrée claire peut demander des dates complètes dans une période cohérente. Un cas ambigu peut contenir « vendredi » sans contexte temporel suffisant. Une autre demande peut mentionner des dates, mais omettre l’année. Un cas incomplet peut ne pas préciser la date de fin. Testez également une période inversée, une date impossible, un type incorrect, une clé supplémentaire et une réponse qui n’est pas du JSON. Pour chaque cas, décidez si l’application accepte, demande une clarification ou rejette ; ne laissez pas cette décision à une interprétation improvisée lors de l’intégration.

Incluez des tests sémantiques avec des sorties préparées, en plus des tests avec le modèle. Si vous ne testez que des générations réelles, les résultats peuvent varier et il devient difficile de déterminer si l’échec vient de la génération, du contrat ou du code consommateur. Les tests déterministes du validateur permettent de vérifier des cas précis ; les tests d’intégration observent le comportement du flux complet avec l’API et la configuration qui seront réellement déployées.

Lors d’une modification du schéma, ajoutez des tests de compatibilité entre les versions. Si un consommateur attend un champ qui disparaît, un changement apparemment mineur peut interrompre le traitement. Versionnez le contrat et décidez comment déployer le producteur et le consommateur : par exemple, en prévoyant une période de transition durant laquelle les deux versions sont acceptées, ou en coordonnant le changement. Ne présentez pas une modification de nom ou de nullabilité comme un simple ajustement cosmétique.

Déployer et maintenir le contrat

Un contrat déployé nécessite un responsable, une version et un processus de modification. Conservez sa définition à côté du code qui le valide et consignez la version utilisée pour chaque résultat traité. Avant de modifier des champs, des types, des énumérations ou des règles relatives aux valeurs absentes, évaluez les effets sur les consommateurs et ajoutez des tests de régression ciblés. Si le modèle, le prompt, la configuration ou l’API change, relancez les tests pertinents : le contrat ne remplace pas la vérification du comportement du système complet.

Mesurez séparément la proportion de réponses analysables, celle qui respecte le schéma, celle qui passe les règles sémantiques et celle qui nécessite une clarification ou une révision. Un indicateur unique de « réussite » masque des différences importantes. Par exemple, savoir que presque toutes les réponses sont du JSON valide ne permet pas de savoir si les dates extraites correspondent aux demandes. Les métriques doivent avoir des définitions stables et éviter de recueillir du contenu sensible lorsqu’une catégorie agrégée suffit.

Surveillez l’évolution de la documentation et des versions des fournisseurs, mais ne supposez pas qu’une mise à jour conserve exactement les capacités de la configuration précédente. Consignez la combinaison testée et vérifiez les conditions de compatibilité avant de la modifier. La documentation d’un service fait référence à ce service et au périmètre qu’elle décrit ; elle ne certifie pas un comportement identique pour un autre produit, une autre version ou un autre modèle.

Si le système prend une décision lourde de conséquences, ajoutez une barrière proportionnée au risque. Il peut s’agir d’une révision humaine, d’une confirmation explicite ou d’une vérification indépendante. Prévoyez aussi une voie de récupération : que faire des résultats en attente, comment corriger une donnée validée mais erronée, et comment éviter d’exécuter deux fois une action après une nouvelle tentative. Le contrat de données fait partie d’un processus opérationnel ; il ne remplace pas ses contrôles.

Critères pratiques pour finaliser la conception

Avant de considérer le travail terminé, vérifiez que la structure répond à un véritable besoin du produit et ne reflète pas seulement une préférence pour recevoir du JSON. Le contrat doit être suffisamment réduit pour que chaque champ ait une fonction claire, tout en étant assez expressif pour représenter l’incertitude, l’absence de données et les résultats sans rapport avec la tâche. Si les cas ambigus ne peuvent pas être représentés de manière sûre, le contrat n’est pas encore prêt pour la production.

Assurez-vous que le consommateur valide la réponse reçue, et pas uniquement les instructions envoyées. Vérifiez séparément le format, les clés, les types et les règles sémantiques. Définissez ce qui doit être bloqué, ce qui peut faire l’objet d’une nouvelle tentative et ce qui nécessite une question. Testez ces décisions avec des exemples vérifiables, notamment une entrée qui manque d’informations et une sortie qui semble valide mais contredit le texte.

Enfin, consignez les incertitudes externes : compatibilité précise de l’API, limites du schéma, couverture des modèles et forme des erreurs. Résolvez-les en consultant la documentation officielle du produit et en testant la version prévue pour le déploiement. Le contrat local pourra ainsi rester une frontière de sécurité et de maintenance, même si le mode de génération évolue.

Poursuivre l’exploration

Corrections et transparence

Si vous repérez une information incorrecte ou obsolète, envoyez-nous la page et la source à vérifier.