Herramientas de desarrollo · JSON formateador y validador
Por qué JSON no tiene comentarios: la decisión de diseño y sus soluciones
· Antecedentes
json estándares validación
Los comentarios se eliminaron de JSON deliberadamente. Esta publicación explica el razonamiento, por qué cada intento de volver a agregarlos crea un nuevo formato y cuáles son sus opciones cuando un archivo de configuración realmente necesita una nota.
El comentario que interrumpió la compilación.
El comentario que interrumpió la compilación: una nota útil agregada a una configuración JSON y un analizador que se detuvo en la primera barra. Es posible que el autor haya copiado un patrón de JavaScript o de un editor compatible con JSONC, mientras que la herramienta de implementación utiliza el estricto JSON. El resaltado de sintaxis puede hacer que la nota parezca legítima aunque el consumidor rechace el primer marcador de comentario.
Los comentarios se rechazan porque la barra diagonal no es un token JSON donde el escáner espera un valor o miembro. ToolAcre no elimina silenciosamente la sintaxis JSONC o JSON5. Una propiedad convencional en forma de comentario son datos ordinarios y pueden violar un esquema de aplicación aunque la sintaxis estricta JSON la acepte. Las afirmaciones históricas sin fundamento sobre el diseño de JSON se omiten o corrigen en lugar de presentarse como un hecho establecido sin evidencia primaria o una fuente de estándares rastreable disponible para su verificación.
Razón de Crockford para eliminar comentarios
El motivo de Crockford para eliminar los comentarios: una explicación posterior dice que los comentarios se habían utilizado para llevar directivas de análisis, lo que socava la interoperabilidad entre implementaciones. La consecuencia de diseño relevante es que el estándar JSON no tiene ningún token de comentario. Las afirmaciones sobre motivaciones privadas, cronología exacta o respuesta universal de la industria requieren fuentes históricas no proporcionadas por este repositorio.
En consecuencia, aquí se omiten o corrigen afirmaciones históricas no respaldadas. El estándar observable y el comportamiento del analizador son suficientes: el estricto JSON intercambia datos a través de seis tipos de valores y dos contenedores, sin un canal de anotaciones. Esa restricción impide que un destinatario asigne un significado operativo al texto que otro destinatario ignora, pero también hace que JSON sea menos cómodo para la configuración mantenida manualmente.
Qué informa un validador sobre un comentario
Lo que informa un validador en un comentario: `//` y `/* */` no están en la gramática, por lo que el error aparece en la primera barra con una línea y columna. El escáner no se opone a las palabras de la nota. No puede comenzar ningún valor JSON, nombre de miembro o separador válido con `/` en esa posición.
Para `{"puerto":8080, // local únicamente "secure":false}`, la coma es válida y el siguiente token legal debe ser el nombre de una propiedad entre comillas o la llave de cierre. El corte viola esa expectativa. Eliminar solo la nota deja un separador válido y el siguiente miembro; eliminar la puntuación cercana puede crear un segundo error. Vuelva a validar la salida estricta exacta después de cada edición.
Los formatos que agregaron comentarios
Los formatos que agregaron comentarios: JSONC permite comentarios alrededor de la sintaxis JSON que de otro modo sería familiar, mientras que JSON5 agrega comodidades como claves de identificación sin comillas y comas finales. Hjson enfatiza la edición humana con una sintaxis relajada adicional. YAML tiene su propia gramática, incluidos comentarios, y no es simplemente JSON con anotaciones agregadas.
La aceptación es específica del consumidor: la configuración del editor y la configuración de TypeScript pueden usar analizadores tolerantes a comentarios, mientras que un manifiesto de paquete o un cuerpo de API pueden requerir un JSON estricto. Kubernetes comúnmente consume YAML o JSON según sus herramientas. Nombre el formato real en la documentación y el manejo de archivos; eliminar extensiones o llamar a cada notación de objeto "JSON" oculta los límites de compatibilidad.
Soluciones alternativas dentro del estricto JSON
Soluciones alternativas dentro del estricto JSON: una clave convencional `_comment` o `//` almacena la explicación como un miembro de cadena ordinario. Sobrevive al análisis estricto porque tanto la clave como el valor utilizan tokens estándar. Varias notas necesitan claves únicas o una matriz, ya que los nombres de miembros duplicados no son confiables y los analizadores pueden contraerlos.
La solución cambia el modelo de datos. Un esquema con `additionalProperties: false` puede rechazar la anotación y una aplicación puede persistirla o transmitirla como configuración real. La documentación externa, un README vecino o un esquema `description` a menudo proporcionan un canal de explicación más seguro. Utilice miembros en forma de comentarios solo cuando cada consumidor los permita e ignore explícitamente.
Ejemplo resuelto: un archivo de configuración anotado
Ejemplo resuelto: un archivo de configuración anotado; comience con una fuente JSONC que contenga `// seconds before retry` arriba de `"timeout":30`. Si el destino acepta solo JSON, utilice un analizador que comprenda JSONC para producir datos y luego serialice esos datos como estricto JSON. El artefacto implementado se convierte en `{"timeout":30}` mientras que la fuente mantenida conserva su explicación.
No elimine comentarios con una expresión regular. Las secuencias de barras diagonales pueden aparecer legítimamente dentro de cadenas como URL, y los patrones de bloques de comentarios pueden abarcar líneas de manera que el reemplazo textual sea mal manejado. Mantenga distintos los artefactos fuente y generado, valide el resultado estricto y organice la regeneración en la compilación. Esto preserva las notas del autor sin pretender que el analizador receptor las admita.
Lo que esto no cubre
Lo que esto no cubre: cómo configurar analizadores individuales para aceptar comentarios, que es específico de la herramienta y cambia con frecuencia. Una opción permisiva en una biblioteca no altera la gramática JSON ni garantiza que otro servicio acepte el mismo texto. Verifique el analizador, la versión y el destino en lugar de depender de la visualización de un editor.
Este artículo también evita afirmaciones sin fundamento sobre cuándo se eliminaron exactamente los comentarios, quién adoptó cada solución primero o si una sola decisión de diseño causó la popularidad de JSON. Tales afirmaciones históricas necesitan fuentes primarias independientes. Aquí se omiten o se corrigen; la conclusión admitida se limita a la sintaxis estricta actual, el comportamiento del repositorio y las diferencias operativas entre los formatos nombrados.
Conclusión: JSON es un formato de intercambio de datos, no un lenguaje de configuración
Conclusión: JSON es un formato de intercambio de datos, no un lenguaje de configuración rico en comentarios, y el validador muestra exactamente dónde una nota infringe la gramática estricta. Cuando los humanos necesiten anotaciones, elija un formato que la herramienta de consumo admita oficialmente o mantenga una fuente anotada que genere un artefacto estricto separado. No asuma que los comentarios serán ignorados sin causar daño.
Si el estricto JSON es obligatorio, mueva la explicación a la documentación o utilice metadatos aprobados por el esquema y luego valide el documento final. ToolAcre informa intencionalmente la primera barra en lugar de eliminar material silenciosamente, porque la conversión silenciosa podría cambiar cadenas u ocultar una discrepancia de formato. El contexto histórico debe seguir siendo igualmente disciplinado: las afirmaciones sin fundamento se omiten o se corrigen, mientras que la sintaxis observable y el comportamiento del analizador llevan la conclusión.