Pero los archivos JSON no soportan comentarios oficialmente. Esto hace que proporcionar contexto o explicación adicional para estos datos sea un desafío.

Este artículo te mostrará cómo incluir comentarios en archivos JSON y por qué JSON no admite comentarios de forma nativa.

¿Por qué JSON no soporta comentarios?

Según la especificación JSON, un documento JSON sólo debe contener estructuras de datos como arreglos y objetos y no incluir comentarios. Esto se debe a que JSON pretende ser un formato de datos simple y fácilmente analizable que se pueda procesar de manera rápida y eficiente.

Los comentarios, si bien son útiles para proporcionar contexto o explicación adicional para los humanos, pueden agregar complejidad al proceso de análisis. Esto ralentiza el rendimiento y aumenta el riesgo de errores.

La razón principal por la que JSON no admite comentarios es que su creador, Douglas Crockford, los eliminó deliberadamente del formato para evitar el uso indebido y mantenerlo como un formato exclusivamente de datos.

Crockford observó que algunas personas usaban comentarios para almacenar directivas de análisis, lo que podría romper la compatibilidad entre diferentes sistemas. De ahí la decisión de eliminar los comentarios para mantener la simplicidad y coherencia del formato en varios lenguajes y entornos de programación.

Como resultado, la única opción para agregar comentarios a un archivo JSON es utilizar una solución alternativa, como utilizar elementos personalizados para almacenar comentarios.

¿Cómo agregar comentarios a un archivo JSON?

Cuando agregas comentarios en el formato //, # o /* */, que se utilizan en lenguajes de programación populares, notará el error Comments are not permitted in JSON ("No se permiten comentarios en JSON").

Entonces, ¿cómo puedo agregar comentarios a mi archivo JSON?

La única forma de hacerlo es incluir comentarios como pares de datos en un archivo JSON. No es una práctica comúnmente utilizada ni recomendada, pero técnicamente es la mejor manera de agregar comentarios a su archivo JSON.

Crea un elemento personalizado dentro de tu objeto JSON, como "_comentario", para distinguirlos del resto de los datos.

{
    "_comentario": "escribe acá tu comentario JSON"
    "nombre": "John Doe",
    "edad": 35,
    "ciudad": "New York",
    "esCasado": true,
    "ocupacion": "Ingeniero de Software",
}

Nota: No es obligatorio utilizar guiones bajos. Puedes decidir utilizar dos barras, como “//comentario” o cualquier otro carácter permitido. El objetivo es dejar claro que se trata de un comentario.

Es importante tener en cuenta que este enfoque puede hacer que el archivo JSON sea más complejo y más difícil de analizar. Pero si los comentarios se agregan como elementos personalizados, se recibirán y procesarán como cualquier otro dato en JSON en el lado del servidor.

Ahora sabes técnicamente cómo agregar comentarios a tu archivo JSON. Pero, ¿cómo se pueden agregar varios comentarios? Esto es posible, pero debes recordar que JSON no permite claves de objetos duplicadas. Debe incluir letras o números únicos en el elemento de comentario, asegurándose de que sea válido y distinguible de otros elementos en el archivo JSON.

{
    "_comentario1": "Estos son datos básicos",
    "nombre": "John Doe",
    "edad": 35,
    "ciudad": "New York",
    "_comentario2": "Información marital",
    "esCasado": true,
    "nombreEsposa": "Jane Doe"
}

Cuando tengas objetos JSON anidados, puedes utilizar claves de objetos similares:

{
    "_comentario": "Estos son datos básicos",
    "nombre": "John Doe",
    "edad": 35,
    "ciudad": "New York",
    "informacionMarital": {
        "_comentario": "Información Marital",
        "esCasado": true,
        "nombreEsposa": "Jane Doe"
    }
}

Conclusión

Ahora sabes cómo agregar comentarios a tu archivo JSON. Pero debido a que estos comentarios también se procesan y se puede acceder a ellos, debes tener cuidado al agregar comentarios a archivos JSON utilizando elementos personalizados.

Gracias por leer y feliz codificación.

Cada recurso utilizado en Internet tiene un tipo de medio, también conocido como tipo MIME, que significa Extensión multipropósito de correo de Internet (por sus siglas en inglés Multipurpose Internet Mail Exension). Esta información es necesaria para las transacciones entre el servidor y el cliente.

El navegador necesita conocer el tipo de medio de los recursos que se le envían para que pueda manejarlos correctamente.

Lo mismo ocurre con el servidor. Necesita saber el tipo de recursos que se le envían para un análisis y procesamiento precisos.

¿Dónde se declara el tipo de contenido (Content-Type)?

El tipo de medio de cualquier recurso se declara en la propiedad Content-Type del encabezado de la solicitud (en el cliente, al realizar una solicitud al servidor) o en el encabezado de respuesta (en el servidor, al enviar una respuesta).

Sin declarar explícitamente el tipo de contenido de un recurso, el cliente puede intentar detectar automáticamente el tipo, pero el resultado puede no ser exacto. Por eso es importante declararlo explícitamente.

Tipos de medios

Los tipos de medios existen en varias formas. Se clasifican en varios grupos:

• application (aplicación)
• audio
• font (fuente)
• example (ejemplo)
• image (imagen)
• message (mensaje)
• model (modelo)
• multipart
• text (texto)
• y video

Estas categorías también tienen sus tipos. Por ejemplo, application/jsones un tipo dentro de applicationy text/htmles un tipo dentro de text.

Puedes encontrar una lista completa de tipos de medios en los tipos de medios de la IANA (un organismo que coordina algunos de los elementos clave en Internet).

Todos estos tipos cubren varios tipos de datos como texto, audio, imágenes, HTML y muchos más tipos que se utilizan en Internet.

El navegador necesita saber el tipo de medio de un recurso

Como mencioné anteriormente, el navegador necesita saber qué tipo de contenido recibe. He aquí un ejemplo para ilustrar eso.

El siguiente código es un servidor Node que sirve un archivo HTML:

const http = require("http");
const fs = require("fs");
const path = require("path");

const server = http.createServer(function (req, res) {
	const filePath = path.join(__dirname, "index.html");
	var stat = fs.statSync(filePath);

	res.writeHead(200, {
		"Content-Type": "text/css",
		"Content-Length": stat.size,
	});

	const readStream = fs.createReadStream(filePath);
	readStream.pipe(res);
});

server.listen(5000);

console.log("Node.js web server at port 5000 is running..");

No te preocupes por los detalles del código. Todo lo que debe preocuparte es el archivo index.htm que estamos sirviendo y que el Content-Typees text/css.

Aquí está el contenido del index.html:

<h1>Homepage</h1>

Por supuesto, un documento HTML es diferente de un archivo CSS. Aquí está el resultado de localhost:5000cuando el servidor está iniciado:

También puedes confirmar la respuesta obtenida al verificar los encabezados en la pestaña de red de DevTools.

Aquí está el resultado en un navegador Chrome:

El navegador obtuvo el contenido como un tipo CSS, por lo tanto, intentó tratarlo como CSS.

Además, ten en cuenta que el conocimiento completo del tipo de contenido obtenido por el navegador también reduce las vulnerabilidades de seguridad, ya que el navegador conoce los estándares de seguridad que debe implementar para esos datos.

Ahora que comprendes el concepto de tipos MIME y su importancia, pasemos a JSON.

El tipo de contenido correcto para JSON

JSON tiene que ser interpretado correctamente por el navegador para ser utilizado adecuadamente. text/plainse usaba normalmente para JSON, pero según IANA, el tipo MIME oficial para JSON es application/json.

Esto significa que cuando envías JSON al servidor o recibes JSON del servidor, siempre debe estar declarado el Content-Type del encabezado, como application/json por ser el estándar que entienden el cliente y el servidor.

Conclusión

Como se indicó anteriormente, el servidor (al igual que el navegador) necesita saber el tipo de datos que se le envía, por ejemplo, en una solicitud POST. Esa es la razón por la que los forms con archivos suelen contener el atributo enctype con un valor de multipart/form-data.

Sin codificar la solicitud de esta manera, la solicitud POST no funcionará. Además, una vez que el servidor conoce el tipo de datos que ha obtenido, sabe cómo analizar los datos codificados.

En este artículo, analizamos qué son los tipos MIME y su propósito. Además, analizamos el tipo de contenido oficial para JSON. Espero que ahora sepas por qué es importante declarar los tipos de recursos cuando se usan en Internet.

Si has estado teniendo problemas para agregar comentarios a un archivo JSON, hay una buena razón: JSON no cuenta con soporte para comentarios.

"Elimine los comentarios de JSON porque vi gente que los estaba usando para mantener directivas de parsing, una práctica que podría haber destruido la interoperabilidad", escribe Douglas Crockford, quien popularizo el formato de información basado en texto.

Sin embargo, existe una solución alternativa y de eso trata este artículo: como agregar comentarios a un archivo JSON.

Agregar información como comentarios

Una manera de eludir el problema de los comentarios es agregar información que funcione como comentarios a tu archivo JSON.

Ahora veamos un ejemplo, iniciando con la siguiente información en nuestro archivo JSON:

{
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

Ahora agreguemos otro par clave-valor (key-value) que servirá como nuestro comentario, lo podemos ver en la primera línea de código del siguiente ejemplo:

{
   "_comentario1": "esto es un comentario",
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

A continuación, otro ejemplo. Esta vez, usaremos dos guiones bajos al inicio y al final de la clave (key).

 "__comentario2__": "esto es otro comentario",

Los guiones bajos ayudan a diferenciar el comentario del resto de nuestra información en el archivo JSON.

Solo una pequeña advertencia

Solo hay un detalle importante a tener en cuenta.

Los comentarios que agregamos a nuestro archivo JSON están incluidos en el objeto JSON. En otras palabras, los comentarios son tratados como información.

Esto es a lo que nos referimos:

Este es el código en nuestro archivo, data.json:

{
   "_comentario1": "este es mi comentario",
   "sport": "basketball",
   "coach": "Joe Smith",
   "wins": 15,
   "losses": 5
}

Ahora vamos a leer la información del archivo, read_comments.py:

import json
with open("data.json", mode="r") as j_object:
   data = json.load(j_object)
print(data)

El resultado incluye nuestro comentario:

{'_comentario1': 'este es mi comentario', 'sport': 'basketball', 'coach': 'Joe Smith', 'wins': 15, 'losses': 5}

Incluso podemos extraer el valor del comentario del objeto JSON: este es mi comentario:

import json
 
with open("data.json", mode="r") as j_object:
   data = json.load(j_object)
   print(data["_comentario1"])

Ten en cuenta que el comentario solo es un comentario para el desarrollador—no para la computadora.

Un tipo diferente de comentario

Esta práctica de agregar comentarios en archivos JSON es diferente a los comentarios en los lenguajes clásicos de programación, tal es el caso de Python, donde es normal que los comentarios sean ignorados cuando se ejecute el programa.

# Este es mi comentario
word = "house"
for letter in word:
   print(letter)

Cuando ejecutamos el programa Python anterior, obtenemos las letras de la palabra, "house". Pero aquí no vemos el comentario, ya que es ignorado.

Otras opciones para comentar

JSMin es otra opción para considerar.

JSMin es una herramienta que elimina los espacios en blanco y los comentarios adicionales de archivos JavaScript. Pero esta también funciona en archivos JSON. JSMin elimina comentarios de archivos JSON antes de que sean analizados (parsed).

Así que, como ya vimos, existen algunas opciones cuando se trata de agregar comentarios en archivos JSON. A pesar de que no sean las mejores soluciones, al menos existe la forma de incluir documentación para cuando sea necesario.

Escribo sobre como aprender a programar y las mejores formas de hacerlo (amymhaddad.com).