¿Puede JSON tener comentarios? La respuesta completa

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

Douglas Crockford, el creador de JSON, eliminó intencionalmente los comentarios de la especificación. Explicó públicamente su razonamiento:

"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."

La preocupación era que si JSON soportara comentarios, los desarrolladores y herramientas comenzarían a insertar instrucciones dentro de los comentarios (como indicaciones para el parser, directivas de preprocesamiento o metadatos). Diferentes herramientas los interpretarían de manera diferente, rompiendo la compatibilidad universal que hace valioso a JSON.

JSON fue diseñado como un formato puro de intercambio de datos — nada más. Transporta datos entre sistemas. No es un lenguaje de configuración, no es un lenguaje de programación y no es un formato de documento.

Al mantener la especificación extremadamente simple (sin comentarios, sin comas finales, sin comillas simples), JSON permanece universalmente analizable por cada lenguaje y cada plataforma sin ambigüedad.

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?