El error que me hizo construir esta herramienta fue exasperantemente pequeño. Estaba metiendo una plantilla de correo electrónico HTML (unos cientos de líneas con comillas, saltos de línea y alguna que otra barra invertida) en un campo JSON para enviarla a una API, y la solicitud seguía regresando como 400. La plantilla estaba bien. El JSON estaba bien por sí solo. Pero en el momento en que los dos se conocieron, una cita doble sin escape de trescientos caracteres cerró silenciosamente la cadena temprano, y todo lo que después de que se convirtió en basura no podía entender al analizador. Había pegado texto válido en un contenedor válido y producido un documento no válido.
Ese es todo el problema que resuelve el escape de JSON, y vale la pena comprenderlo en lugar de solucionarlo. Esta guía cubre lo que realmente hace escapar, qué personajes deben escaparse y por qué, cómo revertirlo y cómo usar el archivo gratuito Escape JSON / Unescape herramienta para mover texto arbitrario dentro y fuera de cadenas JSON sin un solo fallo silencioso. Se ubica junto a otras utilidades de datos sobre las que he escrito en el Guía definitiva de las herramientas JSON.
TL;Dr: Una cadena JSON no puede contener una cita doble sin formato, una barra invertida sin formato ni caracteres de control sin formato como nuevas líneas y pestañas. Escaping reemplaza cada uno con una secuencia de barra invertida -
"se convierte en\", se convierte en una nueva línea\n, una pestaña se convierte en\t, y cualquier otra cosa por debajo de U+0020 se convierte en\uXXXX. Unescaping convierte esas secuencias nuevamente en los personajes originales. El Escape JSON / Unescape la herramienta hace ambas cosas en su navegador, con opciones para envolver el resultado en comillas, escape no ASCII como\uXXXX, o escapar del corte hacia adelante.
¿Qué significa escapar de una cadena para JSON?
JSON tiene una gramática publicada precisa: está definida por RFC 8259 y según el estándar ECMA-404, y las reglas para lo que puede aparecer dentro de una cadena son estrictas. Una cadena JSON es una serie de caracteres envueltos en comillas dobles. Porque la cita doble marca el inicio y el final de la cadena, una cita doble entromete el texto terminaría prematuramente. Debido a que la barra invertida comienza una secuencia de escape, una barra invertida sin formato se malinterpretaría como el comienzo de una. Y debido a que las cadenas JSON están destinadas a ser una única línea lógica de texto, los caracteres de control literales (nuevas líneas, pestañas, devoluciones de carruajes) no pueden permanecer dentro de ellas sin escapar.
Escapar es el proceso de reemplazar cada uno de esos personajes problemáticos con una secuencia de barra invertida de dos caracteres que JSON entiende. Se convierte en una cita doble \". Se convierte en una barra invertida \\. Se convierte en una nueva línea \n. El resultado es un texto que acecharse un poco más feo, pero ahora es seguro colocarlo entre dos comillas sin romper el documento circundante. El significado es idéntico: una lectura del analizador JSON \n vuelve a producir una verdadera nueva línea, pero la representación ahora es legal.
Esto es fundamentalmente diferente de formatear un documento JSON. Un formateador organiza la estructura de un objeto completo: sangría, orden de claves, espacios en blanco entre elementos. Escapar opera un nivel hacia abajo, en el contenido de un valor de cadena única. Tú alcanzas el Formateador JSON cuando tienes un documento completo para imprimir o validar bonito, y para el Escape JSON / Unescape herramienta cuando tienes un conjunto de texto sin formato que necesitas que quepa dentro de un campo.
¿Qué personajes realmente necesitan escapar?
La especificación JSON es refrescantemente específica aquí. Dentro de una cadena, exactamente dos caracteres moho siempre se puede escapar, además de toda la gama de personajes de control.
Las dos escapadas obligatorias de un solo carácter son la doble cita (\") y la barra invertida (\\). Más allá de eso, JSON define escapes cortos para cinco caracteres de control comunes: retroceso (\b), formă feed (\f), newline (\n), return de carruaje (\r) y pestaña horizontal (\t). Cualquiera de otra manera que el carácter de control, cualquier cosa con un punto de código inferior a U+0020 que no tenga una forma corta, debe escribirse como \u escape seguido de cuatro dígitos hexadecimales, por lo que se convierte en un byte nulo \u0000 y el "unit separator" se convierte \u001F.
Hay dos personajes más opcional para escapar, y aquí es donde entra la confusión. La barra diagonal puede escribirse como \/, pero no tiene por qué serlo: una simple / es JSON perfectamente válido. Y cualquier carácter por encima del rango ASCII, como un acentuado é o un emoji, puede escribirse literalmente en un documento UTF-8 o escaparse como \uXXXX; ambos son legales. El Escape JSON / Unescape la herramienta siempre maneja los escapes obligatorios y le brinda alternancias para los dos opcionales para que pueda igualar lo que espere su sistema de destino.
¿debo escapar de la barra diagonal y de los caracteres que no son ASCII?
Estos dos escapes opcionales existen por razones reales, incluso si rara vez los necesitas.
El escape de barra diagonal es importante exactamente en una situación común: cuando JSON está integrado dentro de un HTML <script> etiqueta. El analizador HTML del navegador 's busca la secuencia literal </ para encontrar el final de un bloque de script, entonces una cadena que contiene </script> en su JSON puede cerrar prematuramente la etiqueta y romper la página. Escribiendo la barra diagonal como <\/script> - sigue siendo JSON válido, sigue siendo la misma cadena una vez analizada - lo evita. Fuera de los scripts en línea, puedes dejar las barras en paz, razón por la cual la herramienta deja la barra diagonal sin escapar de forma predeterminada.
Escapar de caracteres que no son ASCII como \uXXXX se trata de portabilidad más que de corrección. Si su JSON pudiera pasar a través de un sistema que destruye los bytes UTF-8 (un antiguo canal de registro, un proxy mal configurado, un canal que asume ASCII), convirtiendo cada carácter por encima del rango ASCII en un ASCII puro \u escape garantiza que sobrevive intacto. La salida es más voluminosa y menos legible por humanos, por lo que está desactivada de forma predeterminada, pero "Escape Unicode" alternar está ahí por el momento que necesitas transporte a prueba de balas. Un punto de código como é se convierte en \u00e9, y un analizador JSON reconstruye el personaje original al salir.
¿cómo funciona la desesperación y cuándo la necesito?
Unescaping es exactamente lo inverso: camina a través de una cadena escapada y convierte cada secuencia de barra invertida nuevamente en el carácter sin formato que representa. \n se convierte en una verdadera nueva línea, \t se convierte en una pestaña, \" se convierte en una cita doble, y \uXXXX se convierte en el carácter en ese punto de código. Lo necesita siempre que esté en el extremo receptor: ha copiado un valor de cadena directamente de un archivo JSON, una línea de registro o una respuesta API, y desea leer el texto original sin una pantalla llena de barras invertidas en el camino.
Un buen unescaper hace dos cosas que un ingenuo hallazgo y reemplazo no hace. Primero, elimina un solo par de comillas dobles circundantes si se cita el valor total, para que pueda pegar "line one\nline two" directamente de un documento JSON y obtenga texto limpio. Segundo, eso valida tal como va: una secuencia de escape no válida como \x, o una barra invertida perdida al final de la cadena, es un error real, y el Escape JSON / Unescape la herramienta informa su posición en lugar de adivinar y producir resultados silenciosamente incorrectos. Obtener un escape claro de " no válido en la posición 14" Es mejor que obtener texto que parece casi correcto pero que está sutilmente dañado.
La propiedad clave en la que confiar es que escapar y desescapar son inversos exactos. Escape cualquier texto y luego desescape el resultado y obtendrás exactamente lo que empezaste, carácter por carácter. Esa garantía de ida y vuelta es lo que hace que sea seguro utilizar la herramienta como un paso de rutina en una canalización en lugar de una transformación arriesgada que debes verificar a mano.
Operaciones de escape versus operaciones de cadena relacionadas
JSON escapar es miembro de una familia de " haga que este texto sea seguro para ese contexto" se transforma y ayuda a mantenerlos rectos. Así es como se compara con los desarrolladores vecinos con los que más a menudo lo confunden.
| Operación | Protege contra | ejemplo | herramienta |
|---|---|---|---|
| Escape JSON | Romper una cadena JSON con comillas, barras invertidas o caracteres de control | he said "hi" → he said \"hi\" |
Escape JSON / Unescape |
| Codificación de entidad HTML | Rompiendo HTML o habilitando XSS con <, >, & |
<b> → <b> |
Entidades HTML |
| URL porcentaje-código | Rompiendo una URL con espacios o caracteres reservados | a b → a%20b |
- |
| Formato JSON/validar | Errores estructurales en todo un documento | minificado → bastante impreso | Formateador JSON |
| JSON → YAML | Mover una configuración entre formatos de serialización | {"a":1} → a: 1 |
JSON a YAM |
El patrón a tener en cuenta es que cada escape apunta a un distinto contenedor. Las entidades HTML evitan que el texto rompa HTML; la codificación porcentual evita que rompa una URL; El escape JSON evita que rompa una cadena JSON. Usar el incorrecto (codificar HTML, algo que necesita escapar JSON) deja el problema real sin resolver y agrega una nueva capa de ruido. Debido a que todo esto se ejecuta en texto que quizás no desee entregar a un servidor de terceros, mantengo cada una de estas herramientas en el lado del cliente, que es el argumento que presenté en su totalidad en el guía de privacidad de datos para herramientas en línea.
¿cuáles son los errores comunes al incrustar texto en JSON?
El error más común es el que me costó una tarde: pegar texto de varias líneas con comillas sin escapar directamente en un campo JSON y asumir que debido a que ambas partes son válidas, el todo es válido. No lo es: el contenedor tiene reglas que el contenido debe obedecer.
Un segundo cercano es doble escape. Si una cadena ya se ha escapado una vez y tú la vuelves a escapar, cada \n se convierte en \\n y sus nuevas líneas se convierten en una barra invertida literal que ningún analizador volverá a convertir. Esto suele ocurrir cuando un valor pasa a través de dos sistemas, cada uno de los cuales escapa útilmente. Si su salida tiene ejecuciones sospechosas de \\ donde esperabas barras invertidas simples, probablemente hayas escapado dos veces y, al escapar una vez, lo arreglarás. La tercera trampa es olvidar que una ruta de Windows es como C:\Users\me está lleno de barras invertidas, cada una de las cuales debe convertirse \\ - un camino sin escape en JSON es una fuente clásica de " ¿Por qué mi JSON no es válido y quot; confusión.
La solución para los tres es la misma: deje que la herramienta escape exactamente una vez, en el límite donde el texto sin formato se encuentra con JSON, y lea el resumen del recuento de caracteres que muestra para verificar la cordura que algo cambió. Cuando necesites verificar manualmente, escapa con " envolver entre comillas y comillas; habilitado y pegue el resultado en el Formateador JSON - si se analiza como una cadena válida, su escape es correcto.
Un ejemplo trabajado: incrustar un fragmento HTML en JSON
Permítanme analizar la situación exacta que inició esto, porque ver la transformación una vez hace que la regla se mantenga. Digamos que quieres enviar este fragmento como body campo de una solicitud API:
<p>Hi "there",</p>
<p>Visit https://example.com/path</p>
Tres cosas en ese texto pelearán con JSON. Las dos citas dobles alrededor there cada uno intentará finalizar la cadena. La nueva línea entre los párrafos es un carácter de control literal que JSON prohíbe dentro de una cadena. Y el </p> las secuencias son inofensivas en un archivo JSON simple, pero peligrosas si este JSON alguna vez se imprime dentro de un HTML <script> etiqueta. Pegue el fragmento en el Escape JSON / Unescape herramienta, enciende " envuelve comillas," y obtienes una única cadena JSON válida: las comillas se convierten en \", la nueva línea se convierte en \n, y con "escape adelante barra y comilla; habilitó las etiquetas de cierre <\/p>. Deje todo ese valor cotizado directamente en su body campo y la solicitud se realiza.
El viaje inverso es igual de rutinario. Cuando un compañero de equipo te envía una línea de registro con un JSON escapado message campo lleno de \n y \", péguelo en la herramienta, cambie a Unescape y lea el texto original de varias líneas sin las barras invertidas. Debido a que las dos operaciones son inversas exactas, puede mover una carga útil para editarla y volver a ingresar sin temor a corrupción: el resumen del recuento de caracteres confirma que se ejecutó la transformación y cualquier escape mal formado se marca con su posición en lugar de alterar silenciosamente el texto. Esa seguridad de ida y vuelta es lo que convierte escapar de un nervioso paso manual en algo que puedes conectar a un flujo de trabajo y olvidarte.
Preguntas frecuentes
¿Qué significa escapar de una cadena para JSON? Los valores de la cadena JSON no pueden contener una comilla doble sin formato, una barra invertida sin formato ni caracteres de control sin formato como nuevas líneas y pestañas. Escaping reemplaza cada uno de estos con una secuencia de barra invertida - " se convierte en " una nueva línea se convierte en \n, una pestaña se convierte en \t, por lo que el texto se puede colocar dentro de una cadena JSON sin romper la estructura circundante.
¿En qué se diferencia esto de un formateador JSON? Un JSON formateador imprime o minimiza un documento JSON completo y valida su estructura. Esta herramienta funciona con un nivel hacia abajo, en el contenido de una sola cadena: hace que el texto arbitrario sea seguro para incrustar dentro de un valor JSON o decodifica un valor de escape de nuevo al texto sin formato. Utilice el formateador para documentos y esta herramienta para cadenas individuales.
¿Qué personajes se escapan? La cotización doble ("), la barra invertida (\), el retroceso (\b), la alimentación de formulario (\f), la nueva línea (\n), el retorno del carro (\r) y la pestaña (\t) siempre se escapan, junto con cualquier otro carácter de control por debajo de U+0020 como \uXXXX. Opcionalmente, la barra diagonal se convierte en / y cada carácter que no sea ASCII se convierte en \uXXXX.
¿Debo escapar de la barra inclinada? Es opcional. La especificación JSON permite tanto / como /, por lo que / simple es válido. El único lugar / importa está dentro de un HTML
