¿Qué es JSON, realmente?
JSON (JavaScript Object Notation) es un formato de datos basado en texto definido en RFC 8259. A pesar del nombre, no tiene nada que ver con ejecutar JavaScript — es solo una forma de representar datos estructurados como texto plano. Todos los lenguajes de programación principales pueden leerlo y escribirlo.
El formato fue formalizado por Douglas Crockford alrededor de 2001, pero despegó porque es más simple que XML mientras es lo suficientemente legible para depurar a simple vista. Hoy es el formato de transmisión por defecto para APIs REST, archivos de configuración (package.json, tsconfig.json) y bases de datos de documentos como MongoDB.
Algo que sorprende a la gente: JSON es un subconjunto estricto de YAML 1.2. Cualquier archivo JSON válido también es YAML válido. Lo inverso no es cierto — YAML permite comentarios, strings multilínea y anchors que JSON no soporta.
Reglas de sintaxis JSON (las que realmente importan)
JSON tiene exactamente 6 tipos de datos: string, number, boolean (true/false), null, object (pares clave-valor) y array (lista ordenada). Eso es todo. Sin fechas, sin undefined, sin funciones.
Los strings deben usar comillas dobles. Las comillas simples son inválidas. Esta es la razón #1 por la que la gente obtiene errores de "unexpected token" al pegar objetos JavaScript en un archivo JSON.
Los números no pueden tener ceros iniciales (01 es inválido), no pueden usar notación hex (0xFF es inválido) y no pueden ser NaN o Infinity. Si necesitas esos valores, codifícalos como strings.
Los objetos usan llaves {} con pares clave-valor separados por dos puntos. Las claves deben ser strings entre comillas dobles. Las trailing commas después del último elemento son ilegales — este es el error de sintaxis más común en JSON editado a mano.
// ❌ INVALID — these mistakes are everywhere
{
name: "Alice", // keys must be quoted
'age': 30, // single quotes not allowed
"scores": [1, 2, 3,], // trailing comma
"id": 0x1F, // hex numbers not allowed
}
// ✅ VALID JSON
{
"name": "Alice",
"age": 30,
"scores": [1, 2, 3],
"id": 31
}Los 5 errores de JSON más comunes (y cómo corregirlos)
1. Trailing comma: Elimina la coma después del último elemento en un objeto o array. La mayoría de los formateadores lo resaltan al instante. Si quieres trailing commas, usa JSONC (JSON with Comments) en la configuración de VS Code.
2. Unexpected token at position 0: Generalmente significa que la respuesta no es JSON en absoluto — puede ser una página de error HTML (empieza con <) o un string vacío. Verifica tu endpoint de API y el encabezado Content-Type.
3. Claves sin comillas: Copiar y pegar desde la consola de JavaScript te da {name: "value"} en vez de {"name": "value"}. Pásalo por un formateador para agregar comillas automáticamente.
4. Strings con comillas simples: json.dumps() de Python siempre produce comillas dobles, pero si estás escribiendo JSON a mano o copiando de un repr() de Python, podrías tener comillas simples. Buscar-y-reemplazar no funcionará si los strings contienen apóstrofos — usa un formateador apropiado.
5. BOM (Byte Order Mark): Algunos editores de Windows anteponen un carácter invisible \uFEFF. Los parsers de JSON se atoran con esto. Abre el archivo en un editor hex — si empieza con EF BB BF, ese es tu BOM. Guarda como UTF-8 sin BOM.
JSON vs JSONC vs JSON5 vs YAML: Cuándo usar qué
JSON estándar (RFC 8259): Usa para payloads de API, intercambio de datos y cualquier cosa que necesite máxima compatibilidad. Cada parser en cada lenguaje lo soporta.
JSONC (JSON with Comments): Usa para archivos de configuración que editas a mano — configuración de VS Code, tsconfig.json, etc. Permite comentarios // y /* */ más trailing commas. No es soportado por JSON.parse() estándar.
JSON5: Extiende JSON con claves sin comillas, strings con comillas simples, números hex, trailing commas y comentarios. Bueno para archivos de configuración editados por humanos. Requiere el paquete npm json5 para parsear.
YAML: Usa cuando necesites comentarios, strings multilínea o anchors/aliases para configuración DRY. Común en DevOps (Docker Compose, Kubernetes, GitHub Actions). Cuidado: los errores de indentación son silenciosos y mortales. El "problema de Noruega" (NO se parsea como false) ha afectado a muchos equipos.
Nuestra recomendación: Usa JSON estándar para cualquier cosa que las máquinas lean. Usa JSONC o YAML para cualquier cosa que los humanos editen regularmente. No uses JSON5 a menos que tu equipo ya dependa de él.
Trabajando con archivos JSON grandes
Las herramientas basadas en navegador (incluyendo la nuestra) pueden manejar archivos hasta aproximadamente 50 MB antes de que la pestaña empiece a ponerse lenta. Para archivos más grandes, usa herramientas de línea de comandos: jq para consultas, python -m json.tool para formateo, o fx para exploración interactiva.
Si estás lidiando con archivos JSON de más de 100 MB regularmente, considera si JSON es el formato correcto. NDJSON (JSON delimitado por líneas nuevas, un objeto por línea) es streameable y no requiere cargar el archivo completo en memoria. Herramientas como jq pueden procesar NDJSON línea por línea.
Para respuestas de API, la paginación es tu amiga. Si un endpoint devuelve 10,000 objetos en una respuesta, ese es un problema de diseño de API, no un problema de JSON. Solicita páginas más pequeñas y procésalas incrementalmente.
Tip de rendimiento: JSON.parse() en V8 es en realidad más rápido que un literal de objeto JavaScript para objetos grandes (contraintuitivo pero cierto desde 2019). Si tienes un dataset estático grande en tu código frontend, envolverlo en JSON.parse('...') puede mejorar el tiempo de inicio.
Consideraciones de seguridad de JSON
Nunca uses eval() para parsear JSON. Esto era común a principios de los 2000 antes de que existiera JSON.parse(), pero ejecuta código arbitrario. Siempre usa JSON.parse() o el equivalente de tu lenguaje.
Cuidado con la contaminación de prototipos en JavaScript. Si parseas {"__proto__": {"isAdmin": true}} y lo mezclas en un objeto, podrías accidentalmente modificar Object.prototype. Librerías como lodash.merge tenían esta vulnerabilidad. Usa Object.create(null) para datos parseados que no controlas.
JSON no soporta referencias circulares. Si intentas JSON.stringify() un objeto que se referencia a sí mismo, obtendrás un TypeError. Usa una función replacer o una librería como flatted para manejar estructuras circulares.
Los límites de tamaño importan para APIs. Un payload JSON de 10 MB puede ser un vector de denegación de servicio. Establece límites de Content-Length en tu servidor (Express: express.json({limit: "1mb"}), nginx: client_max_body_size).
Validando JSON en diferentes contextos
Para validación rápida: Pega en nuestra herramienta JSON Formatter. Muestra la línea exacta y posición del carácter de los errores de sintaxis, maneja archivos hasta 50 MB y funciona offline.
Para validación de esquema: Usa JSON Schema (draft 2020-12) para definir la estructura que tu JSON debería seguir. Herramientas como ajv (JavaScript) o jsonschema (Python) validan datos contra un esquema en tiempo de ejecución. Esto atrapa errores de "JSON válido pero estructura incorrecta" que la verificación de sintaxis no detecta.
Para pipelines CI/CD: Agrega un paso de lint de JSON. El enfoque más simple: python -m json.tool < file.json > /dev/null. Para verificación más estricta con validación de esquema, usa ajv-cli o check-jsonc-syntax.
Para archivos de configuración: La mayoría de los frameworks validan su propio formato de configuración. Ejecutar next build atrapa problemas de next.config.js, tsc --noEmit atrapa problemas de tsconfig.json. No reinventes validación que tu toolchain ya provee.