Puntero JSON: evaluador de punteros RFC 6901

Qué es un puntero JSON

Un puntero JSON es una cadena corta que nombra exactamente un lugar dentro de un documento JSON. Es una sucesión de tokens, cada uno introducido por una barra, de modo que /paths/~1users/get baja desde la raíz al miembro llamado paths, luego al llamado /users y luego a get. El RFC 6901 lo define en ocho páginas, y es lo que usan JSON Patch, las referencias de JSON Schema y OpenAPI para decir a qué se refieren.

La palabra clave es exactamente. Un puntero nombra un sitio, y o está o no está, que es lo que lo separa de JSONPath, donde una sola consulta puede devolver cien nodos o ninguno y donde distintas implementaciones devuelven conjuntos distintos. En un puntero no hay nada sobre lo que discrepar, y por eso lo eligieron los formatos que necesitan no ser ambiguos.

Esa gramática mínima tiene más aristas de las que parece, y esta herramienta las enseña todas. Pega un documento, escribe un puntero, y lo evalúa token a token: en qué se buscó cada uno, qué encontró y, cuando no encontró nada, qué regla lo detuvo.

Cómo se usa

1. Pega un documento. Arranca con el documento de ejemplo de la norma, así que cualquier respuesta se puede contrastar con el propio RFC 6901. Si lo que pegas no es JSON válido, se te dice en lugar de adivinarlo.
2. Escribe un puntero. La cadena vacía nombra el documento entero; lo demás empieza por barra. Dentro de un token, la virgulilla se escribe ~0 y la barra ~1. O elige uno de la lista con todos los punteros de tu documento que aparece abajo.
3. Lee la traza. Cada fila muestra un token, si se buscó en un objeto o en un array, y qué devolvió. Un fallo nombra la regla concreta en vez de limitarse a no dar nada.

La regla de escape y el orden en que debe aplicarse

Dos caracteres no pueden aparecer tal cual dentro de un token. La barra abriría un token nuevo y la virgulilla es el carácter de escape, así que se escriben ~1 y ~0. Ese es todo el sistema de escape, y es más pequeño de lo que la gente espera: no hay barra invertida, ni codificación por ciento, ni ningún otro escape. Una virgulilla seguida de algo que no sea 0 o 1 no es un puntero válido.

Lo interesante es el orden. Al descodificar hay que convertir ~1 en barra primero y ~0 en virgulilla después. Al revés, ~01 se convierte en ~1 y luego en una barra, cuando la respuesta correcta son los dos caracteres ~1. La norma dedica un párrafo entero a eso y nombra el resultado equivocado de forma explícita, lo que suele indicar que las implementaciones reales se equivocan. Esta herramienta descodifica en una sola pasada, así que el peligro no se evita recordando un orden: sencillamente no puede darse.

Al codificar ocurre lo mismo del revés: hay que escapar antes la virgulilla y después la barra, o un nombre que contenga una barra produce un token que se descodifica como otra cosa. La herramienta escapa sobre la marcha por ese mismo motivo.

Cuatro reglas que sorprenden

Un índice de array no puede llevar cero a la izquierda. La gramática admite un cero suelto, o un dígito del uno al nueve seguido de los dígitos que sean, y nada más: /foo/01 es un error de sintaxis y no el índice uno. Aquí es justo donde una implementación en JavaScript se tuerce, porque las dos maneras obvias de leer un número lo aceptan: una convierte el texto 01 en el número uno y la otra saca un número del principio de 1abc y tira el resto. Ninguna es lo que dice la gramática.

Una barra sola no es un puntero vacío. Es un token cuyo nombre es la cadena vacía, así que apunta al miembro llamado nada en absoluto, un nombre de miembro perfectamente legal en JSON y que el documento de ejemplo de la norma incluye precisamente por esto. El puntero vacío, sin ningún carácter, es el que nombra el documento entero.

El carácter suelto - nombra la posición siguiente al último elemento de un array. No es un índice y nunca hay un valor ahí; existe para que JSON Patch pueda decir añade aquí. Darlo como error sería incorrecto y devolver un valor sería mentir, de modo que la herramienta le da su propia respuesta.

Los nombres de miembro se comparan por punto de código, y la norma dice sin rodeos que no se aplica ninguna normalización Unicode. Dos formas de la misma letra acentuada — una compuesta en un solo carácter, otra escrita como letra más marca combinante — se ven idénticas en pantalla y son miembros distintos. Si un puntero que parece correcto se niega a resolver, conviene mirar eso antes que nada.

La forma de fragmento y lo que no significa

Un puntero también puede escribirse dentro de un fragmento de URI, y la norma repite los mismos doce ejemplos en esa forma: el puntero se codifica en UTF-8 y todo lo que un fragmento no admite se codifica por ciento, así que el signo de porcentaje pasa a %25 y el espacio a %20. La herramienta muestra esa versión de lo que escribas y te deja copiarla.

Y entonces llega la frase que casi nadie esperaría, en la misma sección donde se imprimen esos ejemplos: la sintaxis de identificador de fragmento de application/json no es el puntero JSON. Un tipo de medio tiene que declarar el puntero JSON como su sintaxis de fragmento, y el JSON a secas nunca lo hizo. Así que una URL terminada en un puntero significa algo dentro de un JSON Schema o de una referencia de OpenAPI, donde el formato lo dice, y es puro adorno en un .json corriente, donde nada le da ese sentido.

Conviene decir también hasta dónde llega la herramienta. Evalúa punteros y no aplica parches; el RFC 6902 se apoya en esta gramática para añadir, quitar y mover valores, y eso es otro trabajo. Opera sobre el documento que pegas, sin seguir referencias hacia otros archivos. Y es estricta a propósito: donde una biblioteca podría aceptar en silencio un cero a la izquierda o una virgulilla suelta, aquí se te dice qué regla se rompió, porque un puntero que funciona en una implementación y falla en otra es justo el problema que viene a evitar.

¿Por qué es gratis?

Recorrer un documento token a token son unos cientos de líneas de manejo de cadenas, y tu navegador lo hace mientras escribes. Ningún servidor ve tu JSON, así que no hay nada que medir ni ninguna cuenta que crear.

No se sube nada. Lo que pegues se queda en esta pestaña.