JSON con comentarios

JSONC (JSON con Comentarios) extiende el JSON estándar para permitir comentarios estilo JavaScript. Muchas herramientas de desarrollo usan JSONC para archivos de configuración donde los comentarios ayudan a documentar los ajustes. Este analizador elimina los comentarios para producir JSON válido preservando la estructura de datos.

Especificaciones

• jsonc-parser (VS Code)
• TypeScript tsconfig.json

Casos de uso comunes

• Analizar tsconfig.json y jsconfig.json para proyectos TypeScript/JavaScript
• Leer settings.json de VS Code y configuración de extensiones
• Procesar archivos de configuración wrangler.jsonc de Cloudflare
• Editar configuraciones de ESLint, Prettier y otras herramientas con documentación en línea

Funcionalidades

• Analizar comentarios de línea única (// comentario)
• Analizar comentarios multilínea (/* comentario */)
• Manejar comas finales (comunes en archivos JSONC)
• Eliminar comentarios para producir salida JSON válida
• Todas las funciones del analizador JSON estándar (vista de árbol, conversión)

Ejemplos

{
  // Compiler options for the project
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    /* Enable all strict type checking options */
    "strict": true
  }
}

Consejos

• VS Code, TypeScript y muchas herramientas modernas soportan JSONC de forma nativa.
• Al compartir configuración, considere si las herramientas de los destinatarios soportan comentarios.
• Convierta a JSON estándar eliminando comentarios cuando las herramientas requieran JSON estricto.

Comprender JSON con comentarios

JSONC (JSON con Comentarios) es una extensión del JSON estándar que permite comentarios de línea única (//) y multilínea (/* */) estilo JavaScript, así como comas finales después del último elemento en arrays y objetos. Si bien no es un estándar oficial, JSONC se ha convertido en el formato de facto para archivos de configuración orientados al desarrollador donde la documentación en línea mejora la mantenibilidad.

Microsoft popularizó JSONC a través de Visual Studio Code, que lo usa para settings.json, keybindings.json, launch.json y extensions.json. El tsconfig.json de TypeScript y el jsconfig.json de JavaScript son archivos JSONC, al igual que muchos archivos de configuración de ESLint, Prettier y Babel cuando usan la extensión .json. El wrangler.jsonc de Cloudflare usa explícitamente la extensión .jsonc para señalar el soporte de comentarios.

La ventaja clave de JSONC sobre JSON simple es la documentación. Los archivos de configuración a menudo contienen ajustes cuyo propósito no es obvio solo por el nombre de la clave. Los comentarios permiten a los desarrolladores explicar por qué existe un ajuste, cuáles son los valores válidos y cuáles son las consecuencias de los cambios. Las comas finales reducen el ruido en el control de versiones al permitir que el último elemento tenga el mismo formato que todos los demás, de modo que agregar un nuevo elemento solo muestra una línea cambiada en un diff en lugar de dos.

Internamente, los analizadores de JSONC funcionan eliminando comentarios y comas finales antes de pasar el resultado a un analizador JSON estándar. Esto significa que el modelo de datos es idéntico al de JSON — los comentarios son metadatos para humanos, no datos para programas. Al convertir JSONC a JSON para herramientas que requieren conformidad estricta con JSON, los comentarios simplemente se eliminan. La biblioteca node-jsonc-parser de Microsoft, usada en VS Code, es la implementación de referencia para el análisis de JSONC.

JSONC no es un estándar oficial definido por ningún RFC o especificación ECMA. Es una convención popularizada por Microsoft a través de VS Code y TypeScript, con comportamiento bien definido por la biblioteca jsonc-parser que sirve como implementación de referencia. Otras herramientas que soportan JSONC — ESLint, Prettier y varios editores — siguen las mismas convenciones para comentarios de línea única, comentarios multilínea y comas finales. Los archivos JSONC comunes incluyen tsconfig.json y jsconfig.json (TypeScript/JavaScript), archivos de configuración de VS Code (settings.json, launch.json, tasks.json, keybindings.json), wrangler.jsonc (Cloudflare Workers), devcontainer.json (VS Code Dev Containers) y varias otras configuraciones de herramientas. Cualquier archivo JSON editado principalmente por desarrolladores que podría beneficiarse de comentarios probablemente soporta JSONC.

JSONC solo debe usarse para archivos de configuración leídos por herramientas con soporte explícito de JSONC. Las respuestas de API, el almacenamiento de datos y la comunicación entre servicios siempre deben usar JSON estándar, ya que la mayoría de los analizadores JSON rechazarán los comentarios como errores de sintaxis. Para procesar un archivo de configuración JSONC programáticamente con un analizador JSON estándar, elimine primero los comentarios usando una biblioteca compatible con JSONC.

JSONC es más conservador que JSON5, que es un superconjunto más extenso de JSON. Mientras que JSONC agrega solo comentarios y comas finales, JSON5 también permite cadenas con comillas simples, claves de objeto sin comillas, números hexadecimales, puntos decimales iniciales y finales, Infinity y NaN, y cadenas multilínea. JSONC tiene un soporte más amplio en el ecosistema de desarrollo, mientras que JSON5 se usa en archivos de configuración específicos como babel.config.json5 de Babel pero tiene una adopción más limitada en general.