GameParticles
Desarrollo

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. // note y /* note */ son errores los dos.
  • Los literales van en minúsculas: true, false, null. True, NULL y undefined no son válidos.
  • Los números no pueden tener ceros a la izquierda (007), un signo más inicial (+5), ni ser NaN o Infinity.
  • 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.

Herramientas de esta guía

Preguntas frecuentes

¿Por qué mi JSON falla con Unexpected token at position N?

El parser llegó a un carácter que no esperaba en esa posición. Mira un token antes de la posición: una coma final, una comilla simple o un corchete de cierre que falta es casi siempre la causa.

¿Se permiten comentarios en JSON?

No. Ni // ni /* */ forman parte de la gramática de JSON. Algunas herramientas los aceptan en archivos de configuración (JSONC, JSON5), pero un parser estándar como JSON.parse los rechazará.

¿Formatear JSON es lo mismo que validarlo?

Formatear vuelve a indentar un JSON válido para que sea legible. Validar comprueba la sintaxis. Un formateador tiene que analizar el texto primero, así que valida como efecto secundario, pero no comprueba tus datos contra un esquema.

¿Cómo convierto la salida de un dict de Python en JSON de verdad?

Usa json.dumps(obj) en Python en lugar de str(obj). La forma str usa comillas simples y literales de Python como True y None, que no son JSON válido.

Más guías para desarrolladores

Formateador de JSON
Desarrollo · Formatea, valida y minifica JSON con resaltado de sintaxis.
↵
Codificar / decodificar Base64
Desarrollo · Codifica texto en Base64 o decodifica Base64 a texto plano.
↵
Codificador / Decodificador de URL
Desarrollo · Codifica o decodifica componentes de URL y cadenas de consulta.
↵
Generador de hash
Desarrollo · Genera hashes MD5, SHA-1, SHA-256 y SHA-512.
↵
Generador de UUID
Desarrollo · Genera UUID v4 (aleatorios) en lote con un clic.
↵
Probador de regex
Desarrollo · Prueba expresiones regulares sobre un texto con resaltado de coincidencias en vivo.
↵
Contador de palabras
Texto · Cuenta palabras, caracteres, frases, párrafos y tiempo de lectura.
↵
Conversor de mayúsculas y minúsculas
Texto · Convierte texto a MAYÚSCULAS, minúsculas, Título, camelCase, snake_case y más.
↵
Ordenador de listas
Texto · Ordena, invierte, baraja y quita duplicados de listas de texto.
↵
Vista previa de Markdown
Texto · Escribe Markdown y mira la vista previa renderizada en vivo, lado a lado.
↵
Calculadora de porcentajes
Números · Calcula porcentajes, aumentos, descuentos y qué % es un número de otro.
↵
Conversor de colores
Colores · Convierte colores entre HEX, RGB, HSL y HSV al instante.
↵
Snake
Arcade · Come, crece y no choques con las paredes. Un clásico eterno.
↵
2048
Puzles · Desliza y combina fichas hasta conseguir la legendaria ficha 2048.
↵
Word Grid
Puzles · Adivina la palabra oculta de cinco letras en seis intentos con pistas de colores.
↵
Sudoku
Puzles · Completa la cuadrícula 9x9 con lógica. Cuatro niveles, de fácil a experto.
↵
Buscaminas
Estrategia · Usa las pistas numéricas para despejar el campo de minas. Lógica clásica, tres niveles.
↵
Breakout
Arcade · Rompe todos los ladrillos con barra y bola. Power-ups, combos y niveles sin fin.
↵
Práctica de mecanografía
Casual · Mejora tus PPM y tu precisión con prácticas de 30 segundos a 5 minutos. Descubre tus teclas débiles.
↵
TypeRunner
Arcade · Carrera de mecanografía multijugador. Reta a tus amigos con un enlace, vence a la máquina o persigue a tu fantasma.
↵
Typing Blocks
Arcade · Escribe cada palabra antes de que su bloque de madera aterrice. Si fallas, la pila sube hacia la línea.
↵
Bubble Shooter
Arcade · Apunta, rebota en las paredes y explota grupos de tres o más burbujas.
↵
Road Rush
Arcade · Corre contra siete rivales entre el tráfico y ábrete paso a golpes.
↵