Guías de Toolvil
Cómo formatear y validar JSON
¿Alguna vez tu JSON apareció en una sola línea larguísima e ilegible, o falló al analizarse con un error 'Unexpected token'? Con unas pocas reglas básicas de sintaxis JSON puedes encontrar la causa por ti mismo y formatear y validar el archivo.
Qué es JSON y por qué su sintaxis es tan estricta
JSON (JavaScript Object Notation) es un formato para intercambiar datos como texto legible por personas. Se usa casi en todas partes: respuestas de API, archivos de configuración, cargas de webhooks y registros. Pero JSON tiene una sintaxis muy estricta: una sola coma o comilla fuera de lugar hace fallar todo el análisis. Aquí 'más o menos bien' no sirve, y eso es lo que más desconcierta al empezar.
La clave es que JSON 'se parece' a un objeto de JavaScript, pero 'no es lo mismo'. Muchas notaciones que JavaScript acepta son errores en JSON. Por eso, copiar un objeto desde la consola y pegarlo como JSON casi siempre falla. Entender esta diferencia es el punto de partida para corregir tú mismo los errores de JSON.
Reglas básicas de sintaxis JSON que debes cumplir
Los valores de JSON solo pueden ser de seis tipos: objeto ({}), matriz ([]), cadena, número, booleano (true/false) y null. Las reglas que debes cumplir además se resumen en la tabla.
| Regla | Ejemplo correcto | Ejemplo incorrecto |
|---|---|---|
| Las claves van entre comillas dobles (" ") | "name": "철수" | name: "철수" |
| Las cadenas también admiten solo comillas dobles | "city": "서울" | 'city': '서울' (comillas simples) |
| Sin coma después del último elemento | ["a", "b"] | ["a", "b",] (coma final) |
| No se permiten comentarios | (sin comentarios) | // 설명, /* ... */ |
| undefined y las funciones no pueden ser valores | Usa null | undefined, NaN |
Como muestra la tabla, los errores más comunes son cosas que funcionan en JavaScript pero no en JSON. En resumen: usa siempre comillas dobles en claves y cadenas, quita la última coma y no escribas comentarios. Con esos tres hábitos desaparece la mayoría de los errores.
Comillas simples y comillas dobles
En JavaScript, '서울' y "서울" son cadenas, pero JSON acepta solo comillas dobles. Todo valor entre comillas simples es un error. El mismo error aparece cuando el texto copiado de un procesador de textos o una hoja de cálculo trae comillas tipográficas en lugar de comillas dobles normales ("), así que comprueba que sean las normales aunque se vean parecidas.
Comas finales
Una coma después del último elemento de una matriz o un objeto no está permitida en JSON. El JavaScript moderno acepta comas finales, así que es fácil ponerla por costumbre, pero al pasar los datos a JSON el análisis falla en ese punto. Dejar una coma suelta al borrar un elemento también es una causa frecuente.
Errores frecuentes y cómo diagnosticarlos
Un analizador de JSON suele informar los errores con el formato Unexpected token ... in JSON at position N. Aquí position N es, aproximadamente, la posición del carácter donde empieza el problema, así que mirar a su alrededor reduce rápido la causa. Estos son los patrones más habituales.
- Coma final: comprueba si queda una coma justo antes de
} o ]. Es la causa más común. - Comillas ausentes en la clave: una clave sin comillas dobles, como en
{ name: "값" }, es un error. Cámbiala a { "name": "값" }. - Comillas simples: cambia todos los
' por ". - Llaves o corchetes sin pareja: comprueba que el número de
{ y [ de apertura coincide con el de } y ] de cierre. Al añadir sangría se ve de un vistazo. - Comentarios olvidados: elimina cualquier
// o /* */ que se haya añadido como explicación.
Contar a mano la posición de un error es tedioso, así que normalmente es más rápido añadir primero la sangría (formatear) y leer la estructura desplegada. Cuando el JSON que estaba en una sola línea se reparte línea por línea, se ve enseguida qué línea tiene la coma o la comilla fuera de lugar. Pégalo en el formateador y visor de JSON y lo formatea y marca la posición del error, y además puede corregir de una vez los errores comunes anteriores.
Diferenciar formatear (embellecer) y minificar
Las dos conversiones que más se usan con JSON son 'formatear' y 'minificar'. Ambas dejan los datos intactos y solo cambian los espacios en blanco, así que elige la que se ajuste a tu objetivo.
Tipo Qué hace Cuándo usarla Formatear (embellecer) Añade sangría y saltos de línea para que sea fácil de leer Cuando una persona lo lee y depura, en revisiones de código Minificar Elimina todos los espacios y saltos de línea para dejar una sola línea Para reducir el tamaño de transferencia y almacenamiento, en parámetros de URL
La sangría suele ser de 2 o 4 espacios. Si añades 'ordenar claves', las claves de cada objeto quedan en orden alfabético, lo que ayuda a comparar dos JSON o a buscar cambios. Ordenar cambia solo el orden de las claves de los objetos y deja el orden de los elementos de las matrices tal como está, porque el orden de una matriz suele tener significado.
Trabajar con estructuras muy anidadas
Cuando el JSON está muy anidado y cuesta encontrar dónde está un valor, una vista de árbol ayuda. Puedes contraer y expandir objetos y matrices, recorrer primero toda la estructura y abrir solo lo que necesitas. La ubicación de un valor se escribe como una ruta de acceso, por ejemplo data.users[0].email, y al conocer la ruta puedes leer ese valor directamente en el código.
Manejarlo con seguridad: comprueba dónde se procesa
El JSON suele contener valores sensibles como claves de API, tokens y datos personales. Al usar una herramienta en línea, conviene comprobar si los datos que introduces se envían a un servidor o se procesan solo en tu navegador. Una herramienta que procesa localmente en el navegador no envía la entrada a ningún sitio, así que incluso un JSON sensible se puede manejar con relativa tranquilidad.
Aun así, si vas a compartirlo, acostúmbrate a borrar antes valores como tokens y contraseñas o a sustituirlos por valores ficticios. Formatear y validar solo ayuda con la sintaxis y la presentación; no sustituye la seguridad de los datos ni la validación del esquema (estructura de campos).
Dudas frecuentes
¿Qué significa un error 'Unexpected token'?
Significa que el analizador encontró en esa posición un carácter que no puede aparecer allí. La causa suele ser una coma o una comilla que falta justo antes, o una coma final que quedó. Mira primero la zona a la que apunta el número de posición del mensaje. Si añades sangría y despliegas la estructura, la línea causante se ve mucho mejor.
¿Puedo usar un objeto de JavaScript como JSON tal cual?
En general, no. Un objeto de JavaScript puede tener claves sin comillas y usar comillas simples, comas finales, comentarios y undefined, pero JSON prohíbe todo eso. Para obtener un JSON válido, cambia las claves y cadenas a comillas dobles, quita las comas finales y los comentarios, y sustituye undefined por null.
El texto con acentos o caracteres no latinos se ve mal. ¿Está mal el JSON?
Normalmente es un problema de codificación (cómo se muestran los caracteres), no de sintaxis. JSON puede contener Unicode tal cual, así que comprueba que el archivo esté guardado en UTF-8 y se abra con la misma codificación. Si las comillas se han cambiado por comillas tipográficas en lugar de comillas dobles normales ("), eso sí es un error de sintaxis y debes sustituirlas por comillas normales.