Formateador JSON

Qué hace este formateador de JSON

JSON (JavaScript Object Notation) es el formato más común para mover datos estructurados entre programas: respuestas de API, archivos de configuración, líneas de registro y más. Está diseñado para ser compacto, lo que también lo hace difícil de leer cuando los objetos se anidan varios niveles o llegan en una sola línea. Esta herramienta toma cualquier JSON que pegues y lo reescribe de dos formas: embellecido, con sangría uniforme para que la estructura se vea de un vistazo, o minificado, sin cada espacio opcional para que sea lo más pequeño posible al enviarlo.

También valida mientras formatea. Como analiza el texto antes de volver a serializarlo, un JSON inválido nunca produce una salida engañosa: en su lugar obtienes la línea y la columna donde falló el análisis, siempre que pueda deducirlas, para ir directo al problema.

Embellecer vs. minificar: cuándo usar cada uno

Los dos modos tienen objetivos opuestos, y la mayoría de los flujos de trabajo usan ambos en distintas etapas:

• Embellece cuando lees o depuras: inspeccionar una respuesta de API, comparar dos payloads o revisar un archivo de configuración en un pull request. La sangría convierte un muro de texto en un árbol navegable.
• Minifica cuando envías: incrustar JSON en HTML, guardarlo en una cookie o caché, o mandarlo en el cuerpo de una petición donde cada byte cuenta. El JSON minificado es exactamente los mismos datos, solo que sin los espacios.

El selector de sangría (2 espacios, 4 espacios o tabulación) solo afecta a la salida embellecida. Dos espacios es la convención más común en JavaScript y en el tooling web; cuatro espacios o tabulaciones convienen a los equipos que las prefieren. Elijas lo que elijas, el resultado sigue siendo JSON válido: la sangría es puramente cosmética.

Leer los errores de validación

Cuando el JSON es inválido, la herramienta reporta la línea y la columna del primer problema en lugar de un simple "inválido", salvo en el único caso que describe la sección sobre dónde apuntan la línea y la columna. Los mensajes de error de los motores difieren entre navegadores y a menudo omiten la posición, así que la ubicación se calcula de forma independiente y señala un punto razonable por donde empezar. Corrige el primer error y vuelve a comprobar: un solo carácter perdido a menudo se convierte en varios problemas aparentes.

Errores comunes de JSON

JSON es más estricto que los objetos literales de JavaScript a los que se parece. Estos son los errores que más confunden:

• Comas finales: una coma después del último elemento de un objeto o array es válida en JavaScript pero no en JSON.
• Comillas simples: las cadenas y claves de JSON deben usar comillas dobles. 'valor' es inválido; "valor" es correcto.
• Claves sin comillas: toda clave de objeto debe ser una cadena entre comillas, así que { name: "x" } debe pasar a { "name": "x" }.
• Comentarios: JSON no tiene sintaxis de comentarios. // y /* */ provocarán un error de análisis.
• Números especiales: NaN, Infinity y -Infinity no son números JSON válidos.
• Comillas equivocadas: las "comillas tipográficas" pegadas desde un procesador de textos parecen comillas pero son caracteres distintos y no se analizarán.

Dónde apuntan la línea y la columna que se reportan

La posición no es donde omitiste algo: es donde el analizador encontró por primera vez algo que no puede estar ahí legalmente, y suelen ser lugares distintos. En el objeto de abajo, a la línea 3 le falta la coma que debería cerrarla, y la herramienta reporta la línea 4, columna 3: la comilla de apertura de la clave siguiente. Nada estaba mal hasta que llegó esa comilla, porque el documento podría haber terminado legalmente después de la línea 3, así que el analizador solo se entera de la omisión cuando encuentra algo que no es ni una coma ni una llave de cierre.

{
  "id": 42,
  "name": "widget"
  "price": 9.99
}

• Una coma que falta se reporta en el primer carácter de lo que venga después, que en JSON con sangría como el de arriba es la línea siguiente: lee la línea señalada junto con la de arriba.
• Una coma sobrante se reporta en la llave o el corchete de cierre: línea 3, columna 1 para un objeto cuyo último par está en la línea 2. La coma promete otro par y la llave es lo que rompe la promesa.
• Una cadena sin cerrar suele reportarse al final de la línea en la que se abrió, no en la comilla de apertura, porque la siguiente comilla en una línea posterior puede cerrarla en otro sitio. Un salto de línea no puede aparecer dentro de una cadena JSON, así que el salto es el primer carácter que no puede estar ahí.
• Línea 1, columna 1 en un documento que parece perfecto suele significar una marca de orden de bytes. Algunos editores la escriben al guardar como UTF-8; es invisible, va delante de la llave de apertura y JSON no tiene sitio para ella.

Y donde la herramienta no puede deducir ninguna posición, reporta el fallo sin ella en lugar de nombrar una coordenada adivinada. Una línea y una columna dadas con seguridad que apunten a una sintaxis perfectamente correcta te harían buscar en el lugar equivocado, y eso es peor que saber solo que el documento no se analiza.

Qué cambia el formateo y qué conserva

Para casi cualquier documento la respuesta es el espacio en blanco y nada más. Pero la herramienta no edita tu texto: lo analiza convirtiéndolo en valores reales y vuelve a escribir esos valores, y cinco cosas no sobreviven a ese viaje de ida y vuelta. Ninguna es un fallo de la herramienta, porque cada una es lo que la especificación de JSON dice que es un número o un objeto, y conviene conocerlas antes de pegar la salida encima de tu original.

• La misma clave escrita dos veces: solo sobrevive la última de las dos, porque un objeto no puede tener una clave repetida. El RFC 8259 dice que un programa que recibe un objeto con nombres duplicados se comporta de forma impredecible, y otro analizador puede conservar el primero, así que cuál de los dos te queda tampoco es algo en lo que confiar.
• Un entero de más de quince dígitos: los números JSON se leen como coma flotante de doble precisión, que contiene con exactitud todo número entero hasta dos elevado a cincuenta y tres, una cifra de dieciséis dígitos, así que un entero de quince dígitos siempre sobrevive y uno más largo puede no hacerlo. Pega 12345678901234567890 y sale 12345678901234567000. Los identificadores largos de base de datos son la víctima habitual: mantenlos como cadenas si puedes.
• Las formas con exponente y con ceros finales se normalizan: 1e3 vuelve como 1000 y 1.50 como 1.5. Es el mismo número escrito de la forma estándar.
• Una magnitud fuera de lo que ese formato admite vuelve como otra cosa: 1e400 no tiene valor en doble precisión y vuelve como null, y 1e-400 vuelve como 0. Una fracción decimal larga se redondea a la precisión que el formato tiene, igual que un entero largo.
• Un escape se convierte en el carácter que denota: \u00e9 vuelve como é, y un par suplente escapado como el emoji que compone. Para cualquier analizador son la misma cadena; simplemente una de las dos escrituras es más corta.

El orden de las claves se conserva como lo escribiste, con una excepción que vale la pena conocer: una clave formada solo por dígitos, que se lee como un número entero no negativo simple menor de unos cuatro mil millones, se trata como índice de un array y vuelve al principio de su objeto en orden numérico, donde sea que la hayas puesto. Nada más se mueve: ninguna otra clave se reordena, y ninguna se añade ni se renombra. Si algo de esto te importa, minifica en lugar de embellecer y compara el resultado con tu original carácter a carácter. Es la forma más corta de ver qué hizo el viaje de ida y vuelta.

Cuando el JSON que buscas está dentro de una cadena

Los registros de webhooks, las colas de mensajes y las columnas de base de datos llevan muy a menudo un documento JSON entero como un único valor de cadena, con cada comilla de dentro escapada. El documento exterior es perfectamente válido, así que la herramienta lo embellece y lo reporta válido, y la parte que venías a leer sigue siendo una línea larga de barras invertidas. Nada ha fallado: son dos documentos, uno envuelto dentro de una cadena del otro.

{
  "event": "order.created",
  "payload": "{\"id\":42,\"total\":19.99}"
}

Leerlo requiere por tanto dos pasadas. Formatea aquí el documento exterior, copia lo que está entre las comillas de la cadena que quieres, deshaz el escapado y pega el resultado de nuevo. La herramienta Escapar / desescapar cadenas JSON hace ese paso intermedio: su dirección de desescapado convierte \" otra vez en " y la línea en un documento que esta página puede formatear. Si controlas lo que generó el archivo, el mejor arreglo está más arriba: envía el payload como objeto anidado en lugar de como cadena, y no hace falta ninguna pasada.

Un objeto por línea no es un documento

Los archivos de registro, las exportaciones de API y los endpoints de streaming suelen contener un objeto JSON completo por línea; el formato se llama JSON Lines, o NDJSON. Cada línea es JSON válido por sí sola, pero el archivo no es un documento JSON, porque un documento JSON contiene exactamente un valor de nivel superior y este contiene varios, uno tras otro y sin nada que los una.

{"level":"info","msg":"started"}
{"level":"warn","msg":"retrying"}
{"level":"error","msg":"gave up"}

Pega eso aquí y la herramienta reporta la línea 2, columna 1: el primer objeto terminó limpiamente y entonces empezó un segundo donde el documento debería haber acabado. Desde ahí hay dos caminos. Formatea una línea a la vez, que es lo que quieres cuando estás leyendo una sola entrada de registro. O convierte el archivo en un documento, envolviendo las líneas en corchetes y poniendo una coma al final de cada línea menos la última, que es lo que quieres cuando vas a cargarlo todo en algo que espera un array.