JSON Pointer, RFC 6901, es una pequena especificacion: cuatro paginas, una
sintaxis, sin ambiguedad sobre lo que significa un camino. Aparece donde
algo necesita referenciar una ubicacion exacta dentro de un documento JSON
sin inventar su propio lenguaje de caminos, mas comunmente dentro de JSON
Patch y la palabra clave $ref de JSON Schema.
La sintaxis, brevemente
Un pointer es una secuencia de tokens separados por /. /user/name significa
la clave name dentro del objeto user. /items/0 significa el primer
elemento del arreglo items. La cadena vacia, un pointer sin ningun token,
significa todo el documento. Dos caracteres necesitan escape dentro de un
token: ~1 representa un / literal, y ~0 representa un ~ literal,
siempre leidos en ese orden para que ~01 signifique ~1 en lugar de /.
Usar el evaluador de JSON Pointer
Pega un documento, escribe un pointer, y presiona Resolver. Dado
{"a/b":{"c~d":42},"list":["x","y"]}el pointer /a~1b/c~0d resuelve a traves de una clave que literalmente
contiene una barra y una clave que literalmente contiene un tilde, devolviendo
42. Esa es toda la razon por la que existen los escapes: sin ellos, una
clave que contiene el caracter separador seria imposible de direccionar.
Que te dice una busqueda fallida
La mayoria de las herramientas reportan un pointer fallido como un simple
“no encontrado”, lo cual no es suficiente para corregirlo en un documento con
mas de unas pocas claves. Este te dice hasta donde llego el pointer, que
encontro ahi, y que claves tiene realmente el objeto. Pedir /a~1b/nope
contra el mismo documento devuelve:
No hay clave “nope” en el objeto aqui, tiene c
d. Resuelto hasta /a1b
Eso es suficiente para ver el error de escritura inmediatamente, en lugar de releer todo el documento para adivinar que salio mal.
El guion, y por que no resuelve
Dentro de JSON Patch, un guion como el ultimo token de un pointer hacia un
arreglo significa “la posicion despues del ultimo elemento”, usado para
agregar. Por si solo, resolver /items/- contra un documento no nombra un
valor existente, porque aun no hay nada ahi a lo que apuntar. El evaluador
explica esta distincion en lugar de tratarla como un error de parseo generico.
Donde esto difiere de JSONPath
JSON Pointer nombra una ubicacion y resuelve a exactamente un valor o falla. JSONPath es un lenguaje de consultas que puede coincidir con muchos valores a la vez, con comodines, filtros y porciones. Usa un pointer cuando ya sabes exactamente que valor quieres; usa JSONPath cuando estas buscando valores que coincidan con una condicion.