Qu'est-ce que le JSON ? Syntaxe, erreurs courantes, validation

Le JSON (JavaScript Object Notation) est un format texte léger pour stocker et échanger des données structurées. Il se compose d'objets de paires clé/valeur, de tableaux ordonnés et d'une poignée de types de valeurs : chaînes, nombres, true, false et null. C'est le format par défaut des API web et de nombreux fichiers de configuration, car il est facile à lire pour les humains et simple à analyser pour tous les langages de programmation. Le JSON est strict : les clés et les chaînes exigent des guillemets doubles, et les virgules finales comme les commentaires sont interdits.

À quoi ressemble un fichier JSON

Le JSON est né de la syntaxe que JavaScript utilise pour les littéraux d'objet, mais il est indépendant de tout langage. Il est défini dans la RFC 8259 et dans la norme ECMA-404, et le résumé d'une page de json.org décrit toute la grammaire. Un document typique ressemble à ceci :

{
  "id": 1042,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "active": true,
  "score": 98.5,
  "manager": null,
  "roles": ["admin", "editor"],
  "address": {
    "city": "London",
    "postcode": "N1 9GU"
  }
}

Les espaces entre les éléments (espaces, tabulations et sauts de ligne) sont ignorés : les mêmes données peuvent donc tenir sur une seule ligne ou être aérées par une indentation. Le niveau supérieur d'un document JSON peut être n'importe quelle valeur, même si les API utilisent presque toujours un objet ou un tableau.

Les types de données JSON

Il n'existe pas de type date. Les dates s'écrivent généralement sous forme de chaînes au format ISO 8601, comme "2026-10-13T09:30:00Z", ou sous forme de nombres (timestamps Unix) ; notre Convertisseur de timestamp Unix passe de l'un à l'autre.

Nombres et précision

La norme JSON ne limite ni la taille ni la précision des nombres, mais les programmes qui lisent le JSON, eux, les limitent. JavaScript stocke les nombres sous forme de valeurs à virgule flottante sur 64 bits : les entiers supérieurs à 9 007 199 254 740 991 (2⁵³ − 1) peuvent donc perdre de la précision sans prévenir. Pour les identifiants très grands, de nombreuses API les envoient sous forme de chaînes, par exemple "id": "1234567890123456789".

Les règles qui piègent le plus souvent

Le JSON ressemble à du JavaScript, aux dictionnaires Python et au YAML, et c'est justement pour cela qu'on écrit du JSON invalide sans le vouloir. Ces règles ne souffrent aucune exception dans le JSON standard :

• Les clés doivent être des chaînes entre guillemets doubles. {name: "Ada"} est du JavaScript valide mais du JSON invalide ; écrivez {"name": "Ada"}.
• Uniquement des guillemets doubles. 'Ada' n'est pas une chaîne JSON.
• Pas de virgule finale. [1, 2, 3,] et {"a": 1,} sont invalides.
• Pas de commentaires. Ni // ... ni /* ... */ ne sont autorisés.
• Les valeurs littérales sont en minuscules. True, FALSE et None (l'écriture de Python) sont invalides ; utilisez true, false et null.
• Pas de undefined, de fonctions ni de nombres spéciaux. Ils existent en JavaScript mais n'ont aucun équivalent en JSON.
• Les clés devraient être uniques. La norme indique que les noms d'un objet devraient être uniques ; en cas de doublons, les analyseurs se comportent différemment, et beaucoup ne gardent silencieusement que le dernier.

Certains outils acceptent des variantes assouplies. Des fichiers comme le settings.json de VS Code et le tsconfig.json de TypeScript sont lus par des analyseurs qui autorisent les commentaires (souvent appelés JSONC), et le JSON5 autorise les commentaires, les guillemets simples et les virgules finales. Ce sont des formats distincts : un analyseur JSON standard, y compris celui qu'utilisent votre client d'API ou votre serveur, les rejettera.

Erreurs JSON courantes et comment les corriger

Le libellé des erreurs varie selon les analyseurs. Le tableau montre le type de message que vous verrez avec le module json de Python ou le JSON.parse d'un navigateur, ce qu'il signifie généralement, et la correction. La position indiquée pointe souvent juste après la vraie erreur : regardez donc aussi le caractère qui la précède.

La dernière ligne est l'une des plus fréquentes en pratique : le code appelle JSON.parse ou response.json() sur une page d'erreur qui commence par <!DOCTYPE html>, et le < est signalé comme un jeton inattendu.

JSON, YAML ou XML : quelles différences ?

YAML 1.2 a été conçu pour que les documents JSON soient, à de rares cas limites près, aussi des documents YAML valides, ce qui rend la conversion de l'un à l'autre simple. Notre Convertisseur JSON ↔ YAML gère les deux sens, le Formateur et validateur YAML et le Formateur et validateur XML valident les deux autres formats, et le Convertisseur CSV ↔ JSON transforme les exports de tableur en tableaux d'objets.

Mettre en forme ou minifier du JSON

Comme les espaces ne sont pas significatifs, un même JSON peut être mis en forme pour les humains ou pour les machines :

• Le JSON mis en forme (pretty-printed) ajoute des sauts de ligne et une indentation, généralement de deux ou quatre espaces, pour que l'imbrication soit visible. Utilisez-le pour les fichiers de configuration, la documentation et le débogage.
• Le JSON minifié supprime tous les espaces facultatifs pour alléger les données. Utilisez-le pour les données envoyées sur le réseau ou stockées en masse ; la compression HTTP réduit aussi la taille, si bien que le gain est souvent modeste.

{"name":"Ada","roles":["admin","editor"],"active":true}

La plupart des langages savent faire les deux. En JavaScript, JSON.stringify(data, null, 2) met en forme avec une indentation de deux espaces et JSON.stringify(data) minifie. En Python, json.dumps(data, indent=2) met en forme et json.dumps(data, separators=(",", ":")) donne la sortie la plus compacte.

Comment valider du JSON

Valider du JSON comporte deux niveaux : le texte est-il du JSON syntaxiquement valide, et a-t-il la structure que votre application attend ?

1. Vérifiez la syntaxe avec un analyseur strict. Collez le texte dans notre Formateur et validateur JSON, qui indique la ligne et la colonne de la première erreur et fonctionne dans votre navigateur. En ligne de commande, python3 -m json.tool data.json ou jq . data.json affiche le document formaté ou une erreur.
2. Corrigez les erreurs une par une. Un analyseur s'arrête au premier problème : relancez-le après chaque correction jusqu'à ce qu'il réussisse.
3. Vérifiez la structure. Assurez-vous que les champs obligatoires existent et ont le bon type, soit dans le code, soit avec un validateur JSON Schema.
4. Vérifiez l'encodage. Le JSON échangé entre systèmes devrait être en UTF-8. Un fichier enregistré dans un autre encodage peut produire des caractères étranges ou des erreurs avec du texte non anglais.

JSON Schema en bref

JSON Schema est un vocabulaire, écrit en JSON lui-même, qui décrit à quoi ressemble un document valide : quelles propriétés sont obligatoires, de quel type doit être chacune, les valeurs autorisées, les motifs de chaînes, les plages numériques, etc. Il existe des validateurs pour la plupart des langages, et des formats de description d'API comme OpenAPI s'appuient sur JSON Schema pour décrire les corps de requête et de réponse. La spécification est publiée sur json-schema.org. Un petit exemple :

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": { "type": "array", "items": { "type": "string" } }
  }
}

Un document sans email, ou dont l'id est une chaîne, serait du JSON valide mais échouerait à ce schéma. Notez que de nombreux validateurs traitent format comme une simple annotation et ne l'appliquent que s'ils sont configurés pour le faire.

Questions fréquentes

Le JSON peut-il contenir des commentaires ?

Non. Le JSON standard n'autorise aucun commentaire, de quelque sorte que ce soit. Certains outils acceptent JSONC ou JSON5, qui en autorisent, mais les fichiers destinés à être lus par d'autres programmes devraient s'en tenir au JSON pur. Si vous avez besoin d'une note, ajoutez un champ comme "_comment".

Pourquoi le JSON n'accepte-t-il pas les virgules finales ?

La grammaire a été volontairement réduite au minimum et ne les prévoit tout simplement pas. De nombreux moteurs JavaScript et d'autres langages acceptent les virgules finales dans leur propre syntaxe, ce qui explique qu'elles se glissent souvent par erreur dans du JSON écrit à la main.

Quelle est la différence entre le JSON et un objet JavaScript ?

Le JSON est un format texte ; un objet JavaScript est une structure de données en mémoire. La syntaxe du JSON est un sous-ensemble plus strict de la syntaxe des littéraux JavaScript. On passe de l'un à l'autre avec JSON.parse et JSON.stringify.

Que signifie « Unexpected token < in JSON at position 0 » ?

Le texte analysé commence par <, ce qui signifie presque toujours que vous avez reçu du HTML, comme une page d'erreur ou de connexion, à la place du JSON. Vérifiez l'URL de la requête, le code de statut HTTP et le corps brut de la réponse.

L'ordre des clés d'un objet JSON est-il conservé ?

La norme considère les objets comme non ordonnés : il ne faut donc pas compter sur l'ordre des clés. En pratique, la plupart des analyseurs modernes conservent l'ordre de lecture, mais l'ordre des tableaux est le seul que le JSON garantisse.

Quelle extension de fichier et quel type MIME utilise le JSON ?

Les fichiers utilisent l'extension .json et le type de média est application/json, tel qu'enregistré dans la RFC 8259.