JSON 文字列エスケープ

このツールの役割

JSON 文字列は、素の二重引用符・素のバックスラッシュ・素の改行を含めません — 形式は文字列の始まりと終わりを示すためにそれらの文字を必要とします。だからそれらは代わりにエスケープの並びとして書かれ、このツールは 2 つの形式を相互に変換します。ふつうのテキストを貼り付けて JSON に落とし込む準備の整ったエスケープ版を得るか、方向を切り替えてエスケープされたテキストを再び読める形に戻します。

2 つ目の向きこそ、人がふつう訪れる理由です: ログ行、エラーメッセージ、あるいはバックスラッシュの壁のように返ってきた curl の応答です。すべてがブラウザ内で動き、読もうとしているペイロードが本番の応答であるときにこれは重要です。

エスケープの並び

JSON はエスケープの短い一覧を定義し、このツールはまさにその一覧を使います — それ以上に風変わりなものはありません。ほかは何であれ有効な JSON ではないからです。

• \" — 二重引用符。さもないと文字列を終わらせます。
• \\ — 単一のバックスラッシュ。Windows のパスや正規表現のパターンが二重になるのはこのためです。
• \n と \r — 改行と復帰。
• \t — タブ。\b と \f もあり、バックスペースとフォームフィード用です。
• \/ — 前向きスラッシュの任意のエスケープ。有効ですが決して必須ではありません。このツールは受け付け、決して生みません。
• \uXXXX — 16 進コードによる任意の文字で、制御文字や ASCII 外のものを書ける方法です。

制御文字 — コード 32 未満のもの — は JSON 文字列の中に文字どおりの形をまったく持たないので、ASCII 出力を求めていなくても常に \uXXXX エスケープとして出ます。

バックスラッシュが増える理由

このようなツールに手を伸ばす最もよくある理由は、複数回エスケープされたテキストです。各回のエンコードが、前の回が導入したバックスラッシュをエスケープするので、単一の引用符文字がどんどん長い尾を生やします:

original    He said "hi"
escaped     He said \"hi\"
escaped x2  He said \\\"hi\\\"

これは、値が JSON に直列化され、その JSON が別の JSON 文書の中の文字列として保存され、その結果がログに記録されるときに起きます。一度デコードすると 1 層を取り消します。テキストがふつうに読めるまで、結果に対してもう一度動かしてください。デコードして出力にまだはぐれたバックスラッシュがあれば、それは本物の余分な層であって、変換のバグではありません。

引用符: 値か断片か

完全な JSON 文字列の値は、囲みの二重引用符を含みます。しかしたいていの場合、あなたはコードや設定に既に存在する文字列の中に貼り付けようとしており、そこではその引用符は誤りになります。だからエスケープは既定で素のエスケープされた内容を生み、「囲みの引用符を含める」の選択肢は、丸ごと貼り付けられる値が欲しいときにそれらを加えます。

デコードにはそのような選択は要りません — 両方の形式を受け付けます。断片を貼り付けても、JSON 文書からそのまま完全な引用符付きの値を貼り付けても、囲みの引用符が認識されて取り除かれます。

Unicode と、それをエスケープするとき

JSON は Unicode の形式です。"שלום" と "😀" は、書かれたとおりで申し分なく有効な JSON 文字列で、読めるまま残すのがここでの既定です。\uXXXX の選択肢は、追いついていないシステムのために存在します: ASCII を仮定してほかのものを壊す、古いログのパイプライン・端末・パーサーです。

その選択肢がオンのとき、一つの詳細が重要です。基本範囲外の文字 — ほとんどの絵文字 — は、内部でサロゲートペアと呼ばれる 2 つの単位として保存され、形式は両方の半分を別々のエスケープとして書くことを要求します。だから絵文字は 1 つの長いエスケープではなく 2 つの \u エスケープになります。これを誤るツールは、どのパーサーも受け付けないエスケープを生み、それがあるシステムを生き延びて次で壊れる絵文字のふつうの説明です。

デコードが失敗するとき

すべてのバックスラッシュの並びが有効なエスケープではありません。\q は JSON で何も意味せず、\u12 は桁の半分が欠けた \u エスケープです。それらをそのまま通して、問題なさそうだがデータが言ったものではない出力を返す代わりに、このツールは止まって、不正な並びが始まる正確な行と列を報告します。

実務上そのエラーは有益です: はぐれた \q はたいてい、テキストがそもそも JSON エスケープされていなかったことを意味し、途中で切れた \u はたいてい、入力が短く切られたことを意味します — 長さの上限で切り取られたログ行や、並びの途中で止まったコピーです。