Una clave todavía no es una ruta
Imagina un objeto JSON con la clave draft/a~b y un valor que contiene otro objeto con state. La barra forma parte de la clave; no añade un nivel de anidamiento. JSON Pointer, en cambio, identifica un valor mediante segmentos separados por barras. La ruta /orders/0/item puede señalar un elemento de una matriz, donde 0 es su índice. Copiar una clave sin escapar dentro de la ruta podría llevar al lugar equivocado o producir un error.
RFC 6901 define dos escapes dentro de cada segmento: la tilde se convierte en ~0 y la barra en ~1. La ruta completa empieza además con una barra por segmento; una ruta vacía señala el documento entero. Esta notación afecta a los caracteres de la dirección, no al contenido del valor señalado. Tampoco modifica el objeto JSON original. Utiliza el codificador de segmentos cuando construyas una ruta a partir de una clave recibida de datos o de otra persona.
Construye el ejemplo por partes
Para la clave draft/a~b, sustituye primero la tilde por ~0 y después la barra por ~1. El segmento escapado es draft~1a~0b. Añade una barra inicial y el miembro independiente state: obtendrás /draft~1a~0b/state. El convertidor insertado realiza el paso del segmento; no añade la barra inicial porque quizá necesites colocarlo en otra posición de una ruta más larga. Compara su salida con las tres etapas del diagrama.
La herramienta inversa sustituye ~1 por barra antes de sustituir ~0 por tilde. El orden importa: convertir ~01 en ~1 y volver a interpretarlo como barra alteraría el nombre original. Un segmento JSON Pointer tampoco es una codificación porcentual de URL. Si lo sitúas en un fragmento de dirección web, esa capa exterior tiene reglas adicionales. Mantén separadas la sintaxis de la ruta y la de la URL al investigar enlaces o peticiones a una API.
- Clave original: draft/a~b
- Segmento escapado: draft~1a~0b
- Ruta completa: /draft~1a~0b/state
Qué produce el aplanamiento
La herramienta para aplanar recorre un objeto JSON y escribe los valores finales bajo claves con forma de rutas JSON Pointer completas. Si state está dentro de draft/a~b, una entrada plana será /draft~1a~0b/state con el mismo valor final. Esta vista ayuda a comparar, enumerar o exportar datos anidados. La herramienta inversa lee esas claves para reconstruir el objeto, siempre que las rutas no se contradigan. Una entrada plana sigue siendo una propiedad JSON; por sí sola no realiza ninguna consulta.
En esta implementación, las matrices se tratan como valores finales: no se crean entradas separadas para /0 y /1. Los objetos vacíos también son valores finales. Aunque JSON Pointer en general puede señalar índices de matriz, la lista aplanada aquí no los enumera. Si una ruta asigna un valor simple a /a y otra intenta crear /a/b, la reconstrucción debe rechazar el conflicto. Conserva el JSON original antes de editar manualmente las claves de ruta.
Procedimiento para datos con rutas
Empieza con JSON válido y decide si necesitas una sola dirección o una vista plana completa. Para una dirección, separa los nombres reales de los miembros, escapa cada nombre por separado y únelos con barras iniciales. No escapes la ruta entera de una vez: convertirías también sus barras separadoras en caracteres de una clave. Si necesitas inspeccionar muchos valores finales, aplana el objeto y revisa las claves generadas antes de entregarlas a otro sistema.
Al restaurar datos, comprueba que cada clave plana comienza con una barra y que los escapes con ~ son válidos. Vigila asignaciones repetidas o incompatibles, matrices tratadas como valores finales y claves literales con puntos o barras. Prueba el recorrido con un objeto pequeño que incluya los dos signos especiales y compara las estructuras JSON interpretadas, no la sangría. El estándar define las rutas; la política exacta de aplanamiento pertenece a esta herramienta local.