¿Se permiten comentarios en JSON? No, pero hay 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

No hace falta que elimines los comentarios antes de pegar. Pega el JSON tal cual en el Formateador de JSON de FormatArc y, junto al error de análisis, aparecerá el botón "Auto-fix". Al pulsarlo verás la lista de reglas que se van a aplicar, y con "Apply" obtienes el JSON sin // ni /* */. 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.

Cómo corregir "Comments are not permitted in JSON" en VS Code

Esa advertencia la emite el servicio de lenguaje JSON de VS Code y lo que significa en realidad es "este archivo está asociado al modo JSON estricto". La solución correcta depende de quién vaya a leer el archivo:

El archivo admite comentarios de forma legítima (JSONC)

Haz clic en el indicador de lenguaje JSON en la barra de estado (abajo a la derecha), elige Cambiar el modo de lenguaje y selecciona JSON with Comments. Los subrayados desaparecen de inmediato: el archivo ahora se analiza como JSONC, el mismo modo que VS Code ya usa para settings.json y tsconfig.json.

El cambio solo dura la sesión actual del editor. Para hacerlo permanente para un archivo o un patrón de nombres, asócialo en tu settings.json:

{
  "files.associations": {
    "*.config.json": "jsonc"
  }
}

Un analizador estricto leerá el archivo

Cambiar el modo de lenguaje solo silencia al editor. Si el archivo lo consume después JSON.parse, json.loads de Python o cualquier otro analizador estricto, el error en tiempo de ejecución persiste: los comentarios tienen que desaparecer. Mueve las notas a un campo _comment o elimínalos antes de publicar.

Qué dice realmente RFC 8259 sobre los comentarios

RFC 8259Se abre en una pestaña nueva (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-404Se abre en una pestaña nueva, 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.

ECMA-404 frente a RFC 8259: ¿ambos prohíben los comentarios?

Sí. Los dos estándares que definen la gramática de JSON — ECMA-404Se abre en una pestaña nueva y RFC 8259Se abre en una pestaña nueva — dejan // y /* */ fuera de la sintaxis. Están alineados a propósito para que una sola gramática describa JSON allá donde aparezca, pero cubren superficies distintas.

Qué define realmente cada estándar

Por qué ambos llegan a la misma respuesta sobre los comentarios

La ABNF de RFC 8259 Sección 2Se abre en una pestaña nueva define solo cuatro caracteres insignificantes entre tokens (espacio, tabulador, salto de línea y retorno de carro), y ECMA-404 usa un diagrama equivalente con el mismo conjunto de espacios en blanco. Ninguno tiene una regla de producción para // ni para /* */, así que cualquier analizador conforme debe rechazar los comentarios con un error de token inesperado. ECMA-404 ni siquiera tiene una cláusula de extensiones: la única vía de escape legal es la Sección 9 de RFC 8259, y por eso JSONC y JSON5 se plantean como "extensiones que un analizador PUEDE aceptar" y no como estándares rivales.

Por qué esto explica los mensajes de error habituales

Cuando VS Code imprime "Comments are not permitted in JSON.", está aplicando exactamente esta gramática: el archivo se analiza como JSON estricto y el comentario se rechaza porque ni ECMA-404 ni RFC 8259 lo admiten. Esa misma regla es la razón de que JSON.parse devuelva "Unexpected token '/'", de que json.loads de Python diga "Expecting property name" y de que jq se queje de un "Invalid numeric literal". Todos reaccionan a la misma regla de producción ausente.

Los errores exactos que provocan los comentarios en cada analizador

La mayoría de los analizadores nunca pronuncian la palabra "comentario". Se detienen en el primer / inesperado e informan del token que esperaban encontrar, lo que hace sorprendentemente difícil rastrear el error hasta un comentario perdido. La tabla muestra lo que imprime realmente cada analizador habitual al leer este archivo:

{
  // server settings
  "host": "localhost",
  "port": 8080 /* default */
}

Las seis filas de arriba excepto VS Code se reprodujeron localmente con el fragmento anterior, usando nuestro propio benchmark. La línea de VS Code es texto de la interfaz de su servicio de lenguaje y no se puede reproducir desde la línea de comandos. Conviene fijarse en tres detalles.

• Solo VS Code nombra el problema real. Su servicio de lenguaje JSON marca cada comentario con "Comments are not permitted in JSON.", pero solo en los archivos que trata como JSON estricto. El mismo comentario en settings.json o tsconfig.json se acepta sin avisar, porque esos archivos se analizan como JSONC.
• JSON.parse y json.loads culpan al token siguiente, no al comentario. "Expected property name" o "Expecting value" significa que el analizador se detuvo en el /: la línea y la columna apuntan al comentario aunque el mensaje no lo mencione.
• jq interpreta el / como un número. "Invalid numeric literal" parece un problema de datos, pero en esa línea y columna suele ser un comentario.

Si estás ante uno de estos mensajes y el archivo no tiene comentarios visibles, el problema de sintaxis es otro: Cómo corregir los errores de análisis de JSON recorre las demás causas línea por línea.

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.orgSe abre en una pestaña nueva) 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: json5Se abre en una pestaña nueva 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 8259Se abre en una pestaña nueva Sección 2 (la misma gramática codificada en ECMA-404Se abre en una pestaña nueva); la columna JSON5 refleja la especificación de JSON5Se abre en una pestaña nueva 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, pero cuando el análisis falla puedes intercalar la reparación automática. El flujo de trabajo es:

1. Pegar el JSON con sus comentarios en el Formateador de JSON
2. Pulsar "Auto-fix" junto al mensaje de error
3. Revisar la lista de reglas y pulsar "Apply"
4. Leer, verificar o copiar el JSON limpio

La reparación automática cubre cuatro casos: comentarios de línea //, comentarios de bloque /* */, comas finales y comas duplicadas. Los // que están dentro de una cadena (por ejemplo "https://example.com") quedan intactos, así que las URL no se rompen. Las comillas simples y las claves sin comillas de JSON5 no están cubiertas: en ese caso analiza primero con una biblioteca de JSON5 y pega el resultado. 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.orgSe abre en una pestaña nueva, 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?

JSONC sí está cubierto por la reparación automática. Pega el JSON con sus comentarios en el Formateador de JSON de FormatArc y pasa por "Auto-fix" y "Apply": los // y /* */ desaparecen, y las comas finales y duplicadas se corrigen a la vez. Las comillas simples y las claves sin comillas de JSON5 quedan fuera, así que ahí conviene analizar primero con una biblioteca de JSON5 y pegar el resultado.

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

¿Y qué hay de TOML?

TOML admite comentarios con # y está pensado para archivos de configuración, así que las claves siguen siendo legibles sin necesidad de un esquema. Es mejor opción que JSON cuando editas el archivo a mano, y peor cuando los datos tienen que viajar entre servicios, porque los analizadores de TOML están mucho menos extendidos que los de JSON.

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
• Coma final en JSON: por qué falla y cómo eliminarla — el otro error de sintaxis que JSON5 permite

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
• Pega el JSON con comentarios en el Formateador de JSON de FormatArc y usa la reparación automática para quitar comentarios y comas finales antes de formatearlo