yo construyo Toolz.dev, y antes de eso pasé años enviando complementos de WordPress y API de Laravel. En todo esto, el único mensaje de error en el que he perdido más horas es alguna variación de " Token inesperado en JSON en la posición 428." No te dice casi nada. No hay línea ni columna, y la posición que nombra suele ser unos pocos caracteres más allá de lo incorrecto. Terminas contando caracteres en una masa minificada a mano, o pegando toda la carga útil en un editor y entrecerrando los ojos. Construí el Validador JSON así que nunca más tengo que hacer eso, y esta es la guía de lo que hace y por qué validar JSON es más complicado de lo que parece.
TL;Dr: Un validador JSON compara el texto con la gramática en RFC 8259 y, cuando el texto está roto, le indica la línea, columna y carácter exactos del primer error, expresados en términos de lo que esperaba. También detecta cosas que oculta un analizador normal: claves duplicadas, que se colapsan silenciosamente hasta el último valor, e informa la estructura de un documento válido (recuento de objetos, matrices y claves, profundidad de anidamiento y tamaño de bytes). No es un formateador. Un formateador asume que la entrada ya es válida; un validador es lo que se busca precisamente cuando no lo es.
¿qué significa que JSON sea válido?
JSON es un formato pequeño con una gramática estricta. El estándar actual es RFC 8259, que se alinea con ECMA-404, y entre ellos definen exactamente lo que puede contener un documento válido. Un texto JSON es un valor único. Ese valor es un objeto, una matriz, una cadena, un número, true, false, o null. Los objetos se envuelven en aparatos ortopédicos y se mantienen separados por comas "key": value pares. Las matrices están entre paréntesis y mantienen valores separados por comas. Las cadenas están envueltas en comillas dobles, nunca comillas simples. Los números siguen una forma específica sin ceros iniciales ni punto decimal final. No hay comentarios y no hay comas finales.
Esa última oración es donde la mayoría de los JSON del mundo real salen mal, porque muchas de las personas de JSON que escriben a mano no son realmente JSON. Es un archivo de configuración con // comentarios, o un objeto copiado de una fuente de JavaScript donde las comillas individuales y las comas finales están bien, o un elemento editado a mano donde alguien agregó un campo y dejó una coma colgante. Todos ellos son rechazados por un analizador estricto y un validador ' El trabajo de todos ellos es rechazarlos en un lugar específico en lugar de encogerse de hombros.
Vale la pena aclarar un punto, porque hace tropezar a las personas que aprendieron JSON hace años: un valor mínimo es un documento JSON completo y válido. 42 por sí solo es válido JSON. También lo es "hello", y también lo es true. Vechi RFC 4627 requería que el nivel superior fuera un objeto o una matriz, pero esa restricción se eliminó en 2014 cuando RFC 7159 (más tarde 8259) la reemplazó. Si una herramienta te lo dice 42 no es JSON válido, esa herramienta sigue una especificación que ha estado obsoleta durante más de una década.
¿por qué JSON.parse es un reportero de errores tan malo?
La razón por la que un validador dedicado gana su lugar es que el analizador integrado en su idioma está optimizado para el camino feliz, no para explicar el triste. JSON.parse en un navegador se arroja un SyntaxError cuyo mensaje es específico del motor y generalmente le brinda un desplazamiento de carácter sin línea ni columna. V8 dice " Token inesperado } en JSON en la posición 148." Firefox dice "JSON.parse: carácter inesperado en la línea 1 columna 149." Safari vuelve a decir algo diferente. Ninguno de ellos te dice lo que esperaban y la posición se mide desde el inicio de la cadena, lo cual es inútil en el momento en que tu JSON tiene más de un par de líneas.
El validador en Toolz.dev no se utiliza JSON.parse. Pasea por el texto mismo con un analizador de descenso recursivo escrito a mano, siguiendo la línea y la columna a medida que avanza, por lo que cuando se detiene puede entregarle las tres coordenadas: la línea, la columna y el desplazamiento absoluto de caracteres. Más importante aún, conoce la regla gramatical en la que se encontraba, por lo que el mensaje es específico. En lugar de " token inesperado, " obtienes " No se permite la coma de seguimiento antes de la llave de cierre, " o " Las claves de objeto deben ser cadenas de doble cita, " o " Se esperaba una coma o una llave de cierre después de un miembro del objeto." Esa diferencia es la diferencia entre arreglar el archivo en cinco segundos y buscarlo.
También dibuja un intercalación debajo del carácter exacto en la línea ofensiva, como lo hace un compilador. Cuando miras la línea 34 de un archivo de configuración, "columna 12" está bien, pero a ^ sentarse directamente debajo de la cita perdida es más rápido.
¿qué errores JSON detecta el validador por su nombre?
Estas son las fallas que veo con más frecuencia, tanto en mi propio trabajo como en los hilos de soporte para herramientas como esta. El validador nombra a cada uno en lugar de informar un error genérico del token.
| Error | Cómo se ve | Por qué no es válido |
|---|---|---|
| Coma final | {"a": 1,} investigaciones operacionales [1, 2,] |
JSON no tiene comas finales; la gramática estándar 's simplemente no permite uno antes de un aparato ortopédico o soporte de cierre |
| Citas individuales | {'name': 'Liton'} |
Las cadenas y claves deben utilizar comillas dobles; Las comillas simples son un hábito de JavaScript, no JSON |
| Falta coma | {"a": 1 "b": 2} |
Cada miembro después del primero debe ir precedido de una coma |
| comentarios | {"a": 1} // note |
JSON no tiene sintaxis de comentarios; el // y todo lo que sigue es contenido inesperado |
| Clave no citada | {name: "Liton"} |
Las claves son cadenas y deben citarse, a diferencia de los literales de objetos JavaScript |
| Cero líder | {"n": 007} |
Es posible que un número no tenga un cero a la izquierda, por lo que 007 no es válido; escribir 7 |
| Punto decimal final | {"n": 5.} |
La fracción después de un punto decimal necesita al menos un dígito |
| Carácter de control crudo | una pestaña literal o nueva línea dentro de una cadena | Los personajes de control dentro de las cadenas deben escaparse como \t, \nși altceva |
| NaN o Infinito | {"n": NaN} |
Estos son válidos en JavaScript pero no son valores JSON |
| Cadena sin terminar | {"a": "oops} |
Una cadena sin cotización final llega hasta el final de la entrada |
Cada uno de ellos produce un mensaje en lenguaje sencillo y una posición. El caso de cero inicial es un buen ejemplo de por qué ayuda un analizador especialmente diseñado: lee un analizador genérico 007 como el número 0 y luego tropieza con el 7 como "contenido adicional," señalándote al 7, cuando el verdadero problema son los dos ceros que tiene delante. El validador primero verifica el patrón de cero inicial y se lo indica directamente.
¿qué pasa con las claves duplicadas?
Aquí está el que me ha mordido en producción más que cualquier error de sintaxis, porque no es un error de sintaxis en absoluto. Este es JSON válido:
{
"timeout": 30,
"retries": 3,
"timeout": 60
}
RFC 8259 dice los nombres dentro de un objeto " DEBERÍA ser único, " pero no prohíbe los duplicados, por lo que se requiere que un analizador acepte esto. Lo que sucede a continuación es donde comienza el problema: el estándar dice que el comportamiento con nombres duplicados es impredecible y, en la práctica, casi todos los analizadores mantienen el último valor y descartan silenciosamente los anteriores. Entonces este objeto se analiza {"timeout": 60, "retries": 3}, y el "timeout": 30 si configura cuidadosamente en la parte superior del archivo, desaparecerá sin previo aviso. Si dos personas editaron la configuración, o una combinación salió mal, o un paso de plantilla emitió la misma clave dos veces, tiene un error que ningún analizador señalará por usted.
El validador lo marca. La detección de clave duplicada está activada de forma predeterminada y, como un duplicado es legal, se informa como una advertencia y no como un error: el documento sigue siendo válido, pero se le informa cada clave que aparece más de una vez en el mismo objeto, con su línea y a Puntero JSON ruta para que puedas encontrarlo dentro de una estructura anidada. Si realmente quieres duplicados, puedes desactivar el cheque. La mayoría de las veces, ver la advertencia es el momento en que te das cuenta de lo que salió mal.
¿en qué se diferencia un validador de un formateador?
La gente usa las palabras indistintamente y las herramientas se superponen, pero responden preguntas diferentes. A Formateador JSON toma JSON que ya crees que es válido y lo reimprime con una sangría consistente para que un humano pueda leerlo. Si le entrega un formateador JSON roto, lo mejor que puede hacer es rechazarlo. Todo el propósito de un validador ' es el caso roto: le indica dónde y por qué. El validador Toolz.dev hace ambos trabajos, porque una vez que ha confirmado que un documento es válido, ya lo ha analizado, por lo que imprime bastante el resultado en el mismo pase. Pero la característica principal es el diagnóstico, no la sangría.
La misma relación se mantiene con las herramientas vecinas. El Minifier JSON elimina los espacios en blanco para reducir una carga útil, lo que sólo tiene sentido en una entrada válida. El Clasificador JSON reordena las claves para diferencias estables, nuevamente en una entrada válida. El JSON escapa y escapa la herramienta se ocupa de incrustar JSON dentro de una cadena. Y el Probador JSONPath consulta un documento que ya has confirmado que está bien formado. La validación es el paso que viene antes que todos ellos, por lo que es el que ejecuto primero cada vez que una respuesta API o un archivo de configuración se comporta de manera extraña. Hay un recorrido más amplio por cómo encajan en el Guía definitiva de las herramientas JSON.
¿Qué te dicen las estadísticas de estructura?
Cuando un documento se valida, la herramienta informa su forma: cuántos objetos y matrices contiene, cuántas claves, cuántas cadenas, números, booleanos y nulos, qué tan profundamente anida y su tamaño tanto en caracteres como en UTF-8 bytes. Esto no es decoración. Cuando le entregan una respuesta API desconocida, el número de profundidad le indica de un vistazo si está tratando con un registro plano o un árbol profundamente anidado, y el recuento de claves le indica aproximadamente cuánto trabajo analizará.
La cifra de bytes importa más de lo que la gente espera. Los límites de tamaño de solicitud, los límites de cola de mensaje y los límites de columna de la base de datos casi siempre se miden en bytes, no en caracteres, y los dos difieren en el momento en que su JSON contiene algo fuera de ASCII. Un emoji o un nombre acentuado es un carácter en la pantalla pero dos, tres o cuatro bytes en el cable. Si una carga útil choca con un límite de 256 KB, el recuento de caracteres lo engañará y el recuento de bytes no. El validador calcula la longitud real de los bytes UTF-8 para que el número que ve sea el número que cuenta el límite.
Cómo lo uso
Mi flujo de trabajo es aburrido y rápido, que es el punto. Cuando se rompe una integración, copio el cuerpo de respuesta sin procesar directamente de la pestaña de red y lo pego en el validador. Si es válido, el resultado verde y las estadísticas me dicen que el problema está en otro lugar, en mi código en lugar de en sus datos, y he descartado toda una clase de causas en dos segundos. Si no es válido, obtengo la línea y la columna, las arreglo y sigo adelante. Cuando edito manualmente un archivo de configuración, lo pego antes de comprometerme, principalmente para captar la coma final que siempre parezco dejar atrás y la clave duplicada ocasional de una copia y pegado. Para cualquiera que monte su propio kit, el validador se ubica junto con los demás elementos esenciales del Kit de herramientas para desarrolladores web.
El ángulo de la privacidad tampoco es una ocurrencia tardía. El JSON que más necesitan validar es exactamente el JSON con el que deberían tener más cuidado: respuestas API que lleven tokens, archivos de configuración con credenciales, cargas útiles con datos de clientes. Todo lo que hace el validador sucede en su navegador, en JavaScript, en su máquina. No se carga, registra ni almacena nada. Puede demostrarlo abriendo la pestaña de red mientras valida o desconectándose de Internet y observando cómo la herramienta sigue funcionando.
Preguntas frecuentes
¿por qué mi JSON dice que no es válido cuando se ve bien?
Las razones más comunes son una coma final antes de un aparato ortopédico o corchete de cierre, comillas simples donde JSON requiere comillas dobles, una coma faltante entre dos miembros o un comentario, que JSON no permite en absoluto. Los cuatro son fáciles de pasar por alto a simple vista, especialmente en un archivo grande. El validador nombra cuál encontró y le da la línea y columna exactas, por lo que en lugar de escanear el documento completo, saltas directamente al carácter en el que se detuvo.
¿es válido un solo número o cadena JSON por sí solo?
Sí. Según RFC 8259, cualquier valor JSON es un texto JSON completo, por lo que 42, "hello", truey null todos validan por sí mismos. La regla de que el nivel superior tenía que ser un objeto o una matriz proviene del antiguo RFC 4627 y se eliminó en 2014. Una herramienta que rechaza un valor mínimo sigue una especificación obsoleta.
¿el validador cambia o carga mis datos?
No. Analiza el texto de su navegador y nunca lo envía a ninguna parte. En un documento válido produce una copia bastante impresa para mayor comodidad, pero esa copia se genera localmente y el original nunca se transmite, registra ni almacena. Debido a que no hay servidor de ida y vuelta, la herramienta también funciona con la red desconectada una vez que la página se ha cargado.
¿por qué debería importarme las claves duplicadas si el JSON sigue siendo válido?
Porque un duplicado casi siempre significa pérdida de datos que no pretendía. El estándar permite claves duplicadas pero deja su manejo indefinido y, en la práctica, los analizadores conservan solo el último valor y eliminan el resto. Entonces una configuración donde timeout aparece dos veces y pierde silenciosamente la primera configuración. El validador le advierte sobre cada tecla repetida con su posición, que suele ser el momento en que detecta una combinación incorrecta o un error de copiar y pegar.
¿puede esto validar JSON con comentarios, como un archivo de configuración de tsconfig o VS Code?
No, y eso es deliberado. Esos archivos son JSON con Comentarios (JSONC) o JSON5, que son formatos separados que relajan las reglas. El validador apunta al estricto RFC 8259, por lo que marcará un comentario como un error. Si necesita comentarios en un archivo de configuración, esa es una señal de que el formato debe ser algo creado para él, como YAML o TOML, en lugar de que JSON se extienda más allá de lo que permite el estándar.
¿cuál es la diferencia entre validar y formatear JSON?
La validación comprueba si el texto obedece a la gramática JSON y, si no es así, le indica exactamente dónde se rompe. El formato supone que el texto ya es válido y solo ajusta sus espacios en blanco para facilitar la lectura. Buscas un validador cuando algo anda mal y necesitas saber qué; buscas un formateador cuando todo está bien y solo quieres que sea legible. Esta herramienta hace ambas cosas, pero su razón de existir es el diagnóstico.
¿Qué tamaño de archivo puedo validar?
Cómodamente en decenas de megabytes, limitado únicamente por la memoria de su navegador 's, porque todo el documento se analiza en una sola pasada en su dispositivo. No hay límite de tamaño de carga porque no hay carga. Para un archivo realmente enorme, en los gigabytes, un validador de línea de comandos de transmisión es el mejor instrumento, ya que el navegador guarda todo el texto en la memoria a la vez.
