JSON no tiene comentarios porque su diseñador los sacó a propósito. Douglas Crockford, quien formalizó la especificación de JSON a principios de los 2000, explicó después el motivo él mismo: había visto a gente meter directivas de parseo dentro de comentarios — instrucciones pensadas para un lector particular del archivo, escondidas dentro de lo que se suponía que era un dato plano e intercambiable. En cuanto eso empieza a pasar, dos programas que leen el mismo documento pueden discrepar legítimamente sobre qué significa, que es justo lo único que un formato de intercambio de datos no se puede permitir. Sacar la sintaxis de comentarios por completo fue la solución tajante: sin ningún lugar donde poner una directiva, nadie puede esconder una.
Lo que Crockford dijo en realidad, y lo que sugirió en su lugar
La explicación viene de una publicación pública suya, citada después muchas veces: "Quité los comentarios de JSON porque vi que la gente los usaba para transportar directivas de parseo, una práctica que habría destruido la interoperabilidad." Su sugerencia posterior fue pragmática, no absoluta — los comentarios están bien mientras nunca lleguen al parser: "Si querés comentarios en tu JSON, adelante — solo sacalos antes de dárselo a tu parser." Esa es toda la filosofía en una frase. Un paso de build, un preprocesador, un buscar y reemplazar en un editor de texto — cualquier cosa que quite el comentario antes de que JSON.parse vea el archivo conserva la única garantía del formato: todo parser conforme, en todos los lenguajes, lee los mismos bytes de la misma manera.
Dos dialectos taparon el hueco, y no son lo mismo
JSON5 es el más grande de los dos. Es un superconjunto de JSON construido también para ser un subconjunto viable de ECMAScript 5, así que además de comentarios permite strings entre comillas simples, claves de objeto sin comillas, una coma final, números hexadecimales y números con un punto decimal al principio o al final. Es genuinamente popular — en 2022 su propio proyecto reportó más de 65 millones de descargas semanales en npm, ubicándolo en el 0,1% más dependido de los paquetes, con Chromium, Next.js y Babel entre las herramientas que leen archivos de configuración escritos en él.
JSONC — JSON con comentarios — es más acotado. Mantiene la gramática de JSON casi intacta y agrega exactamente dos cosas: comentarios // y /* */, más una coma final que la mayoría de los lectores de JSONC toleran con una advertencia en vez de un error. No es tanto un formato de propósito general como un estilo de la casa: existe porque VS Code necesitaba un lugar donde poner su propia configuración con notas, y se quedó acotado a propósito.
Ninguno de los dos es JSON. Un archivo escrito en cualquiera de los dos falla en cuanto llega a JSON.parse, o a cualquier otro lector estricto — incluido el de este sitio.
Cuáles de tus archivos de configuración son en secreto qué dialecto
Acá es donde la diferencia deja de ser un dato curioso y empieza a explicar mensajes de error. package.json lo lee npm con un parser estricto: un // en cualquier parte es un error de sintaxis, sin excepciones para "solo esta vez." tsconfig.json es el caso opuesto dentro del mismo ecosistema — el compilador de TypeScript lo parsea como JSONC, así que los comentarios de línea y de bloque y una coma final no solo se toleran, son normales, y la mayoría de los editores resaltan la sintaxis del archivo en consecuencia. El settings.json, el tasks.json y el launch.json propios de VS Code usan el mismo modo JSONC. Tres archivos que terminan todos en .json, viviendo en el mismo repositorio, obedeciendo tres reglas distintas según qué programa los abra a continuación.
La extensión nunca te dice cuál regla aplica. La única forma confiable de saberlo es revisar qué es lo que realmente lee el archivo — y si no estás seguro, asumí JSON estricto y dejá los comentarios afuera, porque esa suposición nunca se equivoca.
Qué pasa cuando pegás un archivo con comentarios acá
El formateador de JSON de este sitio es estricto a propósito, igual que JSON.parse. Pegale un archivo con una línea // y va a reportar un error de sintaxis en la posición donde empieza el comentario, igual que lo haría con una coma final perdida por ahí. Eso no es un bug para reportar — un formateador que aceptara JSON5 o JSONC en silencio estaría mintiendo sobre lo que tu destino real va a hacer con el archivo, y lo único peor que un error acá es un pase falso seguido de uno real en algún lugar que importa más.
Qué escribir en lugar de un comentario
Tres salidas honestas, según para qué era realmente el comentario. Si explicaba un valor puntual, una clave hermana como "timeout_note" funciona, al costo de convertirse en un dato que tu código ahora tiene que ignorar en vez de metadata que un lector puede saltear. Si el archivo está genuinamente pensado para que lo edite una persona y lo vuelva a leer un programa que controlás vos, y los comentarios son una de varias cosas que querés recuperar, el movimiento más grande es dejar de pelearte con JSON por eso — la disyuntiva entre YAML y JSON cubre qué más ganás y perdés al cambiar. Y si el destino insiste en JSON estricto pase lo que pase, escribir el archivo fuente en JSON5 o JSONC y reducirlo a JSON plano en un paso de build te da comentarios durante el desarrollo y un archivo que no va a sorprender a nada más adelante — que es más o menos lo que Crockford sugirió desde el principio, solo que automatizado.
Un caso se resuelve solo, sin nada de esto: si el archivo que estás mirando no parsea y no entendés por qué, y resulta que tiene comentarios adentro, eso no es un problema nuevo — es el mismo caso límite que cubre cómo formatear JSON minificado, donde JSON5 y JSONC aparecen como una de las pocas razones por las que un archivo parece JSON y no lo es.
El formateador de JSON de acá no va a leer un archivo con comentarios, y te va a decir exactamente dónde se rindió en vez de adivinar — pegá un tsconfig.json ahí y el primer // es donde se detiene. Si lo que en realidad te trajo hasta acá es un archivo que no parsea por alguna otra razón, cómo formatear JSON minificado recorre el resto de la lista: comas finales, respuestas truncadas y los números que pierden precisión en silencio en el camino.
Preguntas frecuentes
¿Puedo agregar comentarios a un archivo JSON?
No al JSON estándar — no existe sintaxis de comentarios, y JSON.parse y cualquier otro parser estricto rechazan el archivo en cuanto se topan con uno. Podés escribir comentarios en un archivo JSON5 o JSONC en su lugar, o sacarlos en un paso de build antes de que el parser estricto los vea.
¿Cuál es la diferencia entre JSON5 y JSONC?
JSON5 es la extensión más grande: comentarios más claves sin comillas, strings entre comillas simples, comas finales y algunos formatos numéricos que JSON prohíbe, pensado para ser un formato que la gente escribe a mano. JSONC solo agrega comentarios y una coma final tolerada, y existe sobre todo porque Visual Studio Code necesitaba un lugar donde poner sus propios archivos de configuración con notas.
¿tsconfig.json admite comentarios?
Sí. El compilador de TypeScript lee tsconfig.json como JSONC, así que los comentarios // y /* */ y una coma final son normales ahí, aunque el archivo tenga extensión .json. package.json, que lee npm, no recibe el mismo trato y falla con el mismo comentario.
¿Por qué Douglas Crockford quitó los comentarios de JSON?
Según su propio relato, había visto a gente usar los comentarios para transportar directivas de parseo — instrucciones pensadas para un parser en particular en vez de datos — lo que rompía la garantía de que cualquier parser conforme lee un documento JSON de la misma manera. Sacar la sintaxis de comentarios por completo cerró esa puerta en vez de intentar vigilar cómo se usaban.
¿Agregar un comentario rompe package.json?
Sí, de inmediato. npm parsea package.json como JSON estricto, así que un // o un /* */ en cualquier parte del archivo es un error de sintaxis, y la instalación o el script que lo lee va a fallar antes de hacer cualquier otra cosa. No hay forma soportada de evitarlo más que sacar el comentario.
Última actualización 25 de septiembre de 2026
