CDRN

Porovnať dve JSON štruktúry

  • Dashboard
  • Dokumentácia
  • API
porovnáva dve JSON štruktúry a vypisuje pridania, odstránenia a zmeny kľúč po kľúči

Prečo porovnávať dva JSON?

Porovnávanie dvoch JSON štruktúr sa pravidelne vracia v živote vývojára. API odpoveď, ktorá sa zmení po aktualizácii. Konfiguračný súbor, ktorý sa rozchádza medzi dvomi prostrediami. Export objektov, ktorý sa musí zarovnať s referenciou. JSON diff presne odpovedá na túto otázku: čo bolo pridané, odstránené alebo modifikované, a na ktorom mieste?

Riadok po riadku diff (v štýle git diff) často nestačí. Ak formátovanie sa líši (medzery, poradie kľúčov), textový diff signalizuje stovky riadkov, kým štruktúra dát je identická. JSON komparátor pracuje na parsovanej štruktúre, čo eliminuje tento šum a odhaľuje iba sémantické rozdiely.

Formát diffu produkovaného nástrojom

Pre každý rozdiel nástroj vracia:

  • cestu v zjednodušenom JSONPath formáte, napríklad $.user.address[0].city;
  • typ medzi added (pridané vpravo), removed (prítomné iba vľavo), modified (odlišné hodnoty);
  • ľavú hodnotu a/alebo pravú hodnotu podľa typu.

Prázdny diff znamená, že dva JSON sú štrukturálne identické, nezávisle od ich formátovania alebo poradia kľúčov.

Ako algoritmus prechádza dvoma štruktúrami

Algoritmus je rekurzívny. Na každej úrovni identifikuje typ dvoch porovnávaných hodnôt:

  • Ak sú obe asociatívne objekty, berie zjednotenie kľúčov. Pre každý kľúč zostupuje rekurzívne, alebo označuje added/removed, ak kľúč existuje iba na jednej strane.
  • Ak sú obe usporiadané polia, porovnáva pozíciu po pozícii. Rozdiel na začiatku poľa môže posunúť celý zvyšok, čo produkuje verbose diff: je to akceptovaný limit naivného štrukturálneho diffu.
  • Ak sa typy líšia (objekt oproti poľu, skalár oproti null), označuje sa modified.
  • Ak sú obe hodnoty skaláre (reťazec, číslo, boolean, null), stačí jednoduché striktné porovnanie.

Poradie kľúčov v objekte sa nepočíta: {"a": 1, "b": 2} a {"b": 2, "a": 1} produkujú prázdny diff. Je to v súlade s JSON sémantikou, kde poradie nie je významné. Naopak, poradie prvkov poľa sa počíta: pole je konštrukčne usporiadané.

Konkrétny príklad

Tu sú dve verzie užívateľského objektu: 

// lava strana
{
  "id": 42,
  "name": "Alice",
  "roles": ["admin", "editor"]
}

// prava strana
{
  "id": 42,
  "name": "Alice Martin",
  "roles": ["admin", "viewer"],
  "active": true
}

Produkovaný diff:

  • $.name: modified, "Alice" → "Alice Martin"
  • $.roles[1]: modified, "editor" → "viewer"
  • $.active: added, true

Prípady použitia

  • Diff prostredí: porovnať výstup endpointu v pre-produkcii a produkcii. Veľmi užitočné pri migrácii alebo obnovovaní cache.
  • Audit migrácie: porovnať export pred a po transformácii pre overenie, že žiadne pole nebolo stratené.
  • API regresia: pred a po modifikácii porovnať odpoveď pre identický dotaz. Prázdny diff potvrdzuje neregresiu.
  • Synchronizácia konfigurácií: porovnať composer.json medzi dvomi branchami, dve .eslintrc súbory, dve Symfony konfigurácie.
  • Snapshot testy: nahradiť riadok po riadku porovnanie štrukturálnym porovnaním v sade integračných testov.

Limity štrukturálneho diffu

Porovnávanie usporiadaných polí je známym limitom naivných štrukturálnych diffov. Ak vložíme prvok na začiatok poľa, všetky nasledujúce pozície sú posunuté a diff signalizuje každý rozdiel ako modifikáciu. Pre takéto prípady existujú pokročilejšie algoritmy (Myers, Patience, diff podľa prirodzeného kľúča), ale vychádzajú z rámca všeobecného porovnávacieho nástroja.

Diff nehovorí ani prečo k zmene došlo: je to konštatovanie. Pre analýzu regresie treba krížiť toto konštatovanie s commitmi, nasadeniami a parametrami požiadavky.

JSON diff vs JSON Patch (RFC 6902)

Komplementárny formát je JSON Patch (RFC 6902). Opisuje vo forme operácií (add, remove, replace, move, copy, test), ako transformovať JSON dokument na iný. Tam, kde je náš diff konštatovanie (ľudské), JSON Patch je recept (strojový). Dve reprezentácie sú ekvivalentné pre jednoduché prípady a JSON Patch je užitočný pre RESTful API akceptujúce čiastočné modifikácie.

Často kladené otázky

Závisí diff od poradia kľúčov?

Nie: pre JSON objekt nie je poradie významné. Komparátor produkuje rovnaký výsledok, či sú kľúče zoradené alebo nie.

Ako spravovať polia, ktorých poradie nie je dôležité?

Nástroj defaultne považuje polia za usporiadané (je to JSON sémantika). Ak spracovávate množiny, zoraďte obe polia podľa prirodzeného kľúča pred porovnaním, alebo použite špecializovaný porovnávací servis zohľadňujúci túto sémantiku.

Aký je rozdiel od Git diffu?

Git porovnáva textové riadky. Ak sa odsadenie alebo poradie kľúčov líši, Git diff je veľmi verbose. JSON diff pracuje na parsovanej štruktúre a signalizuje iba dátové rozdiely.

Je akceptovaný nevalidný JSON?

Nie: ak jeden z dvoch JSON neparsuje, nástroj vracia chybu. Validujte najprv naším JSON validátorom.

Ukážka požiadavky

curl -X POST https://cdrn.fr/api/v1/tools/json-diff/execute \
  -H "Content-Type: application/json" \
  -d '{"left":"...","right":"..."}'

Vstupná schéma

Pole Typ Povinné Predvolené
left text ✓ –
right text ✓ –

Koncové body

  • GET https://cdrn.fr/api/v1/tools - vypíše všetky dostupné nástroje
  • GET https://cdrn.fr/api/v1/tools/json-diff - získa schému tohto nástroja
  • POST https://cdrn.fr/api/v1/tools/json-diff/execute - spustí tento nástroj s JSON payloadom