JSON explicó: Cómo formatear, validar y convertir

Los bloques de construcción de JSON

JSON está definido por el estándar ECMA-404 y RFC 8259, y toda la gramática encaja en una sola página. Sólo hay seis tipos de valores: cadenas, números, booleanos, nulos, objetos y matrices.

Un objeto es un conjunto no ordenado de pares de nombre y valor envueltos en llaves rizadas, con cada nombre escrito como una cadena en comillas dobles, seguido por un colon y un valor, y pares separados por comas. Una matriz es una lista ordenada de valores envueltos entre corchetes y separados por comas. Los objetos y arrays se pueden anidar dentro de cada uno a cualquier profundidad, que es como JSON representa registros complejos.

Las cadenas deben usar comillas dobles. Los caracteres especiales dentro de una cadena se escapan con una barra inversa, por ejemplo una barra inversa y n para una nueva línea, una barra inversa y una cita doble para una cita literal, o una barra inversa, u y cuatro dígitos hexadecimal para cualquier carácter Unicode. Los números están escritos en decimal, pueden ser negativos, pueden incluir una fracción y un exponente, y pueden no tener ceros principales. Los literales verdaderos, falsos y nulos son siempre minúsculas. El texto intercambiado entre sistemas debe codificarse como UTF-8.

Por ejemplo, un registro de usuario puede ser escrito como un objeto con el nombre id establecido a 1042, nombre establecido a la cadena Ana Torres, correo electrónico establecido a ana@example.com, activo establecido a true, roles establecidos a un array que contiene editor y facturación, y administrador establecido a null. Esa estructura usa cada tipo de valor JSON excepto un objeto anidado.

Los errores JSON más comunes

La mayoría de JSON no válido proviene de hábitos transmitidos desde JavaScript o edición a mano. Las comas de rastreo son las más frecuentes: una coma después del último elemento de un array u objeto está permitida en JavaScript moderno, pero es un error de sintaxis en JSON. Las citas individuales son otra. JavaScript acepta cadenas con una sola cita, pero JSON requiere comillas dobles tanto para nombres como para valores de cadena.

Los nombres de propiedades no citados fallan por la misma razón. Los comentarios no son parte de JSON en absoluto, por lo que una línea que comienza con dos cortes romperá el análisis, a pesar de que algunas herramientas de configuración aceptan una variante relajada que les permite. Los valores indefinidos, NaN e Infinity no existen en JSON. Los números con ceros principales, como 007, no son válidos, lo que importa para cosas como códigos ZIP y números de teléfono que de todos modos deben almacenarse como cadenas.

Otros problemas son más difíciles de ver: una ruptura de línea o pestaña en bruto dentro de una cadena, que debe ser escapado; una marca de orden de bytes al inicio de un archivo; paréntesis no emparejados en datos profundamente anidados; o dos documentos JSON separados pegados en un archivo. Cuando un analizador informa de un error, la posición que da es donde se dio por vencido, que a veces es un poco después del verdadero error, así que mira los caracteres justo antes del lugar informado.

Formato versus minificación

El espacio en blanco entre tokens no tiene significado en JSON, por lo que los mismos datos se pueden escribir en formas muy diferentes. El formato, también llamado bastante-impresión, pone cada valor en tu propia línea y los niveles de sangría anidados, generalmente con dos o cuatro espacios. Es cómo quieres JSON cuando lees una respuesta API, revisas un cambio de configuración o depuras.

Minificar elimina todo espacio innecesario y ruptura de línea. Tomando el registro de usuario anterior como un ejemplo trabajado, la versión bastante impresa con sangría en dos espacios es de 153 bytes, mientras que la versión minificada es de 115 bytes. Eso ahorra 38 bytes, alrededor del 25 por ciento, sin ningún cambio en los datos. En un único registro que es trivial, pero para las respuestas de API grandes envió millones de veces la diferencia suma. En la práctica, la compresión HTTP como gzip o Brotli también elimina gran parte del espacio en blanco repetitivo, por lo que la minificación de los asuntos más para archivos almacenados, datos integrados y situaciones en las que no se aplica la compresión.

Una buena regla es mantener JSON formateado en el control de la fuente, donde la gente necesita leer diffs, y minimizarlo cuando se envía a través de la red o incrustado en una página.

Convertir CSV en JSON

Hojas de cálculo y bases de datos suelen exportar CSV, una tabla de texto plano donde cada línea es una fila y los valores están separados por comas, semicolons o tabuladores. Convertir CSV a JSON generalmente significa tratar la primera fila como encabezados y convertir cada fila siguiente en un objeto cuyos nombres de propiedad son esos encabezados. Un archivo de tres columnas con encabezados id, nombre y ciudad se convierte en una variedad de objetos, cada uno con id, nombre y propiedades de la ciudad.

Varios detalles merecen atención. Los valores que contienen el delimitador deben estar envueltos en comillas dobles, y una cita doble literal dentro de un valor cotizado se escribe como dos comillas dobles. Cada fila debe tener el mismo número de celdas que la fila de cabecera. Los nombres de cabecera deben ser únicos, ya que los duplicados se sobrescribían entre sí en los objetos resultantes. Por último, CSV no tiene tipos de datos, por lo que cada valor comienza la vida como texto. Si necesita números o booleanos en el JSON, convierte esos campos deliberadamente después de importarlos en lugar de suponer que fueron detectados, y mantén identificadores como códigos ZIP como cadenas para que los ceros líderes sobrevivan.

Generando tipos TypeScript de JSON

Cuando el código consume JSON de una API, las interfaces de TypeScript describen qué forma deben tener los datos, de modo que los editores pueden autocompletar nombres de propiedades y el compilador puede detectar errores como campos mal escritos. Escribir esas interfaces a mano para una respuesta grande es tedioso y propenso a errores.

Generarlos de una muestra real es más rápido. Cada objeto JSON se convierte en una interfaz, los objetos anidados se convierten en tus propias interfaces nombradas, los arrays se convierten en arrays mecanografiados, y los valores primitivos mapean a cadena, número y booleano. Para el registro de usuario, el resultado es una interfaz con id como número, nombre y correo electrónico como cadenas, activa como booleano y roles como una matriz de cadenas.

Recuerda que una muestra sólo muestra lo que estaba presente en esa respuesta. Un campo que resultó ser nulo, o que falta por completo, le dice al generador poco sobre su tipo real, por lo que revisa la salida contra la documentación de la API y ajustar los campos opcionales y sindicatos cuando sea necesario.

Base64 dentro de las API de JSON

JSON es un formato de texto y no puede contener datos binarios brutos como imágenes, PDFs o claves criptográficas. La solución habitual es Base64, que representa cualquier secuencia de bytes usando 64 caracteres de texto seguros. Cada 3 bytes de entrada se convierten en 4 caracteres de salida, por lo que Base64 añade alrededor de 33 por ciento de gastos generales. Por ejemplo, el texto de 3 bytes Hi! codifica a SGkh, y un archivo de 300.000 bytes se convierte en una cadena de 400.000 caracteres.

Verá Base64 en muchos lugares alrededor de JSON: cargas de archivos incrustadas en un cuerpo de peticiones, URLs de datos para imágenes pequeñas, encabezado de autenticación HTTP Basic y JSON Web Tokens, cuyas secciones son JSON codificado por Base64url. Base64url es una variante que reemplaza plus y barra con guión y subrayado y a menudo deja caer el trailing es igual a relleno, por lo que el resultado es seguro en URLs y nombres de archivos. Ten en cuenta que Base64 es una codificación, no un cifrado. Cualquiera puede decodificarlo, así que nunca trates una cadena Base64 como una manera de ocultar secretos. Para archivos grandes, subir el binario por separado suele ser más eficiente que inflar una carga útil JSON por un tercio.

Trabajar con JSON en herramientas ToolWorld

El ToolWorld JSON Formatter / Validator pretty-prints JSON con sangría de dos o cuatro espacios, lo minimiza, y muestra el mensaje de error del analizador cuando la entrada no es válida, lo que hace que las comas que siguen y las citas perdidas se encuentren rápidamente. Puede pegar texto o abrir un archivo JSON y luego copiar o descargar el resultado.

El convertidor CSV a JSON acepta CSV pegado o un archivo subido, detecta el delimitador automáticamente o le permite elegir uno, utiliza la primera fila como encabezados, maneja campos citados e informa de errores claros para encabezados vacíos o duplicados y filas con el número incorrecto de celdas. Los valores se presentan como cadenas, coincidiendo con la fuente CSV.

La herramienta JSON to TypeScript convierte un ejemplo en interfaces exportadas con un nombre de raíz que usted elige, crea interfaces separadas para objetos anidados, marca campos anulables como opcionales y le permite copiar o descargar un archivo.ts. Para datos binarios, el codificador / decodificador Base64 convierte texto o archivos desde y hacia Base64, con una opción segura de URL para Base64url. Los cuatro se ejecutan en tu navegador, por lo que los datos que pegues en estancias en tu dispositivo mientras trabaja.