Accueil › Glossaire › JSON Mode

JSON Mode

Le JSON mode est une fonctionnalité d’API qui contraint un LLM à ne générer que du JSON syntaxiquement valide, c’est-à-dire parsable par JSON.parse() ou json.loads(), sans garantir la conformité à un schéma spécifique.

Comment fonctionne le JSON mode

Le JSON mode agit comme une contrainte de génération côté serveur. Quand il est activé, le LLM est contraint de ne produire que des séquences de tokens qui forment du JSON syntaxiquement valide. Concrètement, le modèle ne peut pas générer de texte libre, de blocs Markdown, de préambules conversationnels, ni de JSON malformé (accolades manquantes, virgules en trop, guillemets non fermés).

Le mécanisme exact varie selon les providers, mais le principe est le même : pendant la génération, les tokens qui rendraient la sortie invalide en tant que JSON sont exclus des candidats possibles. C’est une contrainte sur le décodage, pas une simple instruction dans le prompt.

# OpenAI JSON Mode
from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "Analyse le sentiment du texte et réponds en JSON."},
        {"role": "user", "content": "Ce restaurant est incroyable, la meilleure expérience de ma vie !"}
    ],
    response_format={"type": "json_object"}
)

import json
data = json.loads(response.choices[0].message.content)
# Garanti parsable, mais les champs peuvent varier

JSON mode vs Structured outputs : la différence clé

Cette distinction est la plus importante à comprendre pour choisir la bonne approche :

En résumé : le JSON mode est un filet de sécurité qui évite les réponses textuelles quand vous avez besoin de JSON. Les structured outputs sont un contrat formel qui garantit la structure exacte de la sortie. Pour toute application de production, préférez les structured outputs quand ils sont disponibles.

Implémentation par provider

OpenAI

Chez OpenAI, le JSON mode se configure via response_format: {"type": "json_object"}. Il est disponible sur GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo et les modèles plus récents. OpenAI exige que le mot « JSON » apparaisse quelque part dans le system prompt ou le user prompt, sinon l’API retourne une erreur. Pour les applications nécessitant un schéma strict, OpenAI recommande les structured outputs ("type": "json_schema") plutôt que le JSON mode.

Mistral

L’API Mistral supporte le JSON mode via response_format: {"type": "json_object"}, avec une syntaxe identique à OpenAI. Le JSON mode de Mistral garantit un JSON valide mais ne contraint pas le schéma. La validation côté client (Pydantic, JSON Schema) est recommandée.

Groq

Groq propose le JSON mode sur les modèles open source qu’il héberge (Llama, Mixtral, Gemma, Qwen). La syntaxe est compatible OpenAI. Attention : Groq est plus strict que d’autres providers sur les structured outputs et peut retourner des erreurs 400 si le schéma n’est pas parfaitement formaté (notamment tous les champs dans required).

Anthropic

Anthropic n’a pas de « JSON mode » au sens strict (pas de paramètre response_format: {"type": "json_object"}). À la place, Anthropic propose directement les structured outputs via output_config: {"format": {"type": "json_schema", "schema": {...}}} sur Claude Opus 4.6 et Sonnet 4.6. Pour les modèles plus anciens ou quand vous n’avez pas besoin d’un schéma strict, l’approche recommandée est le tool use comme workaround ou le prefilling de l’assistant message avec {.

Google Gemini

Gemini supporte le JSON mode via response_mime_type: "application/json" dans generation_config. Pour la conformité au schéma, ajoutez un response_schema. Sans schéma, Gemini garantit du JSON valide mais avec une structure libre.

Quand utiliser le JSON mode

Le JSON mode reste pertinent dans plusieurs scénarios, malgré la disponibilité croissante des structured outputs :

Prototypage rapide. Quand vous explorez une tâche et ne savez pas encore quel schéma sera optimal, le JSON mode vous donne du JSON parsable sans avoir à définir un schéma formel. Vous pouvez itérer sur le prompt et observer quelles clés le modèle choisit naturellement, puis formaliser le schéma une fois satisfait.

Providers sans structured outputs. Tous les providers ne supportent pas les structured outputs avec schéma. Mistral, Groq, DeepSeek et d’autres providers compatibles OpenAI proposent le JSON mode mais pas nécessairement les structured outputs. Le JSON mode est alors la meilleure option disponible, complétée par une validation côté client.

Tâches à schéma variable. Si le format de sortie doit varier selon le contenu d’entrée (le modèle peut retourner 3 ou 7 champs selon le document), le JSON mode offre cette flexibilité. Les structured outputs imposent un schéma fixe, ce qui peut être contraignant pour les tâches exploratoires.

Réduction de la verbosité. Quand vous voulez simplement éviter que le modèle enrobe sa réponse JSON dans du texte narratif (« Voici le JSON que vous avez demandé : « `json … « ` J’espère que cela vous aide ! »), le JSON mode suffit. Pas besoin de définir un schéma complet pour ce cas simple.

Pièges courants

Le faux sentiment de sécurité

Le piège le plus fréquent : supposer que le JSON mode garantit un schéma stable. Votre code fait data["sentiment"] en confiance, et un jour le modèle retourne {"analysis": "positif"} au lieu de {"sentiment": "positif"}. Résultat : KeyError en production. Ajoutez toujours une validation côté client, même en JSON mode.

Troncation et JSON invalide

Si le modèle atteint la limite de max_tokens pendant la génération d’un objet JSON, la sortie est tronquée et le JSON résultant est invalide (accolade fermante manquante). Le JSON mode ne peut pas prévenir ce cas. Vérifiez toujours le stop_reason : si c’est max_tokens au lieu de end_turn/stop, le JSON est probablement tronqué.

Oublier de mentionner « JSON »

Chez OpenAI, le JSON mode échoue avec une erreur si le mot « JSON » n’apparaît nulle part dans les messages. C’est une sécurité pour éviter l’activation accidentelle du mode. Assurez-vous que votre system prompt ou user prompt contient explicitement une référence au format JSON.

Objets vs tableaux

Certaines implémentations de JSON mode ne produisent que des objets ({...}), pas des tableaux ([...]). Si vous avez besoin d’un tableau JSON en racine, testez avec votre provider spécifique. Les structured outputs gèrent ce cas plus fiablement.

Alternatives au JSON mode

Bonnes pratiques

Si vous utilisez le JSON mode en production, ajoutez systématiquement une validation côté client avec Pydantic (Python) ou Zod (TypeScript). Définissez un modèle de données qui décrit les champs attendus, leurs types et leurs contraintes. Si la réponse JSON ne passe pas la validation, loguez l’erreur et réessayez la requête (avec retry et backoff exponentiel). Fixez le max_tokens suffisamment haut pour que la réponse JSON ne soit pas tronquée. Incluez toujours le mot « JSON » dans le prompt (requis par certains providers). Pour les applications critiques, migrez vers les structured outputs dès que votre provider les supporte.

Si vous travaillez avec plusieurs providers (OpenAI + Anthropic + Mistral), une bibliothèque comme Instructor ou LiteLLM abstrait les différences d’implémentation du JSON mode et des structured outputs. Vous définissez un modèle Pydantic unique, et la bibliothèque se charge de l’adapter au format natif de chaque provider (response_format chez OpenAI, tool use chez Anthropic, response_schema chez Gemini).

Impact sur les coûts et la performance

Le JSON mode a un impact mineur sur la latence par rapport à la génération libre. La contrainte de décodage est légère (elle filtre les tokens invalides du vocabulaire), et les providers modernes l’optimisent bien. En termes de tokens, le JSON est plus verbeux que le texte naturel : les guillemets, les accolades, les deux-points et les virgules consomment des tokens supplémentaires. Un résultat de classification qui tiendrait en un mot coûte 5 à 10× plus en tokens quand il est encapsulé en JSON.

Pour les applications à très fort volume en single-turn batch, cette surcharge est significative. Sur 100 000 requêtes quotidiennes avec un surcoût moyen de 50 tokens par réponse due au formatage JSON, c’est 5 millions de tokens de sortie supplémentaires par jour. Sur Claude Opus 4.6 ($25/M tokens output), cela représente $125/jour de surcoût. Sur Claude Haiku 4.5 ($5/M), c’est $25/jour. Choisissez le format le plus léger qui satisfait vos besoins : si un simple label suffit, ne demandez pas un objet JSON complet avec métadonnées.

Historique du JSON mode

Le JSON mode a été introduit par OpenAI en novembre 2023 avec GPT-4 Turbo. À l’époque, c’était une avancée significative : avant cela, obtenir du JSON fiable d’un LLM reposait entièrement sur le prompt engineering et les retries. Le JSON mode a rapidement été adopté par d’autres providers (Mistral, Groq, Together AI) car la syntaxe response_format: {"type": "json_object"} est simple à implémenter.

En août 2024, OpenAI a lancé les structured outputs (JSON Schema mode), une évolution qui ajoute la conformité au schéma. Anthropic a suivi en novembre 2025 avec ses propres structured outputs pour Claude Sonnet 4.5 et Opus 4.1, puis les a étendus à Claude Opus 4.6 et Sonnet 4.6. Google Gemini supportait déjà les response_schema avant cela.

Le JSON mode n’est pas obsolète pour autant. Il reste la solution la plus largement disponible à travers les providers, et sa simplicité d’utilisation en fait un bon point d’entrée pour les développeurs qui débutent avec les sorties structurées. Mais pour les nouvelles applications de production, les structured outputs sont la voie recommandée.

JSON mode avec les modèles locaux

Les modèles hébergés localement via Ollama, vLLM ou d’autres runtimes supportent aussi le JSON mode. Ollama propose un paramètre format: "json" qui contraint la génération. vLLM supporte guided_json avec un schéma JSON optionnel, offrant un niveau de contrôle proche des structured outputs cloud.

Pour les modèles locaux, des bibliothèques comme Outlines et Guidance appliquent des contraintes de grammaire pendant le décodage, garantissant la conformité à un schéma JSON arbitraire sans dépendre d’une fonctionnalité API. C’est l’équivalent local des structured outputs cloud, et cela fonctionne avec n’importe quel modèle compatible (Llama, Mistral, Qwen, etc.).

L’avantage des modèles locaux pour le JSON mode est l’absence de coût par token et le contrôle total sur la configuration. L’inconvénient est la qualité de génération : les modèles plus petits (7B, 14B paramètres) produisent des JSON structurellement corrects mais avec un contenu de moindre qualité que les modèles frontier cloud. Le choix dépend de votre budget et de vos exigences de qualité.

Verdict

Le JSON mode est un filet de sécurité utile, pas une solution complète. Il garantit que la sortie du modèle est du JSON parsable, ce qui élimine les erreurs de parsing les plus grossières. Mais il ne garantit pas la structure, les types, ni la présence des champs attendus. Pour toute application de production sérieuse, les structured outputs (JSON Schema natif) sont la bonne réponse. Le JSON mode reste pertinent pour le prototypage, les providers qui n’offrent pas de structured outputs, et les cas où la flexibilité du schéma est un avantage. Quelle que soit l’approche choisie, validez toujours côté client.