Název klíče ještě není cesta
Představte si objekt JSON s klíčem draft/a~b, jehož hodnota obsahuje další objekt s položkou state. Lomítko patří do názvu klíče; nevytváří další úroveň zanoření. JSON Pointer naproti tomu označuje hodnotu segmenty oddělenými lomítky. Cesta /orders/0/item může mířit na položku pole, kde 0 představuje její index. Pokud bez úpravy vložíte syrový název do cesty, můžete označit jiné místo nebo vyvolat chybu.
Norma RFC 6901 stanoví dvě únikové sekvence uvnitř každého segmentu: vlnovka se mění na ~0 a lomítko na ~1. Před každým segmentem úplného pointeru stojí lomítko; prázdný pointer označuje celý dokument. Tento zápis se týká adresy, nikoli obsahu hledané hodnoty, a původní objekt JSON nemění. Nástroj pro escapování segmentu použijte při skládání cesty z názvů získaných z dat nebo od uživatele.
Sestavte příklad po segmentech
U klíče draft/a~b nahraďte nejprve vlnovku za ~0 a potom lomítko za ~1. Dostanete segment draft~1a~0b. Přidejte úvodní lomítko a samostatnou položku state: výsledná cesta je /draft~1a~0b/state. Vložený převodník níže provádí krok pro jediný segment. Úvodní lomítko záměrně nepřidává, protože segment můžete potřebovat jinde v delší cestě. Jeho výsledek porovnejte se třemi kroky v nákresu.
Opačný nástroj nejprve mění ~1 na lomítko a teprve potom ~0 na vlnovku. Pořadí je důležité: kdyby se ~01 změnilo na ~1 a následně znovu na lomítko, původní název by se poškodil. Segment JSON Pointer navíc není procentové kódování URL. Jestliže pointer vložíte do fragmentu webové adresy, tato vnější vrstva má další pravidla. Při hledání chyby v odkazu nebo API oddělte syntaxi pointeru od syntaxe URL.
- Původní klíč: draft/a~b
- Escapovaný segment: draft~1a~0b
- Celá cesta: /draft~1a~0b/state
Co vytváří zploštění
Nástroj pro zploštění projde objekt JSON a koncové hodnoty zapíše pod klíče, které vypadají jako celé cesty JSON Pointer. Pokud je state pod klíčem draft/a~b, plochá položka bude /draft~1a~0b/state se stejnou koncovou hodnotou. Takový pohled usnadňuje srovnání, výpis nebo export vnořených dat. Opačný nástroj přečte klíče cest a objekt znovu sestaví, pokud si cesty neodporují. Plochá položka je však stále jen členem objektu JSON, nikoli provedeným vyhledáním.
Tento nástroj pokládá pole za koncové hodnoty a nevypisuje zvlášť jejich položky /0 a /1. Prázdné objekty jsou rovněž koncové. Obecný JSON Pointer může označit index pole, ale tento konkrétní plochý výpis jej nerozepisuje. Pokud jedna cesta přiřadí jednoduchou hodnotu na /a a jiná vyžaduje pod ní /a/b, zpětný převod musí konflikt odmítnout. Před ručními změnami klíčů si uschovejte původní JSON.
Postup pro práci s cestami
Začněte platným JSON a rozhodněte, zda potřebujete jednu adresu nebo celý plochý pohled. Pro jedinou adresu rozdělte zamýšlenou trasu na skutečné názvy členů, každý název zvlášť escapujte a segmenty spojte úvodními lomítky. Neescapujte celý pointer naráz: jeho oddělovací lomítka by se změnila na součást názvu. Chcete-li prohlédnout mnoho koncových hodnot, zploštěte objekt a před předáním jinému systému zkontrolujte vytvořené klíče.
Při obnově dat ověřte, že každý plochý klíč začíná lomítkem a používá platné sekvence ~. Sledujte opakovaná nebo rozporná přiřazení, pole ponechaná pohromadě a doslovné názvy s tečkami či lomítky. Zkuste zpětný převod na malém objektu s oběma zvláštními znaky a porovnávejte zpracované struktury JSON, nikoli odsazení. Norma určuje syntaxi pointeru; přesná politika zploštění je vlastností tohoto místního nástroje.