Cómo formatear y validar JSON sin romperlo

JSON parece sencillo hasta que una coma que falta tumba un despliegue. La mayoría de los fallos de JSON no son exóticos: son comas finales, comillas simples, comentarios o una llave o un corchete que no cierra. Esta guía explica qué permite realmente el JSON válido, los errores que verás más a menudo y una forma fiable de formatear y validar un payload.

Qué permite el JSON válido

JSON tiene una gramática muy pequeña:

• Un valor es un objeto, un array, una cadena, un número, true, false o null.
• Las claves de un objeto deben ser cadenas entre comillas dobles.
• Las cadenas usan comillas dobles; las comillas simples no son válidas.
• Los arrays y los objetos no pueden tener comas finales.
• Los comentarios no forman parte de la especificación de JSON.
• Los números no pueden ser NaN, Infinity ni hexadecimales.

Eso es prácticamente todo. El rigor es la idea: todos los analizadores de JSON de todos los lenguajes pueden ponerse de acuerdo sobre la misma entrada.

Los cinco errores más frecuentes

1. Comas finales

{
  "name": "Ada",
  "age": 36,
}

Esto es válido en JavaScript y en JSON5, pero no en JSON. Elimina la coma después de la última propiedad.

2. Comillas simples

{ 'name': 'Ada' }

JSON solo acepta comillas dobles. Suele pasar al copiar a mano desde Python o JavaScript.

3. Claves sin comillas

{ name: "Ada" }

Las claves de un objeto deben ser cadenas entre comillas dobles. Es otra costumbre de JavaScript que JSON no comparte.

4. Comentarios

{
  // el nombre del usuario
  "name": "Ada"
}

JSON no tiene comentarios. Si necesitas comentarios en un archivo de configuración, usa JSONC o YAML, pero no envíes comentarios a una API JSON.

5. Llaves o corchetes que no coinciden

Una llave o un corchete que falta suele producir un error al final del archivo en lugar de donde está el fallo real. Formatear el documento hace que el nivel que falta se vea mucho más fácil.

Por qué importa formatear

El JSON minificado es eficiente para las máquinas, pero incómodo para las personas. Un documento formateado:

• muestra la estructura de un vistazo;
• hace legibles las diferencias en una revisión de código;
• te ayuda a encontrar una llave o una coma que falta;
• te da una forma estable para comparar dos payloads.

Si estás depurando la respuesta de una API, pégala en un formateador antes de leerla. Si comparas dos versiones, formatea ambas primero y luego usa el diff. Formatear elimina el ruido de los espacios y deja visible el cambio real.

Formato legible o minificado

El formato legible añade sangría y saltos de línea para que se pueda leer. Minificar quita todos los espacios opcionales para el transporte. Son los mismos datos; elige según el destinatario:

• Usa el formato legible para logs, documentación, datos de prueba y depuración.
• Usa JSON minificado para cuerpos de petición y respuestas donde los bytes importan.

Un formateador debería permitir cambiar entre 2 espacios, 4 espacios, tabuladores y salida minificada sin alterar los valores.

Encontrar errores por línea

El mensaje de error más útil no es «JSON no válido», sino «token inesperado en la línea 4, columna 3». Los analizadores modernos suelen dar una posición, pero el formato del mensaje cambia según el entorno.

Un formateador en el navegador puede analizar el documento, indicar la línea y la columna y mantener la salida vacía hasta que el JSON sea válido. Ese ciclo de respuesta es mucho más rápido que adivinar qué llave falta.

El formateador de JSON hace exactamente eso: pegas un payload, ves la posición del error y luego formateas o minificas cuando el análisis pasa. Todo se ejecuta en local, así que puedes usarlo con payloads de producción sin riesgo.

JSON no es un objeto de JavaScript

Un objeto literal de JavaScript puede contener funciones, undefined, claves con comillas simples y comentarios. JSON no. La confusión es habitual porque la sintaxis se parece, pero JSON es un formato de datos, no un lenguaje.

Si necesitas convertir JSON en un valor de JavaScript, JSON.parse se encarga. Si necesitas convertir un objeto de JavaScript en JSON, JSON.stringify hará lo siguiente:

• descartar undefined y las funciones;
• convertir las fechas en cadenas;
• fallar con las referencias circulares;
• convertir NaN e Infinity en null.

Conocer esas reglas evita toda una clase de errores del tipo «¿por qué ha desaparecido este campo?».

De JSON a otros formatos

Cuando un payload ya es válido, a menudo lo necesitas en otra forma:

• JSON a CSV convierte un array de objetos en una hoja de cálculo.
• YAML a JSON mueve configuración entre los dos formatos.
• Comparador de textos compara un payload antiguo y uno nuevo después de formatear ambos.

Una lista de comprobación práctica

1. Pega el payload en un formateador y corrige primero los errores de sintaxis.
2. Formatea ambas versiones antes de compararlas.
3. Minifica solo cuando estés a punto de enviar los datos.
4. Mantén los comentarios fuera de JSON; usa YAML o JSONC para configuraciones que los necesiten.
5. No uses JSON para secretos que no pondrías en un log.

JSON es estricto a propósito. Cuando conoces las pocas reglas que impone, la mayoría de los errores de análisis se vuelven obvios en segundos.