¿Se permiten comentarios en JSON? RFC 8259 dice que no, pero aquí tienes 4 soluciones

¿JSON admite comentarios? — la respuesta corta

No. RFC 8259 no permite comentarios // ni /* ... */ en ninguna parte de un documento JSON. La prohibición es estructural: la gramática de la Sección 2 los excluye, por lo que un analizador estricto debe rechazar cualquier comentario con un error "Unexpected token". La Sección 9, sin embargo, establece que un analizador "MAY accept non-JSON forms or extensions" (puede aceptar formas o extensiones que no sean JSON); esa única frase es la razón por la que JSONC y JSON5 pueden existir como alternativas legítimas.

Si necesitas comentarios en tu JSON, tienes cuatro opciones prácticas:

• JSONC — JSON con comentarios, usado por VS Code
• JSON5 — un superconjunto de JSON bien especificado que además añade comentarios, comas finales y más
• Un campo alternativo como "_comment": "..." que vive dentro del propio JSON
• Eliminar los comentarios antes de pasar el archivo a un analizador estricto

Este artículo recorre cada opción, explica cuándo elegir cada una y muestra cómo convertir un archivo JSON con comentarios en JSON limpio que puedas usar en cualquier lugar.

Decisión rápida:

• Si estás editando un archivo de configuración de VS Code o de Microsoft: usa JSONC
• Si estás eligiendo un formato de configuración para un proyecto nuevo: usa JSON5
• Si el analizador es estricto y no puedes cambiarlo: usa un campo _comment o elimina los comentarios

Una vez que elimines los comentarios, puedes formatear y verificar el resultado en el Formateador de JSON de FormatArc; todo se ejecuta en el navegador y nada sale de tu equipo. Para consejos sobre cómo producir una salida JSON limpia y revisable, consulta Consejos para formatear JSON.

Qué dice realmente RFC 8259 sobre los comentarios

RFC 8259 (Internet Standard 90, diciembre de 2017) no contiene la palabra "comment" en ninguna parte. Los comentarios se excluyen de forma estructural, no mediante una prohibición explícita.

La gramática (Sección 2)

Toda la gramática de JSON cabe en unas pocas líneas ABNF. Los únicos caracteres insignificantes entre tokens son cuatro bytes de espacio en blanco:

ws = *(
        %x20 /              ; Space
        %x09 /              ; Horizontal tab
        %x0A /              ; Line feed
        %x0D )              ; Carriage return

// y /* */ no están en la gramática, por lo que un analizador estricto debe rechazarlos con un error "Unexpected token". Esa es la razón formal por la que todo analizador de JSON conforme al estándar rechaza los comentarios: simplemente no existe ninguna regla de producción que los acepte.

Qué PUEDEN hacer los analizadores (Sección 9)

El mismo RFC permite explícitamente las extensiones:

A JSON parser MUST accept all texts that conform to the JSON grammar. A JSON parser MAY accept non-JSON forms or extensions.

Esta única frase es la razón por la que JSONC y JSON5 pueden existir sin violar el estándar. Son "extensiones" que el RFC permite explícitamente, siempre que los datos enviados por la red sigan ajustándose a la gramática estricta para que cualquier otro analizador pueda leerlos.

La misma regla en todas las revisiones de la especificación

La especificación IETF de JSON ha pasado por tres revisiones — RFC 4627 (2006), RFC 7159 (2014) y RFC 8259 (2017) — y ninguna de ellas ha incluido jamás los comentarios en la gramática. ECMA-404, el estándar ECMA paralelo, adopta la misma postura. Los comentarios han estado fuera de JSON desde que el formato se escribió por primera vez.

Por qué la especificación de JSON no permite comentarios

Douglas Crockford, el diseñador original de JSON, eliminó los comentarios a propósito. En sus propias palabras, la gente usaba los comentarios para incrustar directivas de análisis, lo que rompía la interoperabilidad. La especificación se simplificó para que dos analizadores de JSON cualesquiera se comportaran de forma idéntica.

El resultado es que JSON es:

• Pequeño — la gramática cabe en una página
• Inequívoco — cada valor tiene exactamente una interpretación
• Portable — todos los lenguajes tienen un analizador integrado que se comporta igual

El costo es evidente: no puedes anotar un archivo JSON para explicar por qué existe una configuración. Esa es la contrapartida, y es también la razón por la que tantas herramientas recurren a un superconjunto como JSONC o JSON5.

Para conocer las reglas de sintaxis subyacentes, consulta la Guía de sintaxis de JSON.

Opción 1: JSONC — JSON con comentarios

JSONC es una extensión informal inventada en Microsoft y usada en todo VS Code. Añade dos cosas sobre JSON:

• // comentarios de una sola línea
• /* comentarios de varias líneas */

Todo lo demás es igual que JSON. Un archivo JSONC suele verse así:

{
  // Which theme VS Code should use at startup
  "workbench.colorTheme": "Default Dark Modern",

  /* Editor settings
     applied to every language */
  "editor.tabSize": 2,
  "editor.formatOnSave": true
}

El settings.json, tsconfig.json, launch.json de VS Code y muchas herramientas de Microsoft esperan JSONC. También lo verás en las configuraciones de Deno (deno.json) y en otras herramientas de desarrollo.

Cómo analizar JSONC

JSONC no es compatible con el JSON.parse integrado; necesitas una utilidad auxiliar.

Node.js:

// npm install jsonc-parser
import { parse } from "jsonc-parser";
const data = parse(sourceText);

Python:

# pip install jstyleson
import jstyleson
data = jstyleson.loads(source_text)

El propio VS Code incluye su propio analizador de JSONC; por eso puedes escribir comentarios dentro de settings.json sin que nada se rompa.

Opción 2: JSON5 — una especificación más limpia

JSON5 (json5.org) es un superconjunto de JSON especificado formalmente que añade varias comodidades de ECMAScript 5:

• Comentarios de una y de varias líneas
• Comas finales en objetos y arreglos
• Claves sin comillas (cuando son identificadores válidos)
• Comillas simples para las cadenas
• Cadenas de varias líneas con continuaciones de línea
• Números hexadecimales, puntos decimales iniciales y finales, y Infinity y NaN explícitos

Un archivo JSON5 puede verse notablemente relajado:

{
  // Feature flags for the staging environment
  features: {
    newDashboard: true,
    legacyNotifications: false,
    rateLimitRps: 0xff,
  },
  welcomeMessage: 'Hello, world',
  /* trailing commas are fine */
}

Como JSON5 tiene una especificación real, existen bibliotecas para él en casi todos los lenguajes: json5 para Node.js, pyjson5 para Python, json5 para Ruby, etc.

JSONC frente a JSON5: ¿cuál deberías usar?

Se parecen, pero tienen distintas contrapartidas.

Una regla práctica sencilla:

• Si estás editando un archivo de configuración de Microsoft o de VS Code, ya estás usando JSONC; sigue haciéndolo
• Si estás eligiendo un formato de configuración para un proyecto nuevo y quieres una especificación a la que apuntar las herramientas, elige JSON5
• Si la interoperabilidad con analizadores estrictos de JSON es crítica, quédate con JSON puro y usa el patrón del campo alternativo que se describe abajo

Soporte de implementación: qué permite realmente cada forma

La tabla siguiente compara cinco funciones "no JSON" habituales frente al estándar estricto y los dos superconjuntos. La columna RFC 8259 refleja la gramática de la RFC 8259 Sección 2 (la misma gramática codificada en ECMA-404); la columna JSON5 refleja la especificación de JSON5 publicada; la columna JSONC refleja la extensión informal de Microsoft tal como está documentada para VS Code.

La columna RFC 8259 es "No" en todas las filas porque la gramática de la Sección 2 no tiene ninguna regla de producción para ninguna de estas funciones: las cadenas deben llevar comillas dobles, las claves son cadenas y no hay ningún elemento después del último valor de un objeto o arreglo. JSON5 permite las cinco porque su especificación añade explícitamente la sintaxis de ECMAScript 5. JSONC siempre añade las dos formas de comentario y conserva las claves y cadenas con comillas dobles del JSON estricto; el soporte de comas finales depende del analizador (la especificación de JSONC dice que los analizadores PUEDEN aceptarlas, y el jsonc-parser de referencia deja allowTrailingComma desactivado de forma predeterminada), por lo que la celda dice "Opcional" en lugar de un "Sí" rotundo.

Soluciones alternativas para JSON estricto

Si no puedes cambiar el analizador — por ejemplo, porque un servicio de terceros espera JSON plano — aún puedes dejar notas dentro del archivo usando campos de cadena corrientes.

Patrón 1: el campo _comment

{
  "_comment": "Increase retries before the upstream timeout kicks in",
  "retries": 3,
  "timeout_ms": 5000
}

Las claves con prefijo de guion bajo suelen ignorarse por convención del lado del consumidor, y la mayoría del código las trata como datos corrientes. Esta es la solución más sencilla.

Patrón 2: claves hermanas para comentarios por campo

{
  "retries": 3,
  "retries_comment": "Any higher and we exceed the upstream timeout",
  "timeout_ms": 5000,
  "timeout_ms_comment": "Matches the load balancer timeout"
}

Es más extenso, pero deja claro qué comentario corresponde a qué campo.

Patrón 3: bloque de metadatos externo

{
  "$meta": {
    "generated_by": "deploy.sh",
    "purpose": "Service configuration for the staging environment"
  },
  "service": {
    "port": 8080,
    "retries": 3
  }
}

Un objeto de metadatos de nivel superior mantiene la carga útil limpia a la vez que preserva el contexto.

Estas soluciones añaden datos reales al archivo, lo que significa que los analizadores estrictos los siguen aceptando. La desventaja es que los campos adicionales pasan a formar parte del esquema y deben documentarse como tales.

Elimina los comentarios antes de usar un analizador estricto

Si tienes un archivo JSONC o JSON5 y necesitas pasarlo a un analizador estricto de JSON, tienes dos opciones: analizarlo con una biblioteca de JSONC/JSON5 y volver a serializarlo como JSON, o eliminar los comentarios con una expresión regular.

Ejemplo rápido en Node.js usando el paquete json5:

// npm install json5
import JSON5 from "json5";
import fs from "node:fs";

const source = fs.readFileSync("config.json5", "utf8");
const data = JSON5.parse(source);
fs.writeFileSync("config.json", JSON.stringify(data, null, 2));

O un enfoque mínimo con expresiones regulares — válido para archivos que controlas, pero frágil si las cadenas pueden contener //:

const stripped = source
  .replace(/\/\/[^\n\r]*/g, "")
  .replace(/\/\*[\s\S]*?\*\//g, "");
const data = JSON.parse(stripped);

El camino más seguro es siempre usar un analizador de verdad. Una vez que los comentarios hayan desaparecido, consulta Consejos para formatear JSON para manejar estructuras complejas y detectar cualquier error de sintaxis restante.

Formatea el resultado con FormatArc

Una vez que tengas JSON plano, pégalo en el Formateador de JSON de FormatArc para imprimir la salida con formato y detectar cualquier problema restante. Si el analizador sigue quejándose — normalmente con un error "Unexpected token /" — ese error casi siempre significa que todavía queda un comentario en el archivo. Consulta Cómo corregir errores de análisis de JSON para ver la lista completa de causas.

FormatArc usa el JSON.parse integrado, por lo que rechazará JSONC y JSON5 directamente. El flujo de trabajo es:

1. Eliminar los comentarios (o analizar con una biblioteca de JSONC/JSON5 y luego serializar)
2. Pegar el resultado en el Formateador de JSON
3. Leer, verificar o copiar el JSON limpio

Todo se ejecuta en el navegador: nada sale de tu equipo.

Preguntas frecuentes

¿Se permiten comentarios en JSON en RFC 8259?

No. Los comentarios en JSON no están permitidos por RFC 8259. La gramática de la especificación en la Sección 2 no tiene ninguna regla de producción para // ni /* */, por lo que cualquier analizador conforme debe rechazarlos como "Unexpected token". Las alternativas compatibles con el estándar son JSONC, JSON5 o eliminar los comentarios antes de analizar.

¿RFC 8259 dice explícitamente que los comentarios en JSON no están permitidos?

No con esas palabras — RFC 8259 nunca usa el término "comment". La prohibición es implícita. La Sección 2 define toda la gramática de JSON en ABNF y enumera solo cuatro caracteres insignificantes entre tokens (espacio, tabulación, salto de línea, retorno de carro). Como // y /* */ están ausentes de la gramática, un analizador conforme debe rechazarlos. La Sección 9 permite entonces que los analizadores acepten "non-JSON forms or extensions", que es la base legal de JSONC y JSON5.

¿Dónde dice RFC 8259 que los comentarios en JSON no están permitidos?

RFC 8259 nunca usa la palabra "comment". La prohibición es estructural: la Sección 2 define toda la gramática de JSON en ABNF, y los únicos caracteres insignificantes entre tokens son espacio, tabulación, salto de línea y retorno de carro (ws = *( %x20 / %x09 / %x0A / %x0D )). No hay ninguna regla de producción para // ni /* */, por lo que un analizador conforme debe rechazarlos como "Unexpected token". La Sección 9 permite entonces que los analizadores acepten "non-JSON forms or extensions", que es la base legal de JSONC y JSON5.

¿Por qué settings.json y tsconfig.json de VS Code permiten comentarios?

Ambos archivos son técnicamente JSON inválido según RFC 8259, pero VS Code y el compilador de TypeScript incluyen sus propios analizadores de JSONC y tratan los archivos como JSONC en lugar de JSON estricto. Este es exactamente el caso de "non-JSON forms or extensions" que la Sección 9 permite. La contrapartida es la portabilidad: otras herramientas que usan JSON.parse directamente fallarán con el mismo archivo con un error "Unexpected token /" a menos que también entiendan JSONC.

¿Puedo usar comentarios // o /* en un archivo .json normal?

No si el archivo va a ser leído por un analizador estricto como JSON.parse, json.loads o encoding/json. El analizador rechazará el archivo con un error "Unexpected token" en el primer comentario. Renombra el archivo a .jsonc y usa un cargador que entienda JSONC, o cambia a JSON5.

¿Por qué VS Code me deja escribir comentarios en settings.json?

VS Code trata settings.json y archivos similares como JSONC, no como JSON estricto. Su analizador integrado acepta comentarios // y /* */. Otros editores que usan JSON.parse para leer el mismo archivo fallarán a menos que también entiendan JSONC.

¿Es JSON5 un estándar?

JSON5 tiene una especificación publicada en spec.json5.org, pero no es un estándar de IETF ni de ECMA. Cuenta con amplio soporte en las herramientas de desarrollo, pero no es un reemplazo del JSON de RFC 8259 en las API ni en la transmisión de datos.

¿Debería usar _comment o cambiar a JSON5 para mi archivo de configuración?

Si el archivo lo leen muchas herramientas distintas — algunas de las cuales solo entienden JSON estricto — quédate con JSON plano y usa el patrón _comment. Si el archivo lo consume únicamente código que controlas, JSON5 te da comentarios reales y es menos ruidoso.

¿FormatArc admite JSONC o JSON5?

Las herramientas de FormatArc usan el JSON.parse integrado del navegador, que es estricto. Tendrás que eliminar los comentarios o analizar primero con una biblioteca de JSONC/JSON5 y luego pegar el resultado en el Formateador de JSON de FormatArc.

¿Y qué hay de YAML?

YAML admite comentarios de forma nativa con #. Si lo que más necesitas son los comentarios y puedes cambiar de formato, YAML suele ser la mejor opción para los archivos de configuración. Consulta YAML frente a JSON: diferencias clave para ver la comparación completa, o ve directo a la Guía de sintaxis de YAML.

Lecturas relacionadas

Si quieres entender mejor JSON en sí:

• ¿Qué es JSON? — los fundamentos del formato
• Guía de sintaxis de JSON — las reglas que sigue el JSON estricto

Si elegiste JSONC o JSON5 y necesitas trabajar con la salida:

• Consejos para formatear JSON — salida limpia una vez que los comentarios han desaparecido
• Cómo corregir errores de análisis de JSON — para cuando un comentario se te escapa

Si necesitas comentarios y puedes cambiar de formato:

• YAML frente a JSON: diferencias clave — la alternativa amigable para configuración
• Guía de sintaxis de YAML — aprende YAML si necesitas comentarios y más

Resumen

• El JSON estándar no admite comentarios — esto es así por diseño
• JSONC añade comentarios // y /* */ y lo usa VS Code
• JSON5 es un superconjunto formal con comentarios, comas finales y sintaxis más flexible
• Si no puedes cambiar el analizador, añade un campo _comment o un bloque de metadatos externo
• Después de eliminar los comentarios, imprime el resultado con formato en el Formateador de JSON de FormatArc