Názov kľúča ešte nie je cesta
Predstavte si objekt JSON s kľúčom draft/a~b, ktorého hodnota obsahuje ďalší objekt s položkou state. Lomka patrí do názvu kľúča; nevytvára ďalšiu úroveň vnorenia. JSON Pointer naopak označuje hodnotu segmentmi oddelenými lomkami. Cesta /orders/0/item môže smerovať na položku poľa, kde 0 je jej index. Ak bez úpravy vložíte surový názov kľúča do cesty, môžete označiť iné miesto alebo dostať chybu.
Norma RFC 6901 určuje dve únikové sekvencie vnútri každého segmentu: vlnovka sa zmení na ~0 a lomka na ~1. Pred každým segmentom úplného pointera je tiež lomka; prázdny pointer označuje celý dokument. Tento zápis sa týka adresy, nie obsahu vyhľadávanej hodnoty, a pôvodný objekt JSON nemení. Nástroj na escapovanie segmentu použite pri zostavovaní cesty z názvov získaných z údajov alebo od používateľa.
Zostavte príklad po segmentoch
Pri kľúči draft/a~b nahraďte najprv vlnovku za ~0 a potom lomku za ~1. Dostanete segment draft~1a~0b. Pridajte úvodnú lomku a samostatnú položku state: výsledná cesta je /draft~1a~0b/state. Vložený prevodník nižšie vykonáva krok pre jeden segment. Úvodnú lomku zámerne nepridáva, pretože segment môžete potrebovať na inom mieste dlhšej cesty. Jeho výsledok porovnajte s tromi krokmi na obrázku.
Opačný nástroj najprv mení ~1 na lomku a až potom ~0 na vlnovku. Poradie je dôležité: ak by sa ~01 zmenilo na ~1 a následne ešte raz na lomku, pôvodný názov by sa poškodil. Segment JSON Pointer navyše nie je percentové kódovanie URL. Ak pointer vložíte do fragmentu webovej adresy, vonkajšia vrstva má ďalšie pravidlá. Pri hľadaní chyby v odkaze alebo API oddeľte syntax pointera od syntaxe URL.
- Pôvodný kľúč: draft/a~b
- Escapovaný segment: draft~1a~0b
- Celá cesta: /draft~1a~0b/state
Čo vytvorí sploštenie
Nástroj na sploštenie prejde objekt JSON a koncové hodnoty zapíše pod kľúče, ktoré vyzerajú ako celé cesty JSON Pointer. Ak je state pod kľúčom draft/a~b, plochá položka bude /draft~1a~0b/state s rovnakou koncovou hodnotou. Taký pohľad uľahčuje porovnávanie, výpis alebo export vnorených dát. Opačný nástroj načíta kľúče ciest a objekt znovu zostaví, pokiaľ si cesty neodporujú. Plochá položka je však stále len členom objektu JSON, nie vykonaným vyhľadaním.
Tento nástroj považuje polia za koncové hodnoty a nevypisuje osobitne ich položky /0 a /1. Prázdne objekty sú tiež koncové. Všeobecný JSON Pointer vie označiť index poľa, no tento konkrétny plochý výpis ho nerozpisuje. Ak jedna cesta priradí jednoduchú hodnotu na /a a druhá žiada pod ňou /a/b, spätný prevod musí konflikt odmietnuť. Pred ručným zásahom do kľúčov si ponechajte pôvodný JSON.
Postup pri práci s cestami
Začnite platným JSON a rozhodnite sa, či potrebujete jednu adresu alebo kompletný plochý pohľad. Pri jednej adrese rozdeľte zamýšľanú trasu na skutočné názvy členov, každý názov samostatne escapujte a segmenty spojte úvodnými lomkami. Neescapujte celý pointer naraz: jeho oddeľovacie lomky by sa zmenili na časť názvu. Ak chcete preskúmať mnoho koncových hodnôt, sploštite objekt a pred odovzdaním inému systému skontrolujte vytvorené kľúče.
Pri obnove údajov overte, že sa každý plochý kľúč začína lomkou a používa platné sekvencie ~. Sledujte opakované alebo odporujúce si priradenia, polia ponechané vcelku a doslovné názvy s bodkami či lomkami. Vyskúšajte spätný prevod na malom objekte s oboma špeciálnymi znakmi a porovnávajte spracované štruktúry JSON, nie odsadenie. Norma určuje syntax pointera; presná politika splošťovania je vlastnosťou tohto miestneho nástroja.