Cómo formatear y validar JSON (y corregir los errores comunes)
Aprende a formatear, validar y minificar JSON, a leer los errores del parser y a corregir lo habitual: comas finales, comillas simples y texto sin escapar.
Actualizado
Formatear JSON significa volver a indentarlo para que cada clave quede en su propia línea; validarlo significa comprobar que sigue exactamente la gramática de JSON. Pega el texto en un formateador, lee el primer error que indique, corrige solo eso y vuelve a ejecutarlo. La mayoría de los JSON rotos tiene uno de unos seis errores, y todos están en la lista de abajo.
Qué exige realmente un JSON válido
JSON es más estricto que los literales de objeto de JavaScript, y ahí empieza la mayor parte de la confusión. Las reglas que importan:
- Las claves deben ser cadenas entre comillas dobles:
{"a":1}es válido,{a:1}y{'a':1}no lo son. - Los valores de cadena solo usan comillas dobles.
"it's"está bien;'single'no. - Nada de comas finales.
[1,2,3,]falla;[1,2,3]pasa. - Nada de comentarios.
// notey/* note */son errores los dos. - Los literales van en minúsculas:
true,false,null.True,NULLyundefinedno son válidos. - Los números no pueden tener ceros a la izquierda (
007), un signo más inicial (+5), ni serNaNoInfinity. - El nivel superior puede ser cualquier valor, pero la mayoría de las API espera un objeto
{}o un array[].
Si tienes presentes estas siete reglas, normalmente puedes detectar el problema a simple vista. Cuando no puedas, un validador te da la posición exacta.
Cómo leer un error del parser
Todo parser de JSON indica la posición en la que se rindió, que no es necesariamente donde está el error. Unexpected token } in JSON at position 42 significa que el parser llegó a un } cuando esperaba otra cosa, normalmente porque la línea anterior termina con una coma final. Unexpected end of JSON input significa que se abrió un corchete o una comilla y nunca se cerró. Unexpected token ' casi siempre significa comillas simples.
El enfoque práctico: mira la posición indicada y después mira un token hacia atrás. El formateador de JSON marca el error dentro del texto, en esa posición, así que no tienes que contar caracteres tú mismo.
Corregir los errores comunes
Comas finales
Copiar desde JavaScript, desde dicts de Python o desde archivos de configuración editados a mano deja una coma después del último elemento. Borra la coma antes de cada } y ]. Los linters la permiten en JS; JSON nunca.
Comillas simples y claves sin comillas
La salida de print(dict) en Python, {'name': 'Ada', 'age': 36}, parece JSON pero no lo es. Reemplaza ' por " y pon entre comillas las claves que no las tengan. Si el origen es Python, usa json.dumps() en lugar de str() para obtener JSON de verdad.
Caracteres sin escapar dentro de las cadenas
Una comilla doble literal o un salto de línea dentro de una cadena deben escaparse: "She said \"hi\"" y "line one\nline two". Las propias barras invertidas se convierten en \\, así que una ruta de Windows es "C:\\Users\\ada". Las tabulaciones son \t, y cualquier punto de código Unicode se puede escribir como \u00e9.
Codificación y caracteres invisibles
Una marca de orden de bytes al inicio de un archivo, comillas tipográficas pegadas desde un documento o un espacio de no separación entre tokens producen errores confusos en lo que parece una línea limpia. Vuelve a escribir las comillas sospechosas y guarda el archivo como UTF-8 sin BOM.
Documentos concatenados o envueltos
Los archivos de log suelen contener un objeto JSON por línea. El archivo entero no es JSON válido; cada línea sí. Divide por saltos de línea y analiza cada línea por separado, o envuelve las líneas entre [ y ] con comas entre ellas. Del mismo modo, una respuesta de API envuelta en un callback como cb({...}) es JSONP, así que quita primero la llamada a la función.
Formato legible frente a minificado
El JSON con formato legible usa dos o cuatro espacios por nivel de anidamiento y una clave por línea, que es lo que quieres para leer, para los diffs y para los archivos de configuración que subes a git. El JSON minificado elimina todos los espacios en blanco y lo deja en una sola línea, que es lo que quieres al transmitirlo o dentro de una variable de entorno. Los dos son los mismos datos. JSON.stringify(obj, null, 2) da formato legible en JavaScript; JSON.stringify(obj) minifica. En Python, json.dumps(obj, indent=2) hace el mismo trabajo.
El formato nunca cambia el significado, pero la especificación de JSON no garantiza el orden de las claves. No escribas código que dependa de que {"b":1,"a":2} conserve ese orden después de un viaje de ida y vuelta.Validar contra un esquema
La validación de sintaxis solo te dice que el texto es JSON bien formado. No te dice que "age" sea un número ni que "email" esté presente. Para eso necesitas JSON Schema, con un validador como Ajv en JavaScript o jsonschema en Python. Empieza por la sintaxis, porque un validador de esquemas no puede ejecutarse sobre un texto que no se puede analizar.
Convertir a otros formatos y desde ellos
Las hojas de cálculo quieren filas y columnas, no objetos anidados. Un array de objetos planos como [{"id":1,"name":"Ada"},{"id":2,"name":"Lin"}] se corresponde limpiamente con un CSV con fila de encabezado, y el conversor de JSON a CSV maneja campos entre comillas y comas incrustadas en ambos sentidos. Los objetos anidados hay que aplanarlos primero.
Los archivos de configuración de Kubernetes, GitHub Actions y Docker Compose suelen ser YAML. Todo documento JSON es también YAML válido, pero lo contrario no es cierto, ya que YAML permite comentarios, anclas y cadenas sin comillas. Cuando un archivo YAML se comporta mal, convertirlo con el conversor de YAML a JSON te muestra exactamente cómo interpretó el parser cada valor, lo que detecta la sorpresa clásica de que yes se convierta en true o 3.10 en 3.1.
El resto de las herramientas para formatear, codificar y validar está en la categoría para desarrolladores.
Pruébalo
Pega tu JSON con errores en el formateador de JSON. Funciona en tu navegador, resalta el error en la posición exacta y te deja cambiar entre la salida legible y la minificada con un ancho de indentación personalizado.