JSON Toolkit

JSON修復ガイド:壊れたLLM出力の救出と信頼の境界線

要点:markdownコードフェンスで囲まれ、末尾カンマやPythonリテラルを含むLLM出力は、厳密なパーサーには一切受け付けられません。修復ツールが実際に直せる9種類のエラーと直せない4種類の境界を整理し、状態機械と正規表現という2つの実装方式の違いを解説。jsonrepairとjson-repairの二重スタック接続手順と、修復結果をスキーマ検証で裏付ける方法までを扱います。

中級約 6 分で読めます2026-11-08 公開2026-11-08 更新
JSON修復のパイプライン図:フェンス剥離、引用符の正規化、括弧の対応付けから最終検証まで

厳密なパーサーは壊れた入力に対して一切寛容ではありません。エラーメッセージと行番号を1つ渡すだけで、データは1バイトも返してくれません。修復ツールの存在意義は「完全な失敗」を「とりあえず動く状態」に変えることです。ただし、修復が補ったものは常に意図に対する最良の推測であり、正しさの保証ではありません。

一、壊れたJSONはどこから来るのか:3つの発生源

修復は万能ではないので、まず入力の正体を見極めます。実務で非標準JSONが生まれる場所は3つに集約されます。

  1. LLMの出力。言語モデルはトークン単位でテキストを生成しており、JSONシリアライザーを実行しているわけではありません。「JSONのみを出力して」と頼んでも、モデルは ```json のコードフェンスで囲んだり、「はい、こちらがデータです」という一言を前置きしたり、末尾カンマを残したり、トークン上限に達してオブジェクトの途中で停止したりします。
  2. 他の言語からのコピー。console.log で出力したJavaScriptオブジェクトにはシングルクォートと引用符なしのキーが付き、Pythonの辞書は True/False/None と表示されます。この「JSONに似ている」テキストは JSON.parse に渡した瞬間に爆発します。
  3. JSON5/JSONC設定ファイル。tsconfigのようなファイルはコメントと末尾カンマを合法的に許容します。これをそのまま厳密なパーサーに渡すと、やはり拒否されます。

3つの発生源で対処法は異なりますが、修復ツールはすべてをカバーできます。ただし条件があり、エラーが修復ツールが宣言している「修復可能リスト」に含まれている必要があります。

二、修復できる9種類:修復ツールの本当の得意分野

jsonrepairライブラリのドキュメントと各ツールベンダーが公表している能力リストを総合すると、自動修復できるエラーは9種類に分類できます。

分類 壊れた入力 修復結果
末尾カンマ [1, 2, 3,] [1, 2, 3]
シングルクォート/全角引用符 {'a': 'b'}、{"a": "b"} {"a": "b"}
引用符のないキー {name: 'Ada'} {"name": "Ada"}
コメント {"a": 1 /* 注釈 */} {"a": 1}
Pythonリテラル {"ok": True, "v": None} {"ok": true, "v": null}
markdownフェンス ```json {...} ``` {...}
カンマの欠落 [1 2] [1, 2]
括弧/引用符の未閉鎖 {"a": [1, 2 {"a": [1, 2]}
JSONP/文字列連結 cb({...})、"x" + "y" {...}、"xy"

この9種類に共通するのは、データはすべて揃っていて、構文だけが壊れているという点です。修復ツールは句読点とラッパーを調整するだけで、値には一切触れません。次の細かい点は個別に覚えておく価値があります。

  • 先頭ゼロ付きの数値は文字列に変換される:007 は 7 ではなく "007" に修復されます。桁情報を失わないためです。フィールドがもともとテキスト形式のコード番号なら正しい動作ですが、本当に数値なら自分で判断する必要があります。
  • 裸の単語は文字列になる:NaN は数値として修復できず、実装によって "NaN" になるものと null になるものがあります。ライブラリごとに挙動が違うので、パイプラインに組み込む前に一度試してください。
  • 入力がすでに正当なJSONならそのまま返す:修復ツールには厳密なパースの高速経路が組み込まれており、正当な入力は修復ロジックを通らないため、「修復するほど壊れる」ことはありません。

三、修復できない4種類:信頼の境界線の反対側

修復ツールの能力限界も同じく明確です。次の4種類は期待しないでください。

  1. HTMLエラーページや純粋な文章。入力にJSON構造がまったく存在せず、どのツールもデータを無から生成することはできません。
  2. 構文的には正当だがデータが間違っているケース。キーのスペルミス、値の位置間違い、数値を文字列として保存——これらは意味的な問題であり、構文レベルでは完全に合法なので、どの修復ツールも素通しさせます。
  3. 切断によって失われたデータ。補完機能は {"items": [{"id": 1}, {"na を正当なJSONに修復できますが、name フィールドの値は二度と戻りません。修復結果は「正当だが不完全」なオブジェクトです。本番環境では、補完するか再試行するかを決める前に、必ず stopReason === "max_tokens" を確認してください。
  4. 重複キーと曖昧な構造。同名のキーが2つある場合、どちらが有効になるかはパーサーの実装に依存します。責任ある修復ツールはstrictモードを提供し、黙って一方を選ぶのではなくエラーを投げます。

信頼の境界線を一文でまとめると、修復は「最良の推測」であって「正しさの保証」ではないということです。検証せずに修復結果を下流へ流すことは、目立つ構文リスクを、より見えにくいデータリスクに交換するのと同じです。

四、実装の2流派:URL一つで違いが試せる

市場の修復ツールには2つの実装流派があり、その能力差は特定の入力ですぐに現れます。

正規表現置換派は壊れたパターンをグローバルに検索・置換します。次の入力を考えてください。

{"url": "http://example.com", 'note': 'fine'}

「シングルクォートをダブルクォートに変える」正規表現はURLの中身まで巻き込み、「すべての // を削除する」コメント除去の正規表現は http:// を真っ二つにします。文字列の内側と構造の外側では見た目が同じであり、正規表現には区別できません。

一文字ずつの状態機械派はパース状態を追跡します。現在ダブルクォート文字列の中にいるのか、シングルクォート文字列の中なのか、行コメントの中なのか、ブロックコメントの中なのか、値を待っている状態なのか。' を見つけたとき、まず「自分は文字列の中にいるか」を判断してから、引用符を変換するかスキップするかを決めます。http://example.com はダブルクォート文字列の中にあるので、状態機械は中の // がコメントではなくデータだと認識し、そのまま保持します。jsonrepairやjson-healerといったライブラリはこの流派で、コミュニティの解説で繰り返し強調されている「修復ツールは検索置換ではない」という言葉はまさにこのことを指します。

修復パイプラインの完全な順序(devkitsが公開している実装の流れ)も見る価値があります。フェンス剥離 → 全角引用符の正規化 → 最初の対応の取れたブロック抽出 → コメント除去 → キーへの引用符付与 → 末尾カンマ除去 → リテラル変換 → 最後に JSON.stringify で再シリアライズ。最後の再シリアライズが鍵です。前段で何をしていようと、出力はパース結果から再生成されるため、下流のどの厳密なパーサーも受け入れられます。

五、コードでの接続方法:順序化されたパースチェーン

コードに修復を組み込む場合、ライブラリ選定よりも順序が重要です。json2toonとaijsonmedicが公開しているパターンに沿って整理すると、順序はこうなります。切断チェック → JSON区間の抽出 → 厳密なパース → 修復によるフォールバック → スキーマ検証。

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // 切断された出力を修復してもデータは欠けたまま。再試行する
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // JSON区間を抽出:LLMは前後に挨拶を付けることがある
  const start = text.search(/[[{]/);
  const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
  const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
  try {
    return JSON.parse(candidate);   // 正当な入力は高速経路へ
  } catch {
    return JSON.parse(jsonrepair(candidate));  // 修復によるフォールバック
  }
}

Python側では json-repair パッケージ(スター数4,700以上)の loads() が直接オブジェクトを返します。

from json_repair import repair_json
import json

broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}

さらに2つの実務的な細部があります。

  • スタックの整合。フロントエンドとバックエンドの両方で修復する場合は、意味的に同源の実装を選びます(Pythonのjson-repairとそのTS移植版 @yarmu/json-repair、または同一の整合性コーパス485件を両側が通過しているjsonmend)。そうしないと、同じ出力がフロントエンドではAに、バックエンドではBに修復され、問題の特定がさらに難しくなります。
  • 修復ログの有効化。@yarmu/json-repair は logging: true で毎回の修復操作の配列を返します。本番の修復率が急に上がったとき、通常はプロンプトかモデルのバージョンが変わった合図です。エラーレポートよりも早い信号になります。

修復の後に省略できないステップがもう一つあります。スキーマ検証です。構文が直ってもデータが使えるとは限りません。欠落フィールド、型の不一致、余分なキーはすべてスキーマで捕捉します。契約テストの考え方がそのままここに適用できます。「JSON Schema契約テストのやり方」を参照してください。

六、予防チェックリスト:修復しなくて済むのが最善

修復はあくまでフォールバックです。源流で壊れたJSONを減らすことが本質的な勝利です。優先度順に並べます。

  1. Structured Outputs(json_schemaモード):デコード段階でスキーマによって制約されるため、末尾カンマはそもそも生成されません。OpenAIのstrictモードの失敗率は約0.1%ですが、additionalProperties: false などの厳しい要件が代償です。
  2. JSONモード(json_object):構文の正当性だけを保証し、形状は保証しません。トークン上限による切断も依然として起こります。
  3. 明示的な指示:JSONモードのないエンドポイントでは、「フェンス禁止・コメント禁止・末尾カンマ禁止・オブジェクトのみ出力」と明記するだけでエラー率を70〜80%削減できます。
  4. temperatureを下げ、トークン上限を上げる:前者は文章への脱線確率を減らし、後者は切断を減らします。
  5. エラー付きの再試行:検証が失敗したら、壊れた出力と「JSON path + エラーメッセージ」を会話に添えてもう一度要求します。モデルは正確なエラーがあれば概ね自己修正できます。

実務では「structured outputs + 修復フォールバック + スキーマ検証」の3層を重ねて使えば、修復で処理できないシナリオはほぼなくなります。

七、オンラインツールの役割分担:方言変換と修復は別物

当サイトのツールボックスには、このパイプラインに対応する2つの落とし所があり、それぞれ担当範囲が異なります。

  • **方言系の問題(コメント、シングルクォート、末尾カンマ)**はJSON5変換に直接渡します。JSON5と標準JSONの相互変換はまさにこの3種類をカバーし、変換の意味は明確で推測を含みません。入力全体がJSONC/JSON5ファイルなら、「修復」よりも変換のほうが予測しやすくなります。方言自体の取捨選択は「JSON5とJSONCガイド」を参照してください。
  • 修復の後はJSON解析ツールで検証・整形し、エラーを行と列に特定し、修復結果が本当に厳密なパーサーに受け入れられるかを確認します。
  • **ライブラリ系の問題(Pythonリテラル、切断補完、JSONPラップ、markdownフェンス)**は現時点ではコード側のjsonrepair / json-repairに頼る必要があります。ブラウザ側に同等のワンクリック修復はありません。この2種類の修復は「意図の推測」を伴うため、汎用変換ツールに詰め込むよりローカルライブラリのほうが安全です。

手元にあるのが壊れたデータではなくエラーメッセージなら、まず「JSONパースエラーの修り方」でエラーを座標に翻訳してから、手作業で直すか修復するかを判断してください。

よくある質問

JSON修復はデータを壊してしまいませんか?

修復可能な9種類については句読点とラッパーしか変更せず、値には触れません。文字列内部の //、カンマ、波括弧は状態機械が識別してそのまま保持します。ただし切断補完によるオブジェクトはデータが欠け、先頭ゼロ付き数値は文字列になり、NaN の扱いはライブラリごとに異なります。修復後のキーフィールド確認は必須の作業です。

修復と検証はどんな関係ですか?

検証は「どこが不正か」を教えるだけですが、修復は「正当なJSONそのもの」を出します。信頼できるのは両方やる方法です。まず修復し、次に検証する。スキーマ検証で型と必須フィールドを捕捉し、構文検証でパーサーが受け入れることを確認します。検証せずに修復だけするのは、目立つ構文エラーを、より見えにくいデータエラーに交換するのと同じです。

LLMの出力が常に ```json フェンスに囲まれる場合は?

短期的には抽出で対処します。最初の { または [ から最後の } または ] までの内容を取り出してパースします。フェンス剥離に対応した修復ツールなら出力全体をそのまま処理できます。長期的にはstructured outputsか「markdownフェンス禁止」の明示的な指示に頼り、生成段階からフェンスを作らせないことです。

jsonrepairとjson-repair、どちらを選ぶべきですか?

JavaScriptスタックにはnpmのjsonrepair(ストリーミングtransform対応)、PythonスタックにはPyPIのjson-repairを使います。両端で修復するなら意味的に同源の組み合わせ、たとえばjson-repairとそのTS移植版を選び、同一入力に対して両側の修復結果が一致することを保証します。

修復ツールは日本語や全角引用符を処理できますか?

処理できます。日本語入力で打たれた全角引用符(“”)や全角スペース、ファイル先頭のBOMはすべて一般的な修復リストに含まれ、全角引用符は半角に正規化されます。修復後に検証ツールを一度通せば確認できます。