Qu'est-ce qu'un Document JSON ?

Qu'est-ce qu'un document JSON ?

Un document JSON est un fichier texte ou un message écrit en JavaScript Object Notation : un petit format lisible pour des données structurées, composé d'objets, de tableaux, de chaînes, de nombres, de booléens et de null. Les API, les fichiers de configuration et les bases documentaires l'utilisent parce que tous les langages courants savent l'analyser. Le format est défini dans la RFC 8259 et dans ECMA-404. Pour un premier tour de la syntaxe, voyez JSON : guide pour débutants.

Les types de valeur

Selon la RFC 8259, une valeur JSON doit être un objet, un tableau, un nombre ou une chaîne, ou l'un des trois noms littéraux true, false et null.

• Objet : { "key": value }, un ensemble de paires nom-valeur. Les noms sont toujours des chaînes.
• Tableau : [ value, value ], une liste ordonnée.
• Chaîne : "hello", du texte entre guillemets doubles.
• Nombre : 42, 3.14, 1e10. Le format ne distingue pas les entiers des décimaux.
• Booléen : true ou false, en minuscules et sans guillemets.
• Null : null, l'absence explicite de valeur.

Il n'y a ni type date, ni type binaire, ni syntaxe de commentaire. Les dates et les données binaires circulent sous forme de chaînes, par convention.

Un exemple

{
  "id": "order_42",
  "customer": { "name": "Alice", "verified": true },
  "items": [
    { "sku": "WIDGET-1", "qty": 2, "price": 9.99 },
    { "sku": "GIZMO-7", "qty": 1, "price": 19.95 }
  ],
  "shipped_at": null,
  "tags": ["priority", "gift"]
}

Chaque valeur est de l'un des types ci-dessus, et les objets et tableaux s'imbriquent aussi profondément que nécessaire. Le même texte donne la même structure dans n'importe quel langage.

Où l'on rencontre des documents JSON

• API : corps de requête et de réponse, généralement avec le type de média application/json. Voyez payload d'une API et, pour le style d'appel distant qui enveloppe ses messages en JSON, JSON-RPC.
• Configuration : package.json et tsconfig.json sont des exemples courants.
• Bases documentaires : MongoDB, Firestore et DynamoDB travaillent avec des données en forme de document.
• Logs : la journalisation structurée écrit un objet JSON par ligne.
• Données structurées pour la recherche : JSON-LD intègre des données schema.org dans une page web.

Erreurs qui invalident un JSON

• Virgules finales. {"a":1,} est invalide. JavaScript le tolère, pas JSON.
• Commentaires. JSON n'en a pas. Des formats comme JSON5 et JSONC en ajoutent, mais un analyseur strict les refuse.
• Guillemets simples ou noms sans guillemets. Les noms et les chaînes exigent des guillemets doubles.
• Grands entiers. La RFC 8259 note que les logiciels utilisent couramment des nombres IEEE 754 en double précision, et JSON.parse de JavaScript aussi, si bien que les entiers au-delà de 2^53 - 1 (9007199254740991) peuvent perdre en précision. Envoyez les identifiants 64 bits sous forme de chaînes.
• Noms en double. La RFC indique que les noms d'un objet devraient être uniques, sinon le comportement est imprévisible.
• Mauvais encodage. Selon la RFC, le texte JSON échangé entre systèmes doit être en UTF-8.

JSON face aux autres formats

• YAML s'écrit plus facilement à la main et admet les commentaires, d'où son usage dans les fichiers CI et Kubernetes. Il est aussi sensible à l'indentation.
• XML convient au balisage de documents et aux anciens systèmes d'entreprise, au prix d'une syntaxe plus verbeuse.
• Protocol Buffers est binaire et exige un schéma, ce qui convient aux RPC à fort volume mais se lit moins bien.

Pour décrire ce qu'est un document valide, on utilise JSON Schema. Le blog LoadFocus l'explique dans what is JSON Schema.

Tester des endpoints JSON

Un endpoint JSON peut répondre 200 avec un mauvais corps. La surveillance d'API LoadFocus vérifie à intervalle régulier le code de statut, le corps, les en-têtes et le temps de réponse, et cite la conformité à un schéma JSON comme exemple de contrôle. Les contrôles gratuits tournent toutes les 5 minutes. Pour voir comment un endpoint se comporte avec beaucoup d'appelants simultanés, faites un test de charge d'API. Plus de détails dans surveillance d'API.

Questions fréquentes : documents JSON

Quelle différence entre JSON et un objet JavaScript ?

JSON est du texte. Un objet JavaScript est une valeur en mémoire. JSON est plus strict : les noms et les chaînes exigent des guillemets doubles, et il ne peut contenir ni fonctions, ni undefined, ni commentaires. JSON.parse transforme le texte en objet.

Comment valider un document JSON ?

Passez-le dans un analyseur. En ligne de commande, jq . file.json affiche le document ou la première erreur de syntaxe. Pour vérifier aussi la structure, validez avec un JSON Schema.

Quelle taille peut avoir un document JSON ?

Le format ne fixe aucune limite. Les limites viennent de l'analyseur, qui peut charger tout le document en mémoire, et des serveurs et passerelles intermédiaires. Pour de très gros volumes, envoyez un objet JSON par ligne (NDJSON) ou utilisez un format binaire.

Comment stocker une date en JSON ?

JSON n'a pas de type date. L'usage est une chaîne ISO 8601 comme "2026-05-07T08:22:00Z". Les deux côtés doivent s'accorder dessus.

Faut-il choisir JSON ou YAML pour la configuration ?

JSON pour les fichiers générés par des outils. YAML pour ceux que l'on édite à la main et où les commentaires comptent. Beaucoup d'écosystèmes ont une convention, suivez-la.