JSON文字列化

これは、繰り返し行うことになる地味な作業、すなわち「あるペイロードを別のペイロードの中に入れる」という操作の正体です。Webhook定義の中のリクエストボディ。テストファイルの中のフィクスチャ。KubernetesのConfigMapの値としての設定ドキュメント。OpenAPIのexampleフィールドの中のサンプルレスポンス。いずれの場合も、内側のドキュメントは外側の中では文字列にならなければならず、つまり内側のすべての引用符・バックスラッシュ・改行をエスケープする必要があります。

多くの人はこれを検索と置換で手作業に行いますが、失敗の仕方には特定の、予測可能なパターンがあります。先に引用符を置換し、次にバックスラッシュを置換すると、各引用符の直前に置いたばかりのバックスラッシュがもう一度エスケープされます。欲しかったのは\"なのに、できあがるのは\\"で、これは「リテラルのバックスラッシュの後に文字列が終わる」として解釈されます。ドキュメントの中に引用符を含むものが現れるまでは、問題なく動いているように見えます。

1回の文字走査でエスケープすれば、この失敗は起こり得ません。各文字は1度だけ調べられ、1度だけ変換されます。" を \" に、\ を \\ に、改行を \n に、タブを \t に。後のパスが先のパスの出力を再処理する機会は一切ありません。

RFC 8259は、U+0020未満のすべての制御文字をエスケープすることを要求するため、短縮形のない文字は\uシーケンスになります。非ASCII文字はデフォルトではそのまま残ります。現代のJSONはUTF-8であり、エスケープしても結果が大きくなり読みにくくなるだけだからです。ただし、古いログパイプラインや上位バイトを壊すシステムのように、出力先が純粋なASCIIを本当に必要とする場合は、オプションでエスケープできます。その際、Basic Multilingual Planeの外側の文字にはサロゲートペアを正しく出力します。1つの\uでは絵文字を表せず、1つだけ出力すると文字が途切れてしまうためです。

デフォルトでは、入力はまずJSONとして検証されます。壊れた入力をエスケープすると、文字列リテラル自体は有効でも、その中身は後で——たいていずっと厄介な場所で——パースに失敗する文字列になります。ログ行やシェルスニペットなど、任意のテキストをエスケープしたい場合は、この検証をオフにしてください。