API レスポンスの新旧を比べたいとき、テキスト差分ツールに貼ると地獄を見る。インデントが違う・キーの順番が違う・改行位置が違う、それだけで全行が「差分あり」になる。本当に知りたいのは「どのキーが増えて、どの値が変わったか」という構造の差分なのに。

JSON を構造レベルで比較する差分ツールをぱんだツールズの1機能として作った。整形やキー順の違いは無視して、キーと値の意味的な差分だけを出す。

この記事では、JSON の構造 diff を再帰で実装する方法と、その過程で出てくる「キー順」「配列」の扱いという2つの判断ポイントを解説する。

テキスト diff と構造 diff の違い

まず前提。テキスト diff（diff コマンドや Git の差分）は行単位の文字列比較。だから次の2つは「全然違う」と判定される。

{"name":"taro","age":20}

{
  "age": 20,
  "name": "taro"
}

人間にとっては同じ内容だが、テキストとしては別物。構造 diff は、両方を JSON.parse してからキーと値で比較するので、この2つを「差分なし」と正しく判定できる。整形スタイルやキーの並び順に左右されない、というのが存在意義。

キーの和集合を取って分類する

オブジェクト同士の比較は、「左右どちらかに存在する全キー」を和集合で集めて、各キーを5種類に分類していく。

type DiffType = 'added' | 'removed' | 'changed' | 'unchanged' | 'nested'

function computeJsonDiff(left: JsonValue, right: JsonValue, depth = 0): DiffEntry[] {
  if (isObject(left) && isObject(right)) {
    const allKeys = [...new Set([...Object.keys(left), ...Object.keys(right)])]
    const entries: DiffEntry[] = []
    for (const key of allKeys) {
      const hasLeft = key in left
      const hasRight = key in right

      if (!hasLeft) {
        entries.push({ key, type: 'added', rightValue: right[key], depth })       // 右だけ → 追加
      } else if (!hasRight) {
        entries.push({ key, type: 'removed', leftValue: left[key], depth })       // 左だけ → 削除
      } else if (JSON.stringify(left[key]) === JSON.stringify(right[key])) {
        entries.push({ key, type: 'unchanged', leftValue: left[key], depth })     // 同値 → 変更なし
      } else if (isObject(left[key]) && isObject(right[key])) {
        entries.push({ key, type: 'nested',                                       // 両方オブジェクト → 再帰
          children: computeJsonDiff(left[key], right[key], depth + 1), depth })
      } else if (isArray(left[key]) && isArray(right[key])) {
        /* 配列の扱い（後述） */
      } else {
        entries.push({ key, type: 'changed', leftValue: left[key], rightValue: right[key], depth })
      }
    }
    return entries
  }
  // トップレベルがプリミティブ/配列のときの比較は省略
}

new Set([...keys(left), ...keys(right)]) で重複を除いた全キーを得て、key in left / key in right の有無で「追加」「削除」を判定。両方にあれば値を比べる。depth を再帰のたびに +1 して持ち回ることで、後段の表示でネストのインデントを付けられる。

判断1：深い等価判定は JSON.stringify で済ませる（キー順の罠）

「値が同じか」をどう判定するか。オブジェクトや配列をネストまで含めて厳密に比較する deep equal を自前で書いてもいいが、ここでは JSON.stringify(a) === JSON.stringify(b) で済ませている。手軽で、ネストの深さに関係なく一発で比較できる。

ただし JSON.stringify にはキー順に敏感という弱点がある。{"a":1,"b":2} と {"b":2,"a":1} は内容が同じでも、stringify すると文字列が変わって「不一致」と出る。

これが問題にならないのは、分類の順序のおかげ。あるキーの値同士を比べるとき、unchanged 判定（stringify 比較）で外れても、次の「両方オブジェクトなら nested で再帰」のブランチに落ちる。再帰した先では、また和集合でキーを突き合わせるので、キーの順番が違っても各キーは正しくマッチする。たとえば {"user":{"a":1,"b":2}} と {"user":{"b":2,"a":1}} を比べると、user の値は「stringify では不一致 → nested 再帰 → 中の各キーは unchanged」となり、最終的に差分ゼロに落ち着く。

つまり JSON.stringify の雑な等価判定を、再帰がセーフティネットとして補正している。トップで stringify が一致すれば即 unchanged（速い）、外れても再帰で正しく評価される（正確）、という二段構え。手軽さと正しさを両立させた割り切り。

判断2：配列は「インデックスをキーにしたオブジェクト」として扱う

配列の diff は本質的に難しい。要素が1つ挿入されただけで以降が全部ズレるので、厳密にやるなら LCS（最長共通部分列）のようなアルゴリズムが要る。このツールは、そこは割り切ってインデックスをキーにしたオブジェクトに変換し、同じ位置同士で比較している。

} else if (isArray(left[key]) && isArray(right[key])) {
  // [a, b, c] を {"0":a, "1":b, "2":c} に変換して位置で比較
  const leftObj: JsonObject = {}
  const rightObj: JsonObject = {}
  const leftArr = left[key] as JsonArray
  const rightArr = right[key] as JsonArray
  const maxLen = Math.max(leftArr.length, rightArr.length)
  for (let i = 0; i < maxLen; i++) {
    if (i < leftArr.length) leftObj[String(i)] = leftArr[i]
    if (i < rightArr.length) rightObj[String(i)] = rightArr[i]
  }
  entries.push({ key, type: 'nested',
    children: computeJsonDiff(leftObj, rightObj, depth + 1), depth })
}

配列を {"0": ..., "1": ...} というオブジェクトに変換してしまえば、あとはオブジェクト比較の再帰にそのまま乗せられる。短い方を超えたインデックスは「片方にしか無いキー」になるので、自動的に added / removed として扱われる。コードが増えないのが利点。

トレードオフは明確で、これは位置ベースの比較。配列の先頭に要素を挿入すると、以降の全要素が「変更」と判定される。「同じ要素が移動した」は検出できない。だが API レスポンスや設定ファイルの比較という用途では、位置ベースで十分実用になる。LCS を実装する複雑さに見合わない、という判断。割り切りを明示しておくのが大事で、「配列はインデックス対応で比較」と FAQ にも書いてある。

集計も再帰で

差分の件数（追加 N・削除 M・変更 K）も、ツリーを再帰でたどって数える。nested に当たったら子の集計を足し込むだけ。

function countDiff(entries: DiffEntry[]): DiffSummary {
  const summary = { added: 0, removed: 0, changed: 0 }
  for (const entry of entries) {
    if (entry.type === 'added') summary.added++
    else if (entry.type === 'removed') summary.removed++
    else if (entry.type === 'changed') summary.changed++
    else if (entry.type === 'nested' && entry.children) {
      const child = countDiff(entry.children)   // 子を再帰集計して合算
      summary.added += child.added
      summary.removed += child.removed
      summary.changed += child.changed
    }
  }
  return summary
}

diff のデータ構造をツリーで持っておくと、表示も集計も同じ再帰パターンで書けるので、ロジックがきれいに揃う。

まとめ

構造的な JSON diff は、再帰さえ押さえればコンパクトに書ける。ただし2つの判断が要る。

テキスト diff と違い、JSON.parse してキー・値で比較するので整形・キー順に左右されない
オブジェクトはキーの和集合を取り、added / removed / unchanged / nested / changed に分類
深い等価判定は JSON.stringify で手軽に。キー順に弱いが、外れたら nested 再帰が補正する二段構え
配列はインデックスをキーにしたオブジェクト化してオブジェクト比較に合流。位置ベースの割り切り（LCS はやらない）と明示する
表示も集計も同じツリーを再帰でたどる

「テキストの差分」と「構造の差分」は別問題で、JSON のように構造を持つデータは後者で比べるべき、という当たり前を、再帰で素直に実装できた題材だった。

ぱんだツールズ では他にも PDF・画像・CSV・テキスト処理など、開発者向けのツールを多数公開している。全部無料・登録不要・ブラウザ完結で使える。
https://sakutto-panda.com

この記事は Zenn にも同じ内容を投稿しています。