Tanto el puntero JSON como JSONPath abordan ubicaciones dentro de un documento JSON, y
ambos aparecen en los mismos tipos de herramientas: $ref en JSON Schema, operaciones
PATCH, diferencias basadas en rutas. Resuelven problemas diferentes, y saber cual
de los dos necesita una tarea determinada evita elegir la herramienta equivocada.
Puntero JSON: una ubicacion, RFC 6901
Un puntero 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. Dos caracteres necesitan ser escapados dentro de un token (~1 para
un / literal, ~0 para un ~ literal), y la cadena vacia como puntero
significa todo el documento. Esa es toda la gramatica. Un puntero resuelve a
exactamente un valor, o falla, sin nada en medio: no hay comodin, no hay filtro, no hay
forma de coincidir con mas de la ubicacion que nombra.
{ "user": { "name": "Ada", "roles": ["admin", "editor"] } }/user/name resuelve a "Ada". /user/roles/1 resuelve a "editor".
/user/email falla, porque esa clave no existe. Nada en la
sintaxis del puntero puede pedir “todos los roles” en una sola expresion; el llamador
ya tiene que conocer el indice.
JSONPath: un lenguaje de consultas
JSONPath, estandarizado como RFC 9535, esta disenado para coincidir, no solo
para direccionar. $.user.roles[*] devuelve ambos roles en el ejemplo anterior en
una sola consulta. $..email busca en cada nivel del documento cualquier clave
llamada email, sin importar que tan profundo este anidada. Expresiones de filtro como
$.items[?(@.price > 100)] seleccionan elementos del arreglo por una condicion sobre su
propio contenido. Una consulta JSONPath puede devolver cero coincidencias, una, o muchas, lo cual
es un contrato fundamentalmente diferente al resolver-o-fallar de un puntero.
La diferencia practica
Un puntero nombra una ubicacion que ya conoces. Una consulta JSONPath describe una condicion y le permite al motor encontrar lo que la satisface. Esa diferencia determina cual se ajusta a un trabajo determinado:
- Ya sabes exactamente que valor quieres (“el tercer elemento del arreglo de direccion de envio”): usa un puntero. Es mas simple, tiene un significado unico por documento, y todas las implementaciones coinciden en lo que hace, ya que la RFC deja poco espacio para diferencias de dialecto.
- Estas buscando valores que coincidan con una condicion, o no conoces
la ruta exacta de antemano (“cada objeto con un
statusdefailed, donde sea que aparezca”): recurre a JSONPath. Aqui es donde las diferencias de dialecto empiezan a importar: las implementaciones de JSONPath varian mas de lo que sugieren los propios ejemplos de la RFC 9535, por lo que una consulta escrita para una libreria no esta garantizada a comportarse identicamente en otra.
Donde aparece cada uno en la practica
Las operaciones de JSON Patch (RFC 6902) usan punteros exclusivamente; cada "path"
en una operacion add, remove, replace o move es un puntero JSON,
porque una operacion de parche apunta a una ubicacion exacta por diseno. La
palabra clave $ref de JSON Schema tambien resuelve via sintaxis de puntero, por la misma
razon: una referencia de esquema apunta a una definicion, no a un conjunto de ellas.
JSONPath aparece donde una persona o herramienta necesita consultar un documento
interactivamente: depurando una respuesta de API grande, extrayendo un campo de
registros, o construyendo una regla que debe coincidir con cualquier documento con una
forma dada sin importar exactamente donde se encuentra el campo relevante.
Probando ambos
El Evaluador de Puntero JSON resuelve un puntero contra un documento y, en una busqueda fallida, reporta hasta donde llego y que claves realmente existen en ese punto, en lugar de un simple “no encontrado”. El Probador JSONPath ejecuta el subconjunto documentado de la RFC 9535 con extensiones de funciones, y la hoja de trucos JSONPath del blog de este sitio tiene un ejemplo practico para cada selector que vale la pena conocer. Como usar el puntero JSON cubre la sintaxis del puntero en mayor profundidad, incluyendo los escapes.