JSON

Description

Contrairement la plupart des objets globaux, JSON n'est pas un constructeur. Vous ne pouvez pas l'utiliser avec l'oprateur new ni invoquer l'objet JSON comme une fonction. Toutes les proprits et mthodes de JSON sont statiques (comme pour l'objet Math).

Diffrences entres JavaScript et JSON

JSON est une syntaxe pour srialiser des objets, tableaux, nombres, chanes de caractres, boolens et null. Elle est base sur la syntaxe de JavaScript mais en est distincte : la plupart du JavaScript n'est pas du JSON. Par exemple :

Objets et tableaux

Les noms de proprit doivent tre des chanes de caractres entre guillemets doubles ; les virgules finales sont interdites.

Nombres

Les zros initiaux sont interdits. Un point dcimal doit tre suivi d'au moins un chiffre. NaN et Infinity ne sont pas pris en charge.

Tout texte JSON est une expression JavaScript valide, mais uniquement aprs la rvision JSON superset (angl.). Avant la rvision, U+2028 LINE SEPARATOR et U+2029 PARAGRAPH SEPARATOR sont autoriss dans les littraux de chanes et les cls de proprit en JSON ; mais le mme usage dans les littraux de chanes JavaScript provoque une SyntaxError.

Les autres diffrences incluent l'autorisation uniquement des chanes entre guillemets doubles et l'absence de prise en charge de undefined ou des commentaires. Pour celles et ceux qui souhaitent utiliser un format de configuration plus convivial bas sur JSON, il existe JSON5 (angl.), utilis par le compilateur Babel, et le plus couramment utilis est YAML.

Le mme texte peut galement reprsenter des valeurs diffrentes dans les littraux d'objet JavaScript et dans JSON. Pour plus d'informations, voir Syntaxe des littraux d'objet et JSON.

Grammaire complte de JSON

La syntaxe JSON valide est dfinie formellement par la grammaire suivante, exprime en ABNF (angl.), et copie depuis la norme JSON IETF (RFC) (angl.) :

JSON-text = ws valeur ws
dbut-tableau     = ws %x5B ws  ; [ crochet ouvrant
dbut-objet       = ws %x7B ws  ; { accolade ouvrante
fin-tableau       = ws %x5D ws  ; ] crochet fermant
fin-objet         = ws %x7D ws  ; } accolade fermante
sparateur-nom    = ws %x3A ws  ; : deux-points
sparateur-valeur = ws %x2C ws  ; , virgule
ws = *(
     %x20 /              ; Espace
     %x09 /              ; Tabulation horizontale
     %x0A /              ; Saut de ligne
     %x0D                ; Retour chariot
     )
valeur = false / null / true / objet / tableau / nombre / chane-de-caractres
false = %x66.61.6c.73.65   ; false
null  = %x6e.75.6c.6c      ; null
true  = %x74.72.75.65      ; true
objet = dbut-objet [ membre *( sparateur-valeur membre ) ]
         fin-objet
membre = chane-de-caractres sparateur-nom valeur
tableau = dbut-tableau [ valeur *( sparateur-valeur valeur ) ] fin-tableau
nombre = [ moins ] int [ frac ] [ exp ]
point-dcimal = %x2E          ; .
chiffre1-9 = %x31-39           ; 1-9
e = %x65 / %x45            ; e E
exp = e [ moins / plus ] 1*DIGIT
frac = point-dcimal 1*DIGIT
int = zro / ( chiffre1-9 *DIGIT )
moins = %x2D               ; -
plus = %x2B                ; +
zro = %x30                ; 0
chane-de-caractres = guillemet-double *char guillemet-double
char = non-chap /
    chap (
        %x22 /          ; "    guillemet double       U+0022
        %x5C /          ; \    barre oblique inverse U+005C
        %x2F /          ; /    barre oblique          U+002F
        %x62 /          ; b    retour arrire         U+0008
        %x66 /          ; f    saut de page           U+000C
        %x6E /          ; n    saut de ligne          U+000A
        %x72 /          ; r    retour chariot         U+000D
        %x74 /          ; t    tabulation             U+0009
        %x75 4HEXDIG )  ; uXXXX                       U+XXXX
chap = %x5C           ; \
guillemet-double = %x22 ; "
non-chap = %x20-21 / %x23-5B / %x5D-10FFFF
HEXDIG = DIGIT / %x41-46 / %x61-66   ; 0-9, A-F, ou a-f
       ; HEXDIG quivalent  la rgle HEXDIG dans [RFC5234]
DIGIT = %x30-39            ; 0-9
      ; DIGIT quivalent  la rgle DIGIT dans [RFC5234]

Des espaces blancs insignifiants peuvent tre prsents n'importe o sauf dans un JSONNumber (les nombres ne doivent pas contenir d'espaces blancs) ou dans une JSONString (o ils sont interprts comme le caractre correspondant dans la chane de caractres, ou provoqueraient une erreur). Les caractres tabulation (U+0009), retour chariot (U+000D), saut de ligne (U+000A) et espace (U+0020) sont les seuls caractres blancs valides.

Proprits statiques

JSON[Symbol.toStringTag]

La valeur initiale de la proprit [Symbol.toStringTag] est la chane de caractres "JSON". Cette proprit est utilise dans Object.prototype.toString().

Mthodes statiques

JSON.isRawJSON()

Teste si une valeur est un objet retourn par JSON.rawJSON().

JSON.parse()

Analyse une portion de texte en tant que JSON, en transformant ventuellement la valeur produite et ses proprits, puis retourne la valeur.

JSON.rawJSON()

Cre un objet  raw JSON  contenant une portion de texte JSON. Lorsqu'il est srialis en JSON, l'objet raw JSON est trait comme s'il tait dj une portion de JSON. Ce texte doit tre un JSON valide.

JSON.stringify()

Retourne une chane de caractres JSON correspondant la valeur dfinie, en incluant ventuellement seulement certaines proprits ou en remplaant les valeurs des proprits d'une manire dfinie par l'utilisateurice.

Exemples

Exemple JSON

{
  "browsers": {
    "firefox": {
      "name": "Firefox",
      "pref_url": "about:config",
      "releases": {
        "1": {
          "release_date": "2004-11-09",
          "status": "retired",
          "engine": "Gecko",
          "engine_version": "1.7"
        }
      }
    }
  }
}

Vous pouvez utiliser la mthode JSON.parse() pour convertir la chane JSON ci-dessus en un objet JavaScript :

const jsonText = `{
  "browsers": {
    "firefox": {
      "name": "Firefox",
      "pref_url": "about:config",
      "releases": {
        "1": {
          "release_date": "2004-11-09",
          "status": "retired",
          "engine": "Gecko",
          "engine_version": "1.7"
        }
      }
    }
  }
}`;

console.log(JSON.parse(jsonText));

Srialisation des nombres sans perte

JSON peut contenir des littraux numriques de prcision arbitraire. Cependant, il n'est pas possible de reprsenter tous les nombres JSON exactement en JavaScript, car JavaScript utilise une reprsentation en virgule flottante qui a une prcision fixe. Par exemple, 12345678901234567890 === 12345678901234567000 en JavaScript car ils ont la mme reprsentation en virgule flottante. Cela signifie qu'il n'existe aucun nombre JavaScript qui corresponde prcisment au nombre JSON 12345678901234567890.

Supposons que vous ayez une reprsentation exacte d'un certain nombre (soit via BigInt ou une bibliothque personnalise) :

const data = {
  // Utiliser un BigInt ici pour stocker la valeur exacte,
  // mais cela peut galement tre une bibliothque de nombres  haute prcision personnalise,
  // si le nombre n'est pas un entier.
  gross_gdp: 12345678901234567890n,
};

Vous souhaitez le srialiser, puis l'analyser pour obtenir exactement le mme nombre. Cela pose plusieurs difficults :

• Du ct de la srialisation, pour obtenir un nombre dans JSON, vous devez passer un nombre JSON.stringify, soit via la fonction replacer, soit via la mthode toJSON. Mais, dans les deux cas, vous avez dj perdu de la prcision lors de la conversion du nombre. Si vous passez une chane de caractres JSON.stringify, elle sera srialise en tant que chane de caractres, et non en tant que nombre.
• Du ct de l'analyse, tous les nombres ne peuvent pas tre reprsents exactement. Par exemple, JSON.parse("12345678901234567890") renvoie 12345678901234568000 car le nombre est arrondi au nombre reprsentable le plus proche. Mme si vous utilisez une fonction reviver, le nombre sera dj arrondi avant que la fonction reviver ne soit appele.

Il existe gnralement deux faons de garantir que les nombres sont convertis sans perte en JSON et ranalyss : l'une implique un nombre JSON, l'autre une chane de caractres JSON. JSON est un format de communication. Si vous utilisez JSON, vous communiquez donc probablement avec un autre systme (requte HTTP, stockage dans une base de donnes, etc.). La meilleure solution choisir dpend du systme destinataire.

Utiliser des chanes de caractres JSON

Si le systme destinataire ne dispose pas des mmes capacits de traitement JSON que JavaScript et ne prend pas en charge les nombres haute prcision, vous pouvez srialiser le nombre sous forme de chane de caractres, puis le traiter comme une chane de caractres ct destinataire. Il s'agit galement de la seule option disponible dans les anciennes versions de JavaScript.

Pour dfinir comment les types de donnes personnaliss (y compris BigInt) doivent tre srialiss en JSON, ajoutez soit une mthode toJSON votre type de donnes, soit utilisez la fonction replacer de JSON.stringify().

// Utiliser la mthode toJSON()
BigInt.prototype.toJSON = function () {
  return this.toString();
};
const str1 = JSON.stringify(data);

// Utiliser JSON.stringify() avec replacer
const str2 = JSON.stringify(data, (key, value) => {
  if (key === "gross_gdp") {
    return value.toString();
  }
  return value;
});

Dans les deux cas, le texte JSON ressemblera {"gross_gdp":"12345678901234567890"}, o la valeur est une chane de caractres et non un nombre. Ensuite, du ct du destinataire, vous pouvez analyser le JSON et traiter la chane de caractres.

Utiliser des nombres JSON

Si le destinataire de ce message prend en charge nativement les nombres haute prcision (tels que les entiers Python), il est videmment prfrable de transmettre les nombres sous forme de nombres JSON, car ils peuvent tre directement analyss en tant que type haute prcision au lieu d'analyser une chane de caractres partir de JSON, puis d'analyser un nombre partir de la chane de caractres. En JavaScript, vous pouvez srialiser des types de donnes arbitraires en nombres JSON sans produire d'abord une valeur numrique (ce qui entranerait une perte de prcision) en utilisant JSON.rawJSON() pour dfinir prcisment ce que doit tre le texte source JSON.

// Utiliser la mthode toJSON()
BigInt.prototype.toJSON = function () {
  return JSON.rawJSON(this.toString());
};
const str1 = JSON.stringify(data);

// Utiliser JSON.stringify() avec replacer
const str2 = JSON.stringify(data, (key, value) => {
  if (key === "gross_gdp") {
    return JSON.rawJSON(value.toString());
  }
  return value;
});

Le texte transmis JSON.rawJSON est trait comme s'il s'agissait dj d'un lment JSON, il ne sera donc pas srialis nouveau sous forme de chane de caractres. Par consquent, le texte JSON ressemblera {"gross_gdp":12345678901234567890}, o la valeur est un nombre. Ce JSON peut ensuite tre analys par le destinataire sans traitement supplmentaire, condition que le systme destinataire n'ait pas les mmes limitations de prcision que JavaScript.

Lorsque vous analysez du JSON contenant des nombres de haute prcision dans JavaScript, soyez particulirement vigilant, car lorsque JSON.parse() invoque la fonction reviver, la valeur que vous recevez est dj analyse (et a perdu de sa prcision). Vous pouvez utiliser le paramtre context.source de la fonction reviver de JSON.parse() reviver pour ranalyser le nombre vous-mme.

const parsedData = JSON.parse(str, (key, value, context) => {
  if (key === "gross_gdp") {
    // Or use the constructor of your custom high-precision number library
    return BigInt(context.source);
  }
  return value;
});
// { gross_gdp: 12345678901234567890n }

Spcifications

Compatibilit des navigateurs

Voir aussi

• Comparer du JSON (angl.)
• Embellir/diter du JSON (angl.)
• Analyser du JSON (angl.)
• Valider du JSON (angl.)