JSON Pointer: adresování hodnot

Adresa jedné hodnoty

Každý segment začíná lomítkem. Prázdný pointer je kořen, zatímco / označuje člen objektu s prázdným názvem. Číselný segment je index jen tehdy, když aktuální hodnota je pole; v objektu může být "0" obyčejný název.

{"a/b":{"m~n":"hodnota"}}

/a~1b/m~0n

Escapování ~0 a ~1

Uvnitř názvu se ~ zapisuje jako ~0, / jako ~1. Při kódování nahraď nejprve vlnovky a potom lomítka; při dekódování nejprve ~1 a potom ~0. Jinak by se název ~1 dekódoval chybně.

Když je pointer zapsaný jako JSON string, přidej také obvyklé escapování JSON. To je jiná vrstva než escapování segmentů.

URI fragment

Fragment začíná znakem # a používá percent encoding po převodu pointeru na UTF-8. Například vlastnost a b má pointer /a b a fragment #/a%20b. Při čtení dekóduj percent encoding před segmenty pointeru.

Ne každý JSON dokument automaticky podporuje fragmenty jako JSON Pointer; rozhoduje definice média nebo aplikace. V JSON Schema se lokální $ref s takovým fragmentem používá k adresování dílčího schématu.

Chyby a speciální index

Index pole nesmí mít úvodní nuly: 01 není index 1. Hodnota - adresuje pozici za koncem pole, která sama neexistuje; JSON Patch ji používá při přidávání. U běžného vyhodnocení pointeru nelze získat hodnotu za koncem.

Chybějící cesta je chyba vyhodnocení, kterou zpracuje aplikace. Nepovažuj ji za null. Pro výběr více hodnot použij JSONPath.

Jeden dokument, šest adres a chybějící hodnota

{"":{"0":"prázdný klíč"},"a/b":{"m~n":"hodnota"},"polozky":[{"id":"001"}],"telefon":null}

• Prázdný pointer vrátí celý kořenový objekt.
• / vrátí objekt s vlastností 0; //0 vrátí text prázdný klíč.
• /a~1b/m~0n vrátí hodnota.
• /polozky/0/id vrátí řetězec 001.
• /telefon vrátí existující null.
• /polozky/1 selže: druhá položka neexistuje. Nesmí se zaměnit za existující null.

const encodeToken = text => text.replaceAll("~", "~0").replaceAll("/", "~1");
const decodeToken = text => {
  if (/~(?![01])/.test(text)) throw new Error("Neplatný escape tokenu");
  return text.replaceAll("~1", "/").replaceAll("~0", "~");
};
console.log(encodeToken("a/b~c")); // a~1b~0c
console.log(decodeToken("~01"));   // ~1, nikoli /

Uživatelský pointer nepoužívej jako neomezený přístup k objektu aplikace. Vyhodnocuj jej nad parsovaným JSON a vlastními členy, ověř index pole a limit délky. Pokud pointer slouží ke změně dat, přidej autorizaci cílové cesty, nikoli pouze kontrolu jeho syntaxe. Přesnou definici dává RFC 6901.