RFC 8259: Por qué JSON no permite comentarios

La respuesta corta

No. JSON no soporta comentarios. Ni comentarios de una línea, ni comentarios multilínea, ni ningún tipo de comentario.

Esto no es un descuido. Fue una decisión de diseño deliberada.

Si agregas un comentario a un archivo JSON:

{
  // This is a comment
  "name": "Alice",
  "age": 30
}

Cualquier parser JSON estándar rechazará esto con un error de sintaxis. Los caracteres // no son sintaxis JSON válida.

Lo mismo para comentarios multilínea:

{
  /* This will also fail */
  "name": "Alice"
}

Esto es JSON inválido. Fallará en cada lenguaje, cada parser, cada herramienta.

Por qué JSON no permite comentarios (RFC 8259)

Al consultar la especificación oficial que rige el intercambio de datos, la respuesta inmediata es clara: el estándar json no permite comentarios rfc 8259 prohíbe explícitamente su inclusión. RFC 8259 sirve como el documento de ingeniería definitivo para la Notación de Objetos de JavaScript a nivel mundial, estableciendo los límites de sintaxis rígidos que todos los parsers modernos deben obedecer.

Durante el desarrollo arquitectónico primario del formato, las anotaciones de texto estándar fueron consideradas activamente pero finalmente rechazadas. A medida que aumentaba su adopción generalizada, el creador del formato, Douglas Crockford, notó que los ingenieros intentaban inyectar metadatos e instrucciones en las estructuras de los archivos. La regla que establece que rfc 8259 los comentarios json no están permitidos se impuso estrictamente para evitar una fragmentación catastrófica del estándar del lenguaje.

Él observó a los desarrolladores usar incorrectamente estos bloques de sintaxis para alojar directivas de análisis (parsing) específicas, lo que corría el riesgo de destruir por completo la interoperabilidad entre diferentes plataformas y lenguajes de programación. Si las anotaciones hubieran permanecido, una carga generada por un servidor Node.js podría fallar al analizarse correctamente en un backend de Python o Java debido a comportamientos ocultos inesperados.

Para aclarar esta decisión histórica de forma permanente, Crockford emitió una declaración definitiva que explica su razonamiento de ingeniería:

"Eliminé los comentarios de JSON porque vi que la gente los usaba para contener directivas de parsing, una práctica que habría destruido la interoperabilidad."

Al prohibir completamente estas anotaciones y establecer las estrictas pautas del RFC, la especificación evita efectivamente que las directivas de análisis ocultas rompan las aplicaciones en producción. Esta simplicidad intransigente garantiza que cualquier carga JSON válida pueda analizarse de manera segura y uniforme en cualquier ecosistema de programación sin encontrar errores de tokens inesperados.

Pero necesito comentarios en mis archivos JSON

Esta es una de las frustraciones más comunes que enfrentan los desarrolladores. Tienes un archivo de configuración, quieres explicar qué hace cada ajuste, y JSON no te deja.

Aquí están tus opciones reales:

Opción 1: Usar una clave _comment

Agrega una clave que describa el siguiente valor:

{
  "_comment": "Database connection settings",
  "host": "localhost",
  "port": 5432,
  "_comment_timeout": "Timeout in milliseconds",
  "timeout": 3000
}

Esto es técnicamente JSON válido. Las claves _comment son simplemente propiedades de cadena normales. Tu código de aplicación simplemente las ignora.

Ventajas:

• JSON válido
• funciona con todos los parsers
• legible por humanos

Desventajas:

• contamina los datos con claves que no son datos
• no hay convención estándar para el nombre de la clave
• algunos esquemas rechazarán claves desconocidas

Opción 2: Usar JSON5

JSON5 es una extensión de JSON que permite:

• comentarios de una línea (//)
• comentarios multilínea (/* */)
• comas finales
• cadenas con comillas simples
• claves sin comillas

{
  // Database settings
  host: "localhost",
  port: 5432,
  timeout: 3000, // in milliseconds
}

Ventajas:

• sintaxis natural
• soporta comentarios reales
• retrocompatible con JSON

Desventajas:

• no es JSON estándar
• requiere un parser JSON5
• no soportado por la mayoría de las APIs

Opción 3: Usar JSONC (JSON con comentarios)

JSONC es el formato usado por VS Code para sus archivos de configuración (settings.json, tsconfig.json, launch.json). Permite comentarios // y /* */ pero por lo demás es JSON estándar.

{
  // Enable strict mode
  "strict": true,
  /* Compiler options
     for TypeScript */
  "target": "ES2020"
}

Ventajas:

• soportado por VS Code, configuración de TypeScript, configuración de ESLint
• sintaxis familiar
• ampliamente usado en herramientas

Desventajas:

• no es JSON estándar
• no funciona con JSON.parse()
• limitado a herramientas específicas que lo soportan

Opción 4: Usar YAML en su lugar

Si necesitas un formato de configuración con comentarios, YAML los soporta de forma nativa:

# Database settings
host: localhost
port: 5432
timeout: 3000  # in milliseconds

YAML está diseñado para configuración. JSON está diseñado para intercambio de datos. Si necesitas comentarios, YAML podría ser el formato correcto para tu caso de uso.

Opción 5: Usar un archivo de documentación separado

Mantén tu JSON limpio y pon la documentación en un archivo separado:

config.json          ← datos puros, sin comentarios
config.README.md     ← explica qué hace cada ajuste

Esto mantiene tu JSON válido mientras proporciona documentación legible por humanos.

¿Qué pasa con tsconfig.json?

El tsconfig.json de TypeScript permite comentarios aunque la extensión del archivo sea .json. Esto funciona porque TypeScript usa su propio parser (parser JSONC) que elimina los comentarios antes del procesamiento. No es analizado por JSON.parse().

Lo mismo aplica para:

• settings.json de VS Code
• .eslintrc.json de ESLint
• Varios archivos launch.json y tasks.json

Estas herramientas usan parsers JSONC internamente. Los archivos parecen JSON con comentarios, pero técnicamente son JSONC, no JSON estándar.

Errores comunes

Error 1: Agregar comentarios y esperar que funcione

{
  // This WILL break
  "name": "Alice"
}

JSON.parse() lanzará:

SyntaxError: Unexpected token '/' at position 4

No hay ningún ajuste, flag u opción para hacer que JSON.parse() acepte comentarios. Siempre fallará.

Error 2: Usar comentarios hash

{
  # This is not valid either
  "name": "Alice"
}

Los comentarios hash funcionan en YAML, Python y scripts de shell. No funcionan en JSON.

Error 3: Asumir que todos los archivos .json son JSON estándar

Muchas herramientas usan extensiones de archivo .json para archivos que en realidad son JSONC o JSON5. Solo porque un archivo tiene extensión .json y contiene comentarios no significa que sea JSON válido.

Si copias un tsconfig.json con comentarios e intentas analizarlo con JSON.parse(), fallará.

Eliminar comentarios del JSON

Si recibes un archivo JSON con comentarios y necesitas analizarlo, primero debes eliminar los comentarios.

En JavaScript:

function stripJsonComments(jsonString) {
  return jsonString
    .replace(/\/\/.*$/gm, '')     // Remove single-line comments
    .replace(/\/\*[\s\S]*?\*\//g, ''); // Remove multi-line comments
}

const cleanJson = stripJsonComments(dirtyJson);
const data = JSON.parse(cleanJson);

Advertencia: Este enfoque simple con regex puede fallar si tus cadenas JSON contienen los caracteres // o /*. Para uso en producción, usa una biblioteca de análisis JSONC apropiada.

Formatear JSON de forma segura

Cuando trabajes con archivos JSON — con o sin comentarios — usa un formateador que se ejecute completamente en tu navegador. Si tu JSON contiene datos de configuración, respuestas de API o ajustes internos, no quieres que esos datos se envíen a un servidor de terceros.

El formateador JSON FmtDev procesa todo localmente. Tus datos nunca salen de tu navegador.

Puntos clave

1. JSON no soporta comentarios — esto es intencional, no un bug
2. Douglas Crockford eliminó los comentarios para prevenir el abuso de directivas de parsing
3. Usa claves _comment, JSON5, JSONC o YAML si necesitas comentarios
4. tsconfig.json usa JSONC, no JSON estándar
5. JSON.parse() siempre rechazará los comentarios — sin excepciones
6. Si debes eliminar comentarios, usa un parser JSONC apropiado, no regex
7. Formatea y valida JSON localmente — nunca envíes datos de configuración a herramientas en línea

Artículos relacionados

• Guía de formateo JSON
• Corregir errores Unexpected Token en JSON.parse
• Cómo comparar archivos JSON
• Cómo convertir CSV a JSON
• JSON vs diccionario Python: ¿cuál es la diferencia?

Preguntas Frecuentes (FAQ)

¿El JSON soporta comentarios en RFC 8259?

No. La especificación oficial de JSON (RFC 8259) no soporta comentarios de ningún tipo, prohibiendo tanto las anotaciones de una sola línea como las de varias líneas. Incluirlos desencadenará inmediatamente un error de análisis en los procesadores JSON estándar.