JSON Stringify

Qué hace realmente el escapado

Stringify analiza tu JSON, lo minifica, envuelve el resultado en comillas dobles y escapa todo lo que de otro modo terminaría la cadena antes de tiempo. Las comillas dobles internas pasan a ser \", las barras invertidas se duplican a \\, y los caracteres de control por debajo de U+0020 se convierten en sus formas cortas \n, \r, \t, \b y \f, o en un escape \u00XX cuando no existe forma corta.

Hay dos cosas que se dejan tal cual a propósito. La barra normal no se escapa, porque JSON no lo exige; a veces verás \/ en la salida de otras herramientas, que es válido pero innecesario y procede de la vieja costumbre de ocultar la secuencia </script> dentro de HTML. Los caracteres no ASCII también se conservan en lugar de convertirse en escapes \u, así que las tildes, la eñe, el texto CJK y los emoji siguen siendo legibles. Ambas formas significan lo mismo para un parser, y la legible es más fácil de comparar.

La doble codificación, y por qué da problemas

Esta herramienta existe porque escapar no es idempotente, y la gente suele descubrirlo a mitad de depurar otra cosa. Escapa un documento una vez y una comilla se convierte en \". Escapa el resultado otra vez y se convierte en \\\", porque la barra invertida que acabas de añadir es ahora también un carácter que hay que escapar. Cada pasada duplica aproximadamente las barras invertidas.

Esa es la huella de un payload serializado dos veces: un campo que debería contener un objeto contiene en cambio una cadena de JSON, y al leer el log se ven las comillas con barras invertidas. Ocurre cuando el código llama a un serializador sobre un valor que algún framework ya había serializado, y la solución casi siempre es quitar una de las dos llamadas, no añadir un paso de decodificación.

Unstringify es la herramienta para deshacerlo. Ejecútala una vez por cada capa de codificación y verás cómo las barras invertidas se reducen a la mitad cada vez. Cuando desaparecen y el resultado se analiza como un objeto, ya sabes cuántas capas había.

Cuándo necesitas una cadena escapada

Al incrustar un payload dentro de otro documento JSON, que es como los sobres de webhooks, las colas de trabajos y los registros de auditoría suelen transportar un cuerpo arbitrario. Al asignar un valor JSON a una variable de entorno, donde de otro modo el shell se comería las comillas. Al pegar el cuerpo de una petición en un archivo YAML de un trabajo de CI. Al escribir un fixture de prueba como literal en el código fuente. Al guardar un documento en una columna de texto en lugar de una columna JSON nativa.

En todos los casos, las comillas interiores tienen que atravesar una capa de análisis que de otro modo las trataría como terminadores, y el escapado es lo que las lleva intactas al otro lado.

Las reglas de escape, carácter por carácter

JSON define con exactitud qué caracteres no pueden aparecer literalmente dentro de una cadena. Las comillas dobles terminarían la cadena antes de tiempo, así que se escriben \". La barra invertida inicia un escape, así que se duplica a \\. Todos los caracteres de control por debajo de U+0020 están prohibidos, y cinco de ellos tienen forma corta: el salto de línea es \n, el retorno de carro \r, el tabulador \t, el retroceso \b y el avance de página \f. Todo lo demás en ese rango se convierte en un escape de seis caracteres como \u0000.

Hay dos caracteres que suelen escaparse sin que sea obligatorio. La barra normal puede escribirse \/, lo cual es legal e innecesario; la costumbre viene de incrustar JSON dentro de HTML, donde la secuencia </script> cerraría antes de tiempo el elemento script. Los caracteres que no son ASCII también pueden escribirse como escapes \u, algo que algunas bibliotecas hacen de forma predeterminada para mantener la salida en ASCII puro.

Esta herramienta deja ambos tal cual, porque una salida legible produce mejores diffs y todos los parsers tratan las dos formas de manera idéntica. Si un sistema posterior realmente necesita salida solo en ASCII, eso es una opción del serializador y no algo que el documento exija.

Cómo pasar JSON por el shell sin romperlo

El shell es donde el escape falla con más frecuencia, porque se aplican dos capas de comillas a la vez. Las comillas simples en bash dejan pasar todo tal cual, y por eso curl -d '{"name":"value"}' funciona y la misma cadena entre comillas dobles no: el shell expande variables y elimina caracteres antes de que curl llegue a verla.

Cuando el propio payload contiene una comilla simple, la forma con comillas simples también se rompe, y la respuesta sólida es dejar de incrustarlo en la línea de comandos: escribe el cuerpo en un archivo y usa curl -d @body.json, o pásalo por una tubería. Para payloads generados por código, jq -n es más seguro que concatenar cadenas porque produce JSON válido por construcción.

Las variables de entorno que contienen JSON son el caso hermano, sobre todo en la configuración de CI y en Docker. El valor suele tener que sobrevivir al entrecomillado de YAML, a la expansión del shell y al parseo de la propia aplicación, es decir tres capas, y la forma de mantener la cordura es codificar el JSON en base64, pasar eso y decodificarlo en el punto de uso.

Logs estructurados y la huella de la doble codificación

Cada vez más, los pipelines de logs esperan un objeto JSON por línea, lo que hace que los campos sean buscables en lugar de obligar a usar expresiones regulares sobre texto libre. La trampa está en registrar un objeto que ya fue serializado: el campo llega como una cadena de JSON en vez de como un objeto anidado, y el sistema de logs lo indexa como un único bloque opaco.

La señal visible es justo la huella que esta herramienta existe para deshacer: un valor que se lee como {\"id\":42} en lugar de {"id":42}. Cada capa adicional duplica aproximadamente las barras invertidas, así que contarlas indica cuántas codificaciones hubo.

La corrección corresponde al productor. Pasa el objeto al logger y deja que lo serialice una sola vez, en lugar de serializarlo tú y entregar una cadena. Cuando la cadena llega de otro lado y no se puede cambiar, la mayoría de las plataformas de logs tiene un filtro de parseo de JSON capaz de desenvolver el campo durante la ingesta, lo cual es mejor que hacerlo en cada consulta.

Incrustar un payload dentro de otro documento

Los sobres de webhooks, las colas de trabajos y los logs de auditoría enfrentan el mismo problema: una envoltura con sus propios campos tiene que transportar un cuerpo arbitrario. Serializar ese cuerpo como cadena es la respuesta sencilla, y el costo es que el documento interno se vuelve opaco: no se puede consultar, validar ni indexar sin parsearlo una segunda vez.

La alternativa, mantener el cuerpo como objeto anidado, conserva la capacidad de consulta pero exige que el esquema de la envoltura permita estructura arbitraria y mezcla los dos espacios de nombres a los ojos de cualquier cosa que recorra el documento. La mayoría de los sistemas termina decidiendo caso por caso: anidado donde el cuerpo se inspecciona, en cadena donde solo se retransmite.

Hay una tercera opción que conviene recordar cuando el payload es grande o binario: guárdalo en otro lugar y envía una referencia. Una URL y una suma de verificación dentro del sobre evitan tanto el escape como el límite de tamaño, y así es como terminan funcionando de todos modos la mayoría de los flujos con archivos grandes.

Leer texto escapado sin ninguna herramienta

Deshacer una codificación a ojo es factible con valores cortos y vale la pena practicarlo, porque revela qué pasó. Una sola capa muestra \" alrededor de las claves y los valores. Dos capas muestran \\\" y la cadena suele estar envuelta en comillas que a su vez están escapadas. Más allá de eso, las barras invertidas superan al contenido y contar resulta más rápido que leer.

Una comprobación útil es el comienzo de la cadena. Un objeto correctamente anidado empieza con una llave sin escapar; uno codificado dos veces empieza con una comilla seguida de una llave escapada, una forma que se aprende a reconocer al instante.

En una terminal, printf '%s\n' "$value" resuelve una capa y jq -r '.' resuelve otra, así que aplicarlos por turnos y ver cómo las barras invertidas se reducen a la mitad cada vez es el equivalente en línea de comandos a lo que hace aquí el botón unstringify.