JSON.rawJSON() ist eine ES2024-Methode, die einen String mit gültigem JSON nimmt und ihn in ein spezielles "Raw-JSON-Objekt" verpackt. Wird dieses Objekt anschließend mit JSON.stringify() serialisiert, gibt der Serialisierer den enthaltenen String unverändert wieder aus - ohne ihn als String zu escapen. Damit lassen sich Werte erzeugen, die JSON.stringify() sonst nicht korrekt darstellen kann: etwa Zahlen mit voller Präzision (große BigInt-Werte, lange Dezimalzahlen) oder zukünftige JSON-Erweiterungen.

JSON.stringify() arbeitet intern mit JavaScripts Number-Typ, der nur Double-Precision-Gleitkommazahlen abbilden kann. Werte jenseits von Number.MAX_SAFE_INTEGER (2^53 - 1) verlieren beim Umweg über Number Genauigkeit, und es gibt keinen Weg, ein JavaScript-Objekt so zu konstruieren, dass JSON.stringify() daraus z. B. 12345678901234567890 schreibt. JSON.rawJSON() schließt genau diese Lücke: Der Serialisierer erkennt das Raw-Objekt und übernimmt dessen Inhalt 1:1 in den Ausgabestring.

Hinweis: JSON.rawJSON() ist seit ES2024 spezifiziert und wird in modernen Engines (Node.js ≥ 21.7, Chromium ≥ 114, Safari ≥ 17.4) unterstützt. Für ältere Umgebungen ist ein Polyfill nötig.

01 · Abschnitt

Syntax

JavaScript Syntax 
JSON.rawJSON(string)
Parameter
string

Ein String, der einen einzelnen, gültigen JSON-Primitivwert enthält - also eine Zahl, einen JSON-String, einen Boolean oder null. Strukturen wie Objekte ({...}) oder Arrays ([...]) sind als Inhalt nicht erlaubt und werfen einen SyntaxError.

Rückgabewert: Ein eingefrorenes (frozen) Objekt mit der Eigenschaft rawJSON vom Typ string. Dieses Objekt ist nicht zur direkten Nutzung gedacht, sondern dient ausschließlich als Marker für JSON.stringify().

02 · Abschnitt

Grundlegende Beispiele

Beispiel - Große Zahlen ohne Präzisionsverlust

Eine 19-stellige Ganzzahl überschreitet Number.MAX_SAFE_INTEGER. Über den Umweg Number würde sie gerundet:

JavaScript Beispiel 
const id = 12345678901234567890n;

// Ohne rawJSON: Präzisionsverlust durch Number-Konvertierung
const broken = JSON.stringify({ id: Number(id) });
console.log(broken);

// Mit rawJSON: exakter String wird in die Ausgabe übernommen
const exact = JSON.stringify({ id: JSON.rawJSON(id.toString()) });
console.log(exact);
Output 
{"id":12345678901234567000}
{"id":12345678901234567890}

Beispiel - Lange Dezimalzahlen

Auch Dezimalzahlen mit vielen Nachkommastellen werden durch den Double-Typ gerundet. JSON.rawJSON() erlaubt die exakte Übernahme aus einem String:

JavaScript Beispiel 
const price = "199.9999999999999999";

const out = JSON.stringify({
    price: JSON.rawJSON(price),
});
console.log(out);
Output 
{"price":199.9999999999999999}

Beispiel - Verschachtelt in Arrays und Objekten

Raw-JSON-Werte verhalten sich beim Serialisieren wie ganz normale Werte und können beliebig tief geschachtelt werden:

JavaScript Beispiel 
const data = {
    user: "michael",
    ids: [
        JSON.rawJSON("9007199254740993"),
        JSON.rawJSON("9007199254740994"),
    ],
    balance: JSON.rawJSON("0.10000000000000001"),
};

console.log(JSON.stringify(data));
Output 
{"user":"michael","ids":[9007199254740993,9007199254740994],"balance":0.10000000000000001}
03 · Abschnitt

Fehlerverhalten

JSON.rawJSON() validiert den übergebenen String streng. Ungültige oder strukturierte Werte führen sofort zu einem SyntaxError:

JavaScript Beispiel 
// OK – primitive JSON-Werte
JSON.rawJSON("42");
JSON.rawJSON('"hallo"');
JSON.rawJSON("true");
JSON.rawJSON("null");

// SyntaxError – Strukturen sind nicht erlaubt
try {
    JSON.rawJSON("[1, 2, 3]");
} catch (e) {
    console.log(e.name, e.message);
}

// SyntaxError – ungültige Zahl
try {
    JSON.rawJSON("01");
} catch (e) {
    console.log(e.name, e.message);
}

// SyntaxError – Whitespace ist nicht erlaubt
try {
    JSON.rawJSON("  42  ");
} catch (e) {
    console.log(e.name, e.message);
}
Output 
SyntaxError ...
SyntaxError ...
SyntaxError ...
04 · Abschnitt

Anwendungsfälle

JSON.rawJSON() ist ein spezialisiertes Werkzeug. Typische Einsatzgebiete sind:

  • Numerische Präzision wahren: APIs, die mit Geldbeträgen, Datenbank-IDs (Snowflake-IDs, BigInt-Primärschlüssel) oder wissenschaftlichen Messwerten arbeiten.
  • Bridge zu BigInt: BigInt-Werte selbst sind in JSON nicht erlaubt - mit JSON.rawJSON(big.toString()) lassen sie sich dennoch korrekt in der Ausgabe abbilden.
  • Pass-Through: Roh-Strings aus einer Datenquelle in einen größeren JSON-Output einbetten, ohne den teuren Roundtrip JSON.parse → JS-Objekt → JSON.stringify zu gehen.
  • Zukünftige JSON-Erweiterungen: Werte ausgeben, die JavaScript-seitig (noch) nicht nativ darstellbar sind, vom Konsumenten aber erwartet werden.
05 · Abschnitt

Zusammenspiel mit JSON.isRawJSON()

Beim Verarbeiten gemischter Datenstrukturen muss man oft prüfen, ob ein Wert bereits ein Raw-JSON-Marker ist - etwa in einer Replacer-Funktion. Dafür gibt es JSON.isRawJSON():

JavaScript Beispiel 
const value = JSON.rawJSON("42");

console.log(JSON.isRawJSON(value));      // true
console.log(JSON.isRawJSON({ rawJSON: "42" })); // false
console.log(JSON.isRawJSON(42));         // false
Output 
true
false
false

Mehr dazu im Artikel zu JSON.isRawJSON().

/ Weiter

Zurück zu JSON

Zur Übersicht