Cómo añadir comentarios en archivos JSON: Métodos, ejemplos y mejores prácticas

Portada » Programación » Cómo añadir comentarios en archivos JSON: Métodos, ejemplos y mejores prácticas

Trabajar con archivos JSON es el pan de cada día para quienes desarrollan software, aplicaciones web o gestionan configuraciones modernas. Sin embargo, algo tan habitual como dejar un comentario explicativo dentro del archivo puede convertirse en una auténtica pesadilla, ya que el formato JSON, por su propia naturaleza, no permite comentarios de forma oficial. Muchos se preguntan cómo es posible documentar la estructura o aclarar partes específicas de los datos sin que esto suponga un error de análisis o una mala práctica.

A lo largo de este artículo vas a conocer por qué JSON no permite comentarios, las mejores alternativas que existen a día de hoy –porque claro, los desarrolladores siempre encuentran formas de sortear limitaciones– y las implicaciones que tiene cada método. Además, descubrirás cómo evitar problemas de compatibilidad y cuáles son las soluciones más inteligentes si necesitas anotar archivos JSON para trabajar en equipo o entender futuros cambios.

¿Por qué JSON no soporta comentarios de forma nativa?

Antes de meternos en faena con los trucos y alternativas, es importante entender el origen del problema. JSON (JavaScript Object Notation) nació como un formato sencillo y eficiente para el intercambio de datos entre sistemas. Su principal virtud es precisamente esa simplicidad: solo admite estructuras de datos como objetos, matrices, cadenas, números, booleanos y valores nulos. No hay espacio reservado para metainformación o para esos comentarios explicativos tan útiles en otros lenguajes de programación.

Esta limitación no es un descuido, sino una decisión de diseño deliberada tomada por Douglas Crockford, creador y principal impulsor del formato. Según explicó él mismo, eliminó los comentarios de la especificación porque mucha gente los usaba para introducir directivas de análisis que, al final, podían provocar incompatibilidades entre diferentes aplicaciones o dificultar el procesamiento automático. La idea era que JSON fuera lo más universal y predecible posible, sacrificando aspectos como la documentación interna en aras de la interoperabilidad.

Si alguna vez has intentado usar los típicos comentarios // comentario, /* comentario */ o incluso # comentario al estilo de Python o Bash en un archivo JSON, te habrás encontrado con el error “Comments are not permitted in JSON”. Ni siquiera es posible saltarse la restricción con algún tipo de hack sencillo: los analizadores (“parsers”) estándar se negarán a leer archivos con contenido que no se ajuste 100% al formato.

¿Qué problemas genera la ausencia de comentarios en JSON?

La imposibilidad de añadir comentarios tiene consecuencias prácticas que pueden afectar desde proyectos personales hasta el desarrollo de grandes aplicaciones empresariales:

• La documentación dentro del propio archivo JSON es inexistente. Esto dificulta entender la función de cada clave o el porqué de ciertos valores, sobre todo cuando pasa el tiempo o diferentes personas trabajan con el mismo archivo.
• Modificaciones, ampliaciones o revisiones deben hacerse sin poder justificar cambios directamente en el archivo, lo que puede llevar a confusiones en proyectos colaborativos.
• Los errores por olvido o interpretación son más propensos, ya que nadie podrá explicar en línea qué hace cada parte o cuál es la lógica detrás de una estructura compleja.

Al no haber una manera oficial de insertar comentarios, la comunidad ha desarrollado diferentes estrategias y trucos para documentar, aunque sea de forma indirecta, el contenido de los JSON.

Soluciones alternativas: cómo incluir comentarios en archivos JSON

A pesar de que la especificación prohíbe los comentarios al estilo habitual, existen diversas formas de documentar archivos JSON. Cada una tiene sus ventajas, limitaciones y riesgos, por lo que es importante conocerlas antes de decidir cuál utilizar en función de tu proyecto.

1. Añadir claves especiales para comentarios (la solución más común)

Sin duda, la técnica más extendida y sencilla consiste en añadir pares clave-valor cuyo objetivo sea actuar como comentario. Normalmente se emplean nombres de clave poco probables, como _comentario o __nota__, que no colisionan con ninguna de las claves de los datos “reales”.

Ejemplo básico:

{
  "_comentario": "Este es un archivo de configuración para la aplicación X",
  "usuario": "JohnDoe",
  "permisos": ,
  "activo": true
}

El objetivo es que las aplicaciones que consuman el JSON ignoren estas claves, o bien que los desarrolladores las reconozcan de inmediato como comentarios y no como información relevante para el funcionamiento.

Ventajas:

• Permite añadir explicaciones dentro del propio archivo, junto a cada campo que lo necesite.
• Compatible con cualquier herramienta que respete el estándar JSON (siempre y cuando ignore las claves que no reconoce).

Inconvenientes:

• Estos “comentarios” pasan a ser parte de los datos. Si el archivo se utiliza en una API pública o en entornos productivos donde el tamaño importa, este método puede incrementar innecesariamente el peso de la carga.
• Al ser una convención no oficial, podría haber problemas si en un futuro el esquema JSON legítimamente necesita una clave con el mismo nombre.
• Cualquier parser que espere exclusivamente determinadas claves puede fallar si aparecen estas entradas inesperadas.

2. Variantes no oficiales de JSON: JSONC

Otra opción que ha ganado popularidad entre los desarrolladores es emplear JSONC (JSON con comentarios), un formato no oficial que sí permite incluir comentarios usando // y /*...*/. Sin embargo, estos archivos JSONC requieren de un preprocesador: una herramienta que elimina los comentarios antes de pasar el archivo a cualquier analizador estándar.

Ejemplo de JSONC:

{
  // Usuario administrador de la app
  "usuario": "admin",
  /* Configuración avanzada de permisos */
  "permisos": 
}

Para trabajar con JSONC puedes encontrar herramientas en línea, paquetes de Node.js o extensiones de editores como Visual Studio Code que soportan este formato mientras desarrollas. Una vez que tu archivo está listo para ser enviado a producción, el preprocesador elimina los comentarios y genera un JSON válido.

Pros: Facilita la documentación mientras desarrollas, sin contaminar los datos finales.

Contras: Es un método válido sólo en fase de desarrollo. Si olvidas procesar el archivo antes de usarlo, los analizadores se quejarán.

3. Documentación externa: la opción más segura

Para proyectos donde el cumplimiento estricto del estándar JSON es incuestionable, la recomendación más segura es mantener la documentación fuera del propio archivo. Puedes hacerlo creando un archivo markdown o de texto plano, donde expliques la estructura, el propósito de cada campo y cualquier detalle relevante. También es común emplear documentación en la wiki del proyecto, o herramientas como Swagger/OpenAPI si se trata de definir APIs.

Ventajas:

• No hay forma de romper la compatibilidad con analizadores ni se incrementa el tamaño de los datos.
• Evita conflictos de nombres y mantiene el archivo JSON limpio y centrado solo en los datos.

Desventajas:

• La documentación queda separada. Si alguien edita el JSON sin actualizar el documento externo, puede surgir descoordinación.
• Resulta menos práctico para proyectos pequeños o para quienes prefieren encontrar toda la información en un solo lugar.

4. Preprocesadores y herramientas de build

Ampliando la estrategia de JSONC, en proyectos grandes muchas veces se utilizan preprocesadores personalizados que permiten incluir comentarios o directivas especiales en los archivos de configuración. Estas herramientas, integradas en el proceso de construcción de la aplicación, se encargan de limpiar todos los comentarios antes de desplegar el producto en producción.

Este método combina la comodidad de la documentación interna con la seguridad del cumplimiento del estándar, pero requiere un flujo de trabajo más sofisticado y atención para no subir accidentalmente archivos sin procesar.

Ejemplos avanzados: comentarios en estructuras JSON complejas

Los casos prácticos muestran cómo se pueden aprovechar las convenciones para documentar archivos JSON, incluso cuando hay objetos anidados o arrays.

Ejemplo con varios comentarios diferenciados:

{
  "_comentario1": "Datos personales básicos",
  "nombre": "Ana",
  "edad": 28,
  "ciudad": "Madrid",
  "_comentario2": "Información del trabajo",
  "empresa": "InnovaSoft",
  "puesto": "Desarrolladora",
  "experiencia": 5
}

Si necesitas añadir comentarios dentro de objetos anidados:

{
  "nombre": "Luis",
  "_comentario": "Información adicional",
  "datosAdicionales": {
    "correo": "luis@email.com",
    "_comentario": "Este correo debe ser verificado por el usuario"
  }
}

Recuerda: JSON no permite claves repetidas en el mismo nivel de objeto, por lo que si necesitas poner varios comentarios, tendrás que asignarles nombres únicos como _comentario1, _comentario2, etc.

Implicaciones y consideraciones al documentar archivos JSON

Utilizar cualquiera de los métodos anteriores tiene efectos colaterales que es importante considerar antes de tomar una decisión definitiva:

• Las claves de comentario ocupan espacio y viajan al backend, a la API o hacia cualquier sistema que consuma el JSON. Si la eficiencia es crítica, es mejor evitar la sobrecarga.
• Ciertos esquemas, como los contratos de APIs públicas, pueden rechazar archivos con claves inesperadas. Consulta siempre la documentación oficial del servicio antes de añadir comentarios de este tipo.
• Si el proyecto evoluciona y algún día necesitas utilizar una clave que ya usabas como comentario, pueden surgir incompatibilidades. Procura elegir nombres poco habituales para minimizar el riesgo.
• Algunos analizadores JSON permiten la existencia de claves desconocidas, otros no. La portabilidad puede verse afectada dependiendo del lenguaje o biblioteca que uses.

Diferencias con otros formatos de datos: YAML y XML

Quizá te estés preguntando por qué formatos muy utilizados como YAML o XML sí permiten comentarios y JSON no. La respuesta está en el enfoque de cada formato.

YAML destaca por su legibilidad y por permitir comentarios precedidos por # en cualquier parte del archivo. XML, por su parte, hace uso de las etiquetas para insertar explicaciones que serán ignoradas por los parsers.

JSON, como hemos visto, prioriza la universalidad y la mínima complejidad, eliminando cualquier elemento que no forme parte de los datos; de ahí su popularidad en APIs, configuraciones y entornos donde la eficiencia, la rapidez y la compatibilidad son cruciales.

¿Qué riesgos conlleva el uso de métodos no estándar?

Implementar soluciones alternativas no está exento de riesgos. Los más importantes son:

• Pérdida de datos: si un futuro estandariza alguna de las claves de comentario, podrías perder información o generar un conflicto en la aplicación.
• Confusión y malos entendidos: otros desarrolladores pueden no estar familiarizados con tu convención y pensar que las claves de comentario son datos reales.
• Errores en el análisis: si tu JSON llega a un sistema que espera un esquema rígido, la inclusión de campos no contemplados puede suponer un rechazo del archivo o un fallo silencioso.

Preguntas clave sobre los comentarios en JSON

• ¿Hay alguna forma oficial de añadir comentarios en JSON? No, la especificación no lo permite.
• ¿Por qué no existe soporte oficial? Para mantener JSON lo más simple, rápido y compatible posible.
• ¿Qué alternativas tengo? Añadir claves personalizadas para comentarios, usar preprocesadores en fase de desarrollo o mantener la documentación en archivos externos.
• ¿Hay riesgos al añadir comentarios de forma no estándar? Sí, sobre todo en cuanto a compatibilidad, confusión de datos y potencial pérdida de información.
• ¿Puedo usar JSONC en producción? No es recomendable. Sólo debe usarse en entornos de desarrollo junto a un preprocesador que limpie los comentarios antes del despliegue.
• ¿Qué pasa si mi archivo JSON con comentarios llega a una API externa? Lo más probable es que reciba un error y el archivo sea rechazado.

Recomendaciones y mejores prácticas para documentar archivos JSON

En función del entorno y los requisitos de tu proyecto, puedes elegir la alternativa que mejor se adapte a tus necesidades. Algunas pautas útiles:

• En desarrollo, usa claves de comentario o JSONC si te resulta útil. Pero no olvides limpiar los archivos antes de lanzarlos a producción.
• Para proyectos de largo recorrido o colaborativos, apuesta por la documentación externa: es la opción más segura, escalable y universal.
• Si tienes que incluir comentarios por fuerza dentro del archivo, utiliza convenciones claras y nombres de clave imposibles de colisionar, como __nota_privada_dev__ o similares.
• Revisa siempre la compatibilidad con las herramientas, APIs o sistemas externos que van a consumir tus archivos JSON.

En esencia, trabajar con JSON implica aceptar sus reglas: nada de comentarios oficiales, pero siempre hay margen para la creatividad. Si necesitas dejar anotaciones para ti o tus compañeros, elige la opción menos invasiva, documenta bien tus convenciones y mantiene siempre la vista puesta en la compatibilidad futura. Aunque resulta fastidioso no poder dejar aclaraciones dentro del propio archivo, precisamente ahí está el reto y el valor del diseño minimalista de JSON.