JSON Patch 產生器

比較兩份 JSON 文件,得到把前者變成後者的 RFC 6902 修補內容。全部在瀏覽器中執行。

這個工具做什麼


它比較兩份 JSON 文件,按 RFC 6902 定義的格式寫出把前者變成後者的操作清單。不必為了說明一個欄位變了而傳送整份文件,你傳送的就是變動本身。

什麼時候用


用來組出 PATCH 請求的主體,用來記錄設定檔兩個版本之間改了什麼,或者用來保存一份遠比逐份完整副本小得多的稽核紀錄。它也是一種快速手段,能查出兩份看起來一樣的文件究竟差在哪裡。

它會產生哪些操作


操作含義
add在原本沒有值的位置加上一個值,或者插入到陣列中。
remove刪除該位置上的值。
replace覆寫一個已經存在的位置上的值。
move把一個值從一個位置移到另一個位置。
copy把一個值複製到另一個位置。
test檢查一個值,若不符則整份修補內容作廢。

這個工具只寫 add、remove 與 replace。這三種足以表達任何變動,而一份能逐行讀懂的修補內容,比一份更短卻要費神琢磨的更有價值。另外三種同樣屬於 RFC 6902,符合規範的伺服器都會接受。

路徑是怎麼回事


每個路徑都是一個 JSON Pointer(RFC 6901):從文件根部開始、用斜線分隔的一條路線,「/address/zipCode」指的是 address 裡面的 zipCode 欄位。陣列位置用數字表示,所以「/skills/0」是第一項,而短橫線表示陣列結尾:「/skills/-」是附加。由於斜線是分隔符號,鍵名中若含有斜線就寫成 ~1,真正的波浪號寫成 ~0。

關於輸出的說明


比較是按字面進行的:逐個位置對比取值,因此在陣列開頭插入一項,會對後面每一項都產生一個 replace,而不是一次插入。對於帶有穩定識別碼的物件陣列,依識別碼產生的修補內容總是比依位置產生的更小。

如何產生 JSON Patch


貼上兩份 JSON 文件並產生修補內容。

  1. 把原始 JSON 貼到左邊。
  2. 把修改後的 JSON 貼到右邊。
  3. 按下「產生」,然後複製修補內容。

常見問題


這個工具會上傳我的資料嗎?
不會。兩份文件都留在你的瀏覽器裡,修補內容在你自己的電腦上產生。

輸出符合 RFC 6902 嗎?
符合。每個操作都是一個帶 op、path 的物件,add 與 replace 還帶 value,而路徑就是 RFC 6901 定義的 JSON Pointer。

它包含 move 與 copy 操作嗎?
不包含。它只寫 add、remove 與 replace,這三種足以表達任何變動,而且讀起來容易得多。一次 move 不過是 remove 之後接一個 add。

修補內容怎麼套用?
把它送給接受 application/json-patch+json 的 API,或者用現成的函式庫:Python 用 jsonpatch,JavaScript 用 json-patch,.NET 用 JsonPatchDocument,Java 用 json-patch,諸如此類。

它和 JSON Merge Patch 有什麼差別?
JSON Merge Patch(RFC 7386)看起來就像文件本身,其中 null 表示「刪除」。這讓它易讀,卻無法保存一個真正的 null,也無法只改陣列中的某一項。JSON Patch 更囉嗦,但什麼都能表達。

Wikipedia — JSON Patch
Wikipedia — JSON
Wikipedia — Patch (computing)
Wikipedia — Diff
Wikipedia — REST