JSON.stringify()

value

JSON 文字列に変換する値です。

replacer 省略可

文字列化の手順の挙動を変更する関数、または value のプロパティのうち出力に含めるものを指定する String と Number の配列です。この値が配列である場合は、文字列でも数値でもない要素 (Symbol など) は完全に無視されます。文字列や数値としては、プリミティブもラッパーオブジェクトも使用可能です。この値が関数でも配列でもない場合 (null の場合や、指定しない場合など) は、結果の JSON 文字列にオブジェクトの文字列をキーとするすべてのプロパティが含まれます。

space 省略可

出力する JSON 文字列に可読性を目的に空白 (インデントや改行など) を挿入するために使う String または Number オブジェクトです。

これが Number のときは、インデントとして使う空白文字の数を示します。この数の上限は 10 です (それより大きい数値は、単に 10 となります)。 1 より小さい値は空白を使わないことを示します。

これが String のときは、その文字列 (10 文字より長い場合はその最初の 10 文字) がネストされたそれぞれのオブジェクトや配列の前に挿入されます。

これが文字列でも数値でもない (文字列や数値としては、プリミティブもラッパーオブジェクトも使用可能) 場合、たとえば null や指定しない場合は、空白は使用されません。

与えられた値を表現する JSON 文字列。

• TypeError ("cyclic object value") 例外は、循環参照が見つかった時に発生します。
• TypeError ("BigInt value can't be serialized in JSON") 例外は、 BigInt 値を文字列化しようとしたときに発生します。

JSON.stringify() は値をそれを表す JSON 表記に変換します。値は以下のように変換されます。

• Boolean、 Number、 String、および (Object() により得られる) BigInt の各オブジェクトは、文字列化の際に慣習的な変換セマンティクスに従い、対応するプリミティブ値に変換されます。(Object() により得られる) Symbol のオブジェクトは、プレーンオブジェクトとして扱われます。
• BigInt の値を文字列化しようとすると、例外が発生します。しかし、BigInt が (モンキーパッチ BigInt.prototype.toJSON = ... により) toJSON() メソッドを持っている場合、このメソッドにより文字列化できます。この制約により、適切な文字列化の方法 (そして、ほとんどの場合、対応する逆変換の方法) が常にユーザーによって明示されるようにします。
• undefined、関数 (Function)、シンボル (Symbol) は有効な JSON 値ではありません。変換中にそのような値に遭遇した場合は、(オブジェクトの中で発見された場合は) 省略されたり、(配列の中で見つかった場合は) null に変換されたりします。 JSON.stringify() は JSON.stringify(() => {}) や JSON.stringify(undefined) のように「純粋」な値を渡した場合に undefined を返すことがあります。
• Infinity および NaN の数値は、 null の値と同様に、すべて null と見なされます。(ただし、前述の値と違って、省略されることはありません)
• 配列は配列として文字列化されます。(角括弧で囲まれます) 0 から length - 1 までの添字 (両端を含みます) が文字列化され、他のプロパティは無視されます。
• その他のオブジェクトについては:
  • シンボル (Symbol) がキーとなっているプロパティはすべて、引数 replacer を使用する場合でも完全に無視されます。
  • 値が toJSON() メソッドを持っている場合は、それがデータをどう文字列化するかを決定します。オブジェクトを文字列化するかわりに、toJSON() メソッドが返す値が文字列化されます。JSON.stringify() は toJSON を 1 個の引数 key を指定して呼び出します。この引数は、replacer 関数と同じ以下の仕様です:
    • オブジェクトがプロパティの値の場合は、プロパティ名
    • 配列の要素の場合は、配列の添字を表す文字列
    • JSON.stringify() がこのオブジェクトについて直接呼ばれた場合は、空文字列
  • Date のインスタンスは文字列を返す toJSON() を実装しています (date.toISOString() と同じです)。そのため、これは文字列に変換されます。
  • 列挙可能なプロパティのみが文字列化されます。そのため、Map、Set、WeakMap、WeakSet などは "{}" に変換されます。引数 replacer を用いることで、これらをより実用的なものに変換できます。プロパティは、Object.keys() と同じアルゴリズムで走査されます。このアルゴリズムは、完全に定義された順番を用い、実装間で一貫性があります。例えば、JSON.stringify を同じオブジェクトに対して用いると、常に同じ文字列を生成します。また、JSON.parse(JSON.stringify(obj)) は (オブジェクトが完全に JSON に変換可能であると仮定すると) もとのオブジェクトと同じキーの順番を持つオブジェクトを生成します。

replacer 引数は関数または配列です。

配列の場合、その要素は結果の JSON 文字列に含めるオブジェクトのプロパティの名前を表します。文字列と数値である値のみが処理に用いられ、シンボルのキーは無視されます。

関数の場合、key と文字列化される value の 2 つの引数を取ります。キーをもつオブジェクトが replacer のコンテキストで this として提供されます。

replacer 関数は、まず文字列化されるオブジェクトについて呼び出され、このときの key は空文字列 ("") です。その後、文字列化されるオブジェクトや配列のそれぞれのプロパティについて呼び出されます。配列の添字は、文字列として key に入ります。処理中のプロパティの値は、文字列化において replacer の返値に置き換えられます。すなわち:

• 数値 (Number)、文字列 (String)、論理値 (Boolean)、null を返すと、その値を直接文字列化したものがプロパティの値として使用されます。(BigInt を返すと、例外が発生します)
• 関数 (Function)、シンボル (Symbol)、undefined を返すと、出力にはそのプロパティが含まれなくなります。
• その他のオブジェクトを返した場合、そのオブジェクトのそれぞれのプロパティに replacer 関数を呼び出して再帰的に文字列化します。

通常、配列の要素の添字はずれません (要素が関数などの無効な値である場合も、省略されるのではなく null になります)。replacer 関数を用いると、別の配列を返すことで、配列の要素の順番を制御できます。

space 引数で最終的な文字列での空白の数を調整できます。

• 数値であれば、レベルの階層がそれぞれその数の空白文字 (最大 10 文字) でインデントされます。
• 文字列であれば、レベルの階層がそれぞれこの文字列 (またはその最初の 10 文字) でインデントされます。

インデントの階層が 10 より長くなることはありません。space の値が数値の場合は最大 10 となり、文字列の場合は 10 文字に切り詰められます。

function replacer(key, value) {
  // プロパティをフィルターする
  if (typeof value === "string") {
    return undefined;
  }
  return value;
}

var foo = {
  foundation: "Mozilla",
  model: "box",
  week: 45,
  transport: "car",
  month: 7,
};
JSON.stringify(foo, replacer);
// '{"week":45,"month":7}'

replacer で最初のオブジェクトと空文字列をキーとするプロパティを区別したい場合は、(両方の場合において key は空文字列となり、value はオブジェクトを取りうるので) 繰り返しの回数の記録が必要になるでしょう。(最初の繰り返しより後の場合、本当に空文字列のキーです)

function makeReplacer() {
  let isInitial = true;

  return (key, value) => {
    if (isInitial) {
      isInitial = false;
      return value;
    }
    if (key === "") {
      // (最初のオブジェクト以外の) 名前が "" であるプロパティをすべて取り除く
      return undefined;
    }
    return value;
  };
}

const replacer = makeReplacer();
console.log(JSON.stringify({ "": 1, b: 2 }, replacer)); // "{"b":2}"

replacer が配列である場合、その配列の値は結果の JSON 文字列に含めるプロパティの名前を示します。

JSON.stringify(foo, ["week", "month"]);
// '{"week":45,"month":7}', "week" と "month" プロパティだけが保持される

出力をスペース 1 個でインデントします。

console.log(JSON.stringify({ a: 2 }, null, " "));
/*
'{
 "a": 2
}'
*/

タブ文字を使うと、標準的な表示の整形と同様になります。

console.log(JSON.stringify({ uno: 1, dos: 2 }, null, "\t"));
// 以下の文字列を返します:
/*
{
	"uno": 1,
	"dos": 2
}
*/

オブジェクトに toJSON() を定義することで、シリアライズの挙動をオーバーライドできます。

文字列化されるオブジェクトに toJSON という名前の値に関数を持ったプロパティがある場合、その toJSON() メソッドで JSON の文字列化の挙動をカスタマイズできます。シリアライズされるオブジェクトの代わりに、その toJSON() メソッドが呼び出されたときの返値がシリアライズされます。 JSON.stringify() は toJSON に以下のどれか 1 つの引数をつけて呼び出します。

• このオブジェクトがプロパティの値であった場合は、プロパティ名
• 配列内の値であった場合は、文字列化した配列のインデックス
• JSON.stringify() がこのオブジェクトに対して直接呼び出された場合は、空文字列

例

var obj = {
  data: "data",

  toJSON(key) {
    if (key) return `Now I am a nested object under key '${key}'`;
    else return this;
  },
};

JSON.stringify(obj);
// '{"data":"data"}'

JSON.stringify({ obj }); // Shorthand property names (ES2015).
// '{"obj":"Now I am a nested object under key 'obj'"}'

JSON.stringify([obj]);
// '["Now I am a nested object under key '0'"]'

JSON 形式はオブジェクト参照に対応していないため (IETF 草稿はありますが)、循環参照のあるオブジェクトをエンコードしようとすると TypeError が発生します。

const circularReference = {};
circularReference.myself = circularReference;

// 循環参照をシリアライズすると "TypeError: cyclic object value" が発生
JSON.stringify(circularReference);

循環参照をシリアライズするためには、これに対応したライブラリを使用したり (Douglas Crockford による cycle.js など)、自分自身で解決策を実装したりする方法があります。循環参照を探索してシリアライズされた値に置き換える (または削除する) 必要があるでしょう。

JSON.stringify() をオブジェクトをディープコピーするために使っている場合は、かわりに structuredClone() を使いたくなるかもしれません。この関数は循環参照に対応しています。v8.serialize() などのバイナリシリアライズを行う JavaScript エンジンの API も、循環参照に対応しています。

従来、JSON は JavaScript の完全に厳密なサブセットではありませんでした。文字コードポイント U+2028 LINE SEPARATOR (改行) と U+2029 PARAGRAPH SEPARATOR (改段落) は JSON テキスト内の文字列リテラルやプロパティ名に使用することができます。しかし、JavsScript のテキスト内で同様の文脈では使用することができず、Unicode エスケープを使用した \u2028 および \u2029 しか使うことができません。これは最近変更され、どちらのコードポイントも JSON と JavaScript の両方の文字列で使用することができるようになりました。

したがって、古い JavaScript エンジンとの互換性が必要な場合は、JSON.stringify から返された文字列を JavaScript の文字列に代入するために、直接 eval や new Function に渡したり、JSONP URL の一部として用いたりするのは危険です。次のユーティリティを使用することができます。

function jsFriendlyJSONStringify(s) {
  return JSON.stringify(s)
    .replace(/\u2028/g, "\\u2028")
    .replace(/\u2029/g, "\\u2029");
}

var s = {
  a: String.fromCharCode(0x2028),
  b: String.fromCharCode(0x2029),
};
try {
  eval("(" + JSON.stringify(s) + ")");
} catch (e) {
  console.log(e); // "SyntaxError: unterminated string literal"
}

// catch する必要はない
eval("(" + jsFriendlyJSONStringify(s) + ")");

// Firefox での console.log はコンソールにログ出力をする場合
//   Unicode エスケープを解除するので、alert を使う
alert(jsFriendlyJSONStringify(s)); // {"a":"\u2028","b":"\u2029"}

var a = JSON.stringify({ foo: "bar", baz: "quux" });
//'{"foo":"bar","baz":"quux"}'
var b = JSON.stringify({ baz: "quux", foo: "bar" });
//'{"baz":"quux","foo":"bar"}'
console.log(a !== b); // true

// 一部の記憶関数は JSON.stringify を使用して引数をシリアライズしており、
// 上記のような同じオブジェクトに出会った時にキャッチし損ねることがあります

ユーザーが作成したオブジェクトを格納し、ブラウザーが閉じた後に復元できるようにしたい場合は以下の例が JSON.stringify() を適用した模範例です。

// JSON の一例を作成
var session = {
  screens: [],
  state: true,
};
session.screens.push({ name: "screenA", width: 450, height: 250 });
session.screens.push({ name: "screenB", width: 650, height: 350 });
session.screens.push({ name: "screenC", width: 750, height: 120 });
session.screens.push({ name: "screenD", width: 250, height: 60 });
session.screens.push({ name: "screenE", width: 390, height: 120 });
session.screens.push({ name: "screenF", width: 1240, height: 650 });

// JSON.stringify() で JSON 文字列に変換してから
// session の名前で localStorage に保存
localStorage.setItem("session", JSON.stringify(session));

// JSON.stringify() で生成されて localStorage に保存された文字列を
// 再び JSON オブジェクトに変換する方法の例
var restoredSession = JSON.parse(localStorage.getItem("session"));

// ここで変数 restoredSession には localStorage に保存されていた
// オブジェクトが入っている
console.log(restoredSession);

well-formed JSON.stringify 仕様を実装しているエンジンは、サロゲート文字、U+D800 から U+DFFF までのすべてのコードポイントを、リテラルではなく Unicode エスケープシーケンスを使用して文字列化します。この変更前は、入力にサロゲート文字が含まれている場合、JSON.stringify はサロゲート文字をそのまま出力していました。このような文字列は妥当な UTF-8 または UTF-16 でエンコードされていませんでした。

JSON.stringify("\uD800"); // '"�"'

しかし、この変更で JSON.stringify は lone surrogates を JSON エスケープシーケンスによって表すようになり、妥当な UTF-8 または UTF-16 でエンコードすることができるようになりました。

JSON.stringify("\uD800"); // '"\\ud800"'

この変更では、サロゲート文字の Unicode エスケープをサロゲート文字と同一のものとして扱うため、 JSON.stringify の結果を、JSON テキストを妥当である限りどのようなものでも受け付ける JSON.parse のような API に渡したときに後方互換性があります。JSON.stringify の結果を直接解析する場合のみ、JSON.stringify がこれらのコードポイントに対して 2 通りのエンコーディングをする可能性があることに注意して扱う必要があります。

• core-js による現在の JSON.stringify の挙動 (シンボルおよび well-formed unicode) のポリフィル
• JSON.parse()
• cycle.js – JSON.decycle と JSON.retrocycle の 2 つの関数を導入します。これらは循環的な構造と DAG を、拡張されたレトロ互換性のある JSON 形式にエンコードおよびデコードすることができます。