De JSON5 a JSONC: Desbloqueando una Experiencia de Formato JSON Más Permisiva

Cuando el JSON estricto te hace depurar hasta la madrugada por una coma faltante, quizás sea hora de conocer a sus primos más tolerantes — JSON5 y JSON con Comentarios (JSONC).

¿Qué es JSON5?

JSON5 es una extensión de JSON que incorpora características de ECMAScript 5.1: claves sin comillas, comas finales, cadenas con comillas simples, comentarios y números hexadecimales. Es mantenido por la comunidad y está diseñado para que los archivos de configuración escritos a mano sean más legibles y tolerantes que el JSON estricto.

¿Qué es JSONC?

JSONC (JSON with Comments) es una extensión mínima del JSON estándar que añade soporte para comentarios de una línea (//) y multilínea (/* */), además de comas finales. Mantenido por Microsoft, es el formato nativo de la configuración de VS Code, tsconfig.json y otros archivos de configuración de TypeScript.

Por Qué Necesitamos JSON “Permisivo”

Cuellos de botella en legibilidad: El JSON estándar prohíbe comentarios, comas finales, comillas simples, etc., lo que perjudica la claridad en configuraciones y demos.
Dolor en el trabajo en equipo: Los archivos JSON masivos sin notas en línea son difíciles de mantener; una edición menor puede romper todo el archivo.
Realidades de DevOps: Los pipelines de Kubernetes y CI/CD frecuentemente fusionan o generan JSON al vuelo; la sintaxis permisiva reduce las correcciones manuales.

JSON5 vs. JSONC de un Vistazo

Característica	JSON (estricto)	JSON5	JSONC
Comentarios de línea `//`	No	Sí	Sí
Comentarios de bloque `/* */`	No	Sí	Sí
Comas finales	No	Sí	Sí
Cadenas con comillas simples	No	Sí	No
Claves sin comillas	No	Sí	No
Signos numéricos `+` / `-`	No	Sí	No
Números hex / binario	No	Sí	No
Mantenedores del spec	ECMA	Comunidad (A. Rauschmayer)	Microsoft / VS Code

En una frase: JSON5 se parece a un objeto literal de JavaScript, mientras que JSONC es simplemente JSON estándar más comentarios.

Ejemplos de Sintaxis

JSON Puro (estricto)

{
  "name": "Go Tools",
  "features": ["Base64", "JSON Formatter"]
}

Ejemplo JSON5

// Configuración del proyecto
{
  name: 'Go Tools',      // comillas simples y claves sin comillas
  features: [
    'Base64',
    'JSON Formatter',    // coma final
  ],
  version: 1.0,          // número no string permitido
}

Ejemplo JSONC

{
  // Nombre del proyecto
  "name": "Go Tools",
  // Lista de funcionalidades
  "features": [
    "Base64",
    "JSON Formatter", // coma final
  ]
}

Soporte de Formateo y Análisis

Escenario	JSON5	JSONC	Libs / herramientas recomendadas
Navegador	Polyfill `JSON5.parse()`, Prettier con parser `json5` integrado (>= v1.13)	Soporte nativo de `settings.json` de VS Code	—
Node.js	Paquete npm `json5`	`comment-json`, `jsonc-parser`	Admiten formateo CLI y análisis AST
IDE	Extensiones para VS Code, WebStorm	VS Code nativo, plugin de WebStorm	Prettier puede unificar el formateo
CI / Lint	`eslint-plugin-json5`	`eslint-plugin-jsonc`	Integrar con Husky y lint-staged
Herramienta online	Go Tools JSON Formatter (embellece y valida JSON5/JSONC)	Igual	JSON Formatter

Formateo Rápido en VS Code

Añade a settings.json:

"[jsonc]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Luego presiona Alt + Shift + F para embellecer cualquier archivo JSONC.

Archivos de Configuración del Mundo Real

JSON5 y JSONC ya se usan ampliamente en los archivos de configuración que encuentras a diario. Aquí hay ejemplos concretos:

TypeScript (tsconfig.json — JSONC)

{
  // El modo estricto detecta más errores en tiempo de compilación
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "outDir": "./dist",
    // Alias de rutas para importaciones más limpias
    "paths": {
      "@/*": ["./src/*"],
      "@tests/*": ["./tests/*"],
    },
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
}

El tsconfig.json de TypeScript usa JSONC de forma nativa — los comentarios y las comas finales funcionan sin configuración adicional. Este es uno de los archivos JSONC más comunes en cualquier proyecto JavaScript/TypeScript.

Configuración Plana de ESLint (eslint.config.json — JSONC)

{
  "rules": {
    // Advertir sobre console.log, pero permitir console.error
    "no-console": ["warn", { "allow": ["error", "warn"] }],
    "semi": ["error", "always"],
    "quotes": ["error", "double"],
  }
}

Babel (babel.config.json5 — JSON5)

{
  // Las comillas simples y las claves sin comillas mejoran la legibilidad
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      modules: false,  // Dejar que el bundler maneje los módulos
    }],
  ],
  plugins: [
    '@babel/plugin-transform-runtime',
  ],
}

Configuración del Workspace de VS Code (.vscode/settings.json — JSONC)

{
  // Preferencias del editor
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,

  // Sobreescrituras por lenguaje
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
}

Consejos Prácticos y Advertencias

1. Convierte antes de producción

Los navegadores aún requieren JSON estricto para JSON.parse. Usa herramientas en el paso de compilación para eliminar comentarios y comas finales:

// Script de compilación Node.js: convierte config JSON5 a JSON estricto
import JSON5 from 'json5';
import { readFileSync, writeFileSync } from 'fs';

const config = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(config, null, 2));

Para bundlers, usa rollup-plugin-json5 o vite-plugin-json5 para manejar la conversión automáticamente durante la compilación.

2. Seguridad y confiabilidad

La permisividad puede ocultar campos no deseados. Valida siempre la configuración con JSON Schema o zod antes de consumirla:

// Valida la forma de la config con zod después de analizar
import { z } from 'zod';
import JSON5 from 'json5';

const ConfigSchema = z.object({
  port: z.number().min(1).max(65535),
  host: z.string(),
  debug: z.boolean().default(false),
});

const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // Lanza excepción si es inválido

3. Convenciones del equipo

Declara en el README que *.json5 es solo para configuraciones; los paquetes publicados deben distribuirse con .json estricto.
Estandariza las reglas de Prettier para evitar diffs ruidosos.
Usa .editorconfig para aplicar indentación consistente en archivos JSON, JSON5 y JSONC.

4. Rendimiento

Analizar JSON5/JSONC añade dependencias y una ligera sobrecarga — está bien para CLI y herramientas de desarrollo, pero mide en producción. El paquete npm json5 pesa ~8 KB minificado, y el análisis es aproximadamente 2-5x más lento que el JSON.parse nativo. Para archivos de configuración cargados una vez al inicio, esto es insignificante. Para rutas críticas de rendimiento que analizan miles de objetos por segundo, quédate con JSON estricto.

Preguntas Frecuentes

¿Cuál es la diferencia entre JSON5 y JSONC?

JSON5 extiende JSON con sintaxis similar a JavaScript: claves sin comillas, comas finales, comentarios de una sola línea y de bloque, números hexadecimales y cadenas multilínea. JSONC es más simple — solo añade comentarios de una sola línea (//) y de bloque (/* */) al JSON estándar. Elige JSONC para archivos de configuración donde los comentarios son suficientes; elige JSON5 cuando necesites una sintaxis más rica.

¿Puedo usar JSON5 o JSONC en APIs de producción?

No — JSON5 y JSONC están diseñados para archivos de configuración, no para intercambio de datos. Las APIs deben usar JSON estándar (RFC 8259) para máxima interoperabilidad. Reserva JSON5/JSONC para archivos de configuración locales como tsconfig.json, .vscode/settings.json o configuración de entorno donde la legibilidad humana importa más que el análisis automático.

¿VS Code admite JSON5 de forma nativa?

VS Code admite JSONC de forma nativa (sus propios archivos de configuración usan JSONC), pero no admite JSON5 de serie. Para JSON5, instala una extensión dedicada como “JSON5 syntax” desde el marketplace de VS Code. También puedes asociar archivos .json5 con el modo de lenguaje JSON5 en tu configuración.

¿Cómo convierto JSON5 a JSON estándar?

Usa el paquete npm json5: JSON5.parse() lee JSON5, luego JSON.stringify() produce JSON estándar. Para uso en CLI, ejecuta npx json5 < input.json5 > output.json. Las herramientas online como nuestro JSON Formatter también pueden validar la salida convertida para garantizar la corrección.

¿JSONC es lo mismo que JSON con Comentarios?

Sí — JSONC significa “JSON with Comments” (JSON con Comentarios) y es el formato utilizado por VS Code, TypeScript (tsconfig.json) y otras herramientas de Microsoft. Sigue el spec JSON estándar con la única adición de comentarios // y /* */. Los analizadores eliminan los comentarios antes de procesar, por lo que la estructura de datos resultante es idéntica al JSON estándar.

Para más herramientas de desarrollo en el navegador, incluyendo codificación Base64, generación de hashes y conversión de timestamps, consulta nuestra Guía esencial de herramientas para desarrolladores.

Conclusión

Equilibrar legibilidad y rigor es una lucha clásica del desarrollo. JSON5 y JSONC mejoran la experiencia de escritura, y con el pipeline de compilación y validación correcto, puedes disfrutar las ventajas del “JSON permisivo” de forma segura.

De JSON5 a JSONC: Una Guía de Formato JSON Más Permisiva