¿Puede JSON tener comentarios?
En resumen: RFC 8259 no tiene sintaxis de comentarios, así que los comentarios `//` y de bloque hacen que `JSON.parse` lance una excepción. Usa JSON5 o JSONC, un campo `_comment`, una descripción de Schema o YAML en su lugar.
En resumen: no pongas nunca comentarios en JSON estándar; usa JSONC o JSON5 para configuración local que solo editan personas, lleva las explicaciones a un description de JSON Schema cuando el archivo cruce sistemas, y cambia a YAML o TOML en cuanto crezca el volumen de anotaciones.
No.
Cualquier analizador que cumpla el estándar rechaza esto:
{
"port": 8080 // local development only
}
Chrome informa de SyntaxError: Unexpected token }. El analizador llegó a /, que no puede iniciar ningún valor JSON, y se detuvo.
Por qué la especificación deja fuera los comentarios a propósito
RFC 8259 define seis valores: objeto, array, número, cadena, true/false, null. No hay producción de comentario.
Los comentarios se propusieron pronto y se rechazaron por una razón concreta: en cuanto los comentarios son legales, alguien los usa para llevar directivas —inclusiones condicionales, variables de plantilla— y cada analizador desarrolla su propio dialecto. La interoperabilidad se rompe en el primer salto. JSON es deliberadamente solo datos, sin nada ejecutable dentro.
Cuatro formas de conservar tus notas
1. Usa un superconjunto. JSON5 y JSONC aceptan ambos estilos de comentario. El settings.json y el tsconfig.json de VS Code son JSONC.
El coste es real: JSON.parse sigue rechazándolos, y las APIs, los pipelines de logs y las colas de mensajes normalmente solo aceptan JSON estándar. Tu comentario se descarta silenciosamente o lanza una excepción en algún punto posterior.
2. Pon la nota en los datos.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
Funciona en todas partes, pero contamina el modelo: cada consumidor tiene que saber qué claves ignorar, y tu definición de tipo crece con un campo que no son realmente datos.
3. Usa una descripción de Schema. description está pensado para personas y herramientas. Los validadores lo exponen, los editores lo muestran al pasar el ratón, y nunca entra en el payload. Es la única opción que sobrevive al mantenimiento a largo plazo sin romper la compatibilidad.
4. Cambia el formato de archivo. Si el archivo existe para editarlo a mano, YAML o TOML admiten comentarios de forma nativa. Pelearse con JSON aquí es un esfuerzo desperdiciado.
Elegir
| Situación | Respuesta |
|---|---|
| Se envía a otro sistema, por una API o una cola | Sin comentarios; documenta en el Schema o en documentación externa |
| Configuración que solo leen personas y editores | JSONC, con extensión .jsonc |
| Necesita herramientas universales y explicación en línea | JSON estándar más description del Schema |
| Configuración larga con muchas anotaciones | Cambia a YAML |
FAQ
¿Por qué un campo _comment contamina el modelo?
Porque pasa a formar parte de los datos. Cada consumidor tiene que saber qué claves ignorar, y la definición de tipo gana un campo que no es realmente dato de negocio.
¿Debería la explicación vivir en un description de JSON Schema?
Sí. description se queda fuera del payload, mientras que los validadores lo exponen y los editores lo muestran al pasar el ratón, así que es la única opción que sobrevive al mantenimiento a largo plazo sin romper la compatibilidad.
¿Pueden JSON.parse analizar JSONC o JSON5?
No. JSON.parse sigue rechazando los comentarios, y las APIs, los pipelines de logs y las colas de mensajes normalmente solo aceptan JSON estándar, así que el comentario se descarta o lanza una excepción en algún punto posterior.
Herramientas
- Analizador de JSON5 — pega una configuración con comentarios y observa la estructura resuelta
- Formateador y validador de JSON — el JSON ilegal se informa con línea y columna, así que el comentario culpable queda a la vista