Dominando los archivos JSONL: estructura, casos de uso y ventajas clave

Un archivo JSONL contiene un valor JSON completo por línea. La documentación oficial lo llama "el formato de texto JSON Lines, también conocido como JSON delimitado por nuevas líneas". Esa única regla es la razón por la que se transmite tan bien mediante streaming, por la que sobrevive a lecturas parciales y por la que una hoja de cálculo no lo abrirá.

¿Qué es un archivo JSONL?

JSON Lines es un formato de texto para registros. La especificación lo describe como "un formato conveniente para almacenar datos estructurados que pueden procesarse un registro a la vez".

La documentación es explícita sobre dónde encaja. "Funciona bien con herramientas de procesamiento de texto al estilo Unix y tuberías de shell", y la página añade que "es un formato excelente para archivos de registro". También se describe como "un formato flexible para pasar mensajes entre procesos cooperativos".

El contraste con el JSON simple es el punto clave. Un array JSON de un millón de registros es un solo valor: un lector tiene que consumir todo el contenido antes de que la estructura esté completa. Un archivo JSONL de un millón de registros son un millón de valores, y cada línea es independiente.

Existe una segunda especificación estrechamente relacionada. La especificación de NDJSON es directa al respecto: "actualmente no existe un estándar para transportar instancias de texto JSON dentro de un protocolo de transmisión". Su caso de uso declarado es "entregar múltiples instancias de texto JSON a través de protocolos de transmisión como TCP o tuberías de UNIX".

Cómo se estructura un archivo JSONL

Los tres requisitos

La documentación de JSON Lines enumera exactamente tres. El primero es la codificación UTF-8. Lleva una advertencia tomada del propio JSON: "al igual que el estándar JSON, NO se debe incluir una marca de orden de bytes (U+FEFF)".

El segundo es que cada línea sea un valor JSON válido. La página señala que "los valores más comunes serán objetos o arrays, pero se permite cualquier valor JSON". Luego presenta el caso extremo que suele confundir a la gente: "null es un valor válido, pero una línea en blanco no lo es".

El tercero es que el terminador de línea sea \n. Los finales de línea de Windows siguen funcionando. La razón que se da es mecánica: "esto significa que también se admite \r\n porque el espacio en blanco circundante se ignora implícitamente al analizar los valores JSON".

Qué no debe aparecer dentro de una línea

Esta es la restricción que hace que el formato funcione. La especificación de NDJSON lo establece como un requisito: "los textos JSON NO DEBEN contener nuevas líneas ni retornos de carro".

Normalmente se permite que un valor JSON ocupe muchas líneas con sangría. En un archivo delimitado por líneas esto no es posible, porque la nueva línea es el separador de registros. Cada registro tiene que escribirse en una sola línea física.

La línea final y las líneas vacías

Dos detalles difieren entre las dos especificaciones, y ambos importan cuando se rechaza un archivo.

Tomemos la nueva línea final. JSON Lines dice que "se recomienda encarecidamente incluir un terminador de línea después del último valor JSON en un archivo, pero no es obligatorio".

En cuanto a las líneas en blanco, las dos especificaciones no están de acuerdo. JSON Lines es estricto: una línea en blanco no es un valor válido. NDJSON es permisivo, admitiendo que "el analizador PUEDE ignorar silenciosamente las líneas vacías", mientras que exige que "este comportamiento DEBE estar documentado".

Extensiones y tipos de medio

La nomenclatura también se divide. JSON Lines dice que los archivos "pueden guardarse con la extensión de archivo .jsonl". Sobre el tipo de medio, dice que el "tipo MIME puede ser application/jsonl, pero esto aún no está estandarizado". NDJSON dice que el tipo de medio "DEBERÍA ser application/x-ndjson" y la extensión "DEBERÍA ser .ndjson."

Para la compresión, JSON Lines recomienda compresores de flujo: "se recomiendan gzip o bzip2 para ahorrar espacio, lo que da como resultado archivos .jsonl.gz o .jsonl.bz2".

Vale la pena conocer una pequeña convención cuando se lee un mensaje de error. Los editores de texto llaman a la primera línea "línea 1". La documentación amplía eso: "el primer valor en un archivo JSON Lines también debería llamarse 'valor 1'".

Para qué se utiliza JSONL

Normalmente se encontrará con un archivo .jsonl en una de estas cuatro situaciones.

Archivos de registro y eventos. La propia documentación del formato menciona los archivos de registro, y la razón es que un escritor puede añadir una línea a la vez sin tener que reescribir nada.

Cargas en almacenes de datos. La documentación de BigQuery de Google es un buen ejemplo del estatus oficial del formato. Admite la carga de "datos JSON delimitados por nuevas líneas (ndJSON) desde Cloud Storage", y su selector de formato de archivo muestra la opción como "JSONL (JSON delimitado por nuevas líneas)".

Exportaciones de API de registros anidados. Los datos que no se aplanan limpiamente en columnas mantienen su anidamiento por línea. Las líneas de pedido con un número variable de artículos son el caso clásico.

Conjuntos de datos de aprendizaje automático. Los conjuntos de entrenamiento y evaluación se distribuyen comúnmente de esta manera, porque un bucle de entrenamiento lee los registros uno a la vez.

El hilo conductor es la transmisión o streaming. Se convierte en la opción obvia cuando el archivo se produce o se consume de forma incremental.

JSONL frente a JSON frente a CSV

	JSONL	JSON	CSV
Unidad del archivo	Un valor por línea	Un valor para todo el archivo	Una fila por línea
Datos anidados	Sí, por registro	Sí	No de forma nativa
Añadir un registro	Añadir una línea	Reescribir el contenedor	Añadir una fila
La lectura parcial es útil	Sí	Raras veces	Sí
Se abre en una hoja de cálculo	No	No	Normalmente
Los registros pueden diferir en su estructura	Sí	Sí	No, las columnas son fijas
Legible por humanos en un editor	Sí, una línea larga cada uno	Sí, cuando tiene sangría	Sí

La fila que causa más sorpresa es la penúltima. Dos líneas en el mismo archivo JSONL pueden contener claves diferentes. Eso es exactamente lo que hace que el formato sea flexible, y exactamente lo que hace que una importación ingenua produzca columnas desiguales.

Para la alternativa binaria orientada a columnas, la explicación de Parquet cubre el mismo territorio desde el lado del almacenamiento. Para el caso tabular más simple, el análisis de TSV cubre el texto separado por tabuladores.

Ventajas clave

Escritura de solo adición. Un nuevo registro es una nueva línea. No es necesario cambiar nada de lo anterior en el archivo.

Lecturas en streaming. Un consumidor puede procesar el registro uno antes de que se haya escrito el registro dos millones.

Tolerancia a fallos. Un archivo truncado sigue siendo legible hasta la última línea completa. Un array JSON truncado suele ser completamente ilegible.

El anidamiento sobrevive. La estructura que un CSV tendría que aplanar permanece intacta dentro de cada registro.

Compatible con la shell. La documentación da crédito al procesamiento de texto al estilo Unix y a las tuberías de shell, porque un archivo orientado a líneas funciona con herramientas orientadas a líneas.

Soporte de almacenes de datos. La documentación de BigQuery establece la regla que impone: "cada objeto JSON debe estar en una línea separada en el archivo".

Dónde deja de ayudar JSONL

El formato resuelve el transporte y la adición. No resuelve ninguna de las preguntas que pueda tener sobre el contenido.

La compresión es un verdadero compromiso en lugar de una ventaja gratuita. La documentación de BigQuery es contundente sobre el coste: "si utiliza la compresión gzip, BigQuery no puede leer los datos en paralelo". Añade que "cargar datos JSON comprimidos en BigQuery es más lento que cargar datos sin comprimir". La propia página del formato recomienda gzip para ahorrar espacio. Ambas afirmaciones son ciertas y apuntan en direcciones opuestas.

También es redundante. Cada línea repite el nombre de cada clave, por lo que un conjunto de registros amplio es sustancialmente más grande que los mismos datos en un formato de columnas.

Y no dice nada sobre la consistencia. Se permiten registros con diferentes estructuras, lo que significa que un campo puede dejar de aparecer silenciosamente a mitad de un archivo sin que nada sea inválido.

Cómo trabajar con un archivo JSONL si no es ingeniero

Esta es la brecha práctica. Las herramientas empresariales esperan filas y columnas, y un archivo .jsonl no se abrirá de la misma manera que un CSV.

La ruta pragmática es un paso de conversión. Pida a quien haya generado el archivo un extracto aplanado en CSV o Excel de los campos que necesita. O aplánelo usted mismo con cualquier herramienta compatible con JSON. Perderá el anidamiento, lo cual no suele importar una vez que haya decidido qué campos utilizará el análisis.

A partir de ahí, el trabajo es un análisis ordinario. La página de precios de Powerdrill Bloom enumera cargas para Excel, CSV, PDF y documentos, por lo que un extracto aplanado entra directamente. Las preguntas se realizan en lenguaje natural en lugar de escribirse como consultas. El asistente de IA para CSV cubre esa ruta, y los conectores de datos cubren los casos en los que es mejor extraer los datos de su origen en lugar de exportarlos.

La distinción que vale la pena mantener es que esta es una decisión de transporte tomada antes de que le llegue a usted. Convertirlo a otro formato una vez que el archivo llega a su escritorio es algo normal, no una solución temporal.

Conclusión

JSONL es un formato de texto con una sola regla: un valor JSON completo por línea y sin nuevas líneas dentro de un valor. Esa regla aporta capacidad de adición, transmisión en streaming y tolerancia a lecturas parciales, razón por la cual los registros y las cargas de almacenes de datos lo utilizan de forma predeterminada.

Lo que no ofrece es una tabla. En el momento en que el archivo llega a alguien que necesita respuestas en lugar de una tubería de datos, el siguiente paso útil es un extracto aplanado y una pregunta.

Si ahí es donde se encuentra, pruebe Powerdrill Bloom con el archivo convertido y comience por convertirlo en un gráfico.

Preguntas frecuentes

¿Para qué se utiliza un archivo JSONL?

Se utiliza para flujos de registros: archivos de registro, exportaciones de eventos, cargas de almacenes de datos y conjuntos de datos de aprendizaje automático. La documentación del formato menciona específicamente los archivos de registro y las tuberías de shell. El factor común es que los registros se escriben o leen uno a la vez.

¿Cuál es la diferencia entre JSONL y NDJSON?

Describen la misma idea con diferente documentación. JSON Lines utiliza la extensión .jsonl y señala que application/jsonl aún no está estandarizado. NDJSON especifica .ndjson y application/x-ndjson, y permite que los analizadores ignoren las líneas vacías.

¿Puedo abrir un archivo JSONL en Excel?

No haciendo doble clic en él, porque cada línea es un valor JSON en lugar de una fila de celdas. El enfoque habitual es aplanar primero los campos que necesita en CSV o Excel, o utilizar una herramienta que lea el formato directamente.

¿Por qué un registro no puede ocupar varias líneas en JSONL?

Porque el carácter de nueva línea es el separador de registros. La especificación de NDJSON establece que "los textos JSON NO DEBEN contener nuevas líneas ni retornos de carro". Por lo tanto, el JSON formateado para lectura humana (pretty-printed) debe colapsarse en una sola línea por registro.

¿Se permite una línea en blanco en un archivo JSONL?

Las dos especificaciones difieren. JSON Lines establece que "null es un valor válido, pero una línea en blanco no lo es". NDJSON permite que un analizador ignore silenciosamente las líneas vacías, siempre que ese comportamiento esté documentado.