Convertir NDJSON a JSON

Un documento JSON es un único valor. Un archivo NDJSON es una sucesión de valores con saltos de línea entre ellos, y no hay buena voluntad que convierta eso en un documento: el analizador lee el primer objeto, llega a la llave de apertura del segundo y se detiene con un error de símbolo inesperado. No es un fallo del analizador, y es exactamente el motivo de esta página.

La consecuencia aparece en sitios muy corrientes. Un validador de esquema rechaza el archivo. La función que interpreta la respuesta de una petición en el navegador lanza una excepción. Una importación estática falla al compilar. Un cargador de configuración informa de un error de sintaxis en la línea 2 de un archivo cuya línea 2 es JSON impecable. En todos los casos la solución es la misma pizca de estructura: corchetes alrededor de todo y comas entre los registros.

Quien llega aquí rara vez ha creado el `.ndjson` o el `.jsonl`. Se lo ha entregado la exportación de una plataforma, un volcado de registros de actividad, el resultado de una consulta de un proveedor o un compañero que trabaja con una herramienta que escribe así por costumbre. La forma del archivo no fue una decisión suya y la herramienta que tiene delante tampoco.

Por eso conviene mirar el archivo antes de convertirlo, aunque solo sea las tres primeras líneas y la última. Si cada línea es un objeto con las mismas claves, esto va a salir bien. Si la última línea está cortada a mitad, lo vas a saber en la conversión y no cuando el destino se queje, que es una de las cosas que esta ruta hace mejor que un apaño manual.

Cada línea se convierte en un elemento de un array de nivel superior, en el orden del archivo, y eso vale también cuando el origen tiene una sola línea: un archivo de un registro produce un array de un elemento y no el objeto suelto. La salida va sangrada a dos espacios por nivel y termina con un salto de línea.

Poder predecir la forma vale más de lo que parece. Significa que un script que consuma el resultado puede indexar directamente sin comprobar qué le ha llegado, y que la longitud del array es el número de líneas no vacías del origen. Si tu archivo tenía un único objeto y lo que querías era el objeto y no una lista de uno, ese desenvoltorio es un paso aparte que esta conversión no va a hacer por ti.

Muchas interfaces no aceptan un array pelado. Quieren un objeto con los registros bajo un nombre —`registros`, `data`, `items`, lo que diga su documentación— y a menudo con un recuento o un identificador de lote al lado. La conversión produce el array y se detiene ahí, porque inventarse el nombre de una clave sería adivinar un contrato que no puede ver.

Añadirlo después es trivial, y conviene hacerlo con una herramienta y no a mano en un editor, donde una llave que falta al final de un archivo grande es facilísima de provocar y tediosa de encontrar. Comprueba el nombre del campo contra la documentación antes de enviar nada: un lote rechazado suele limitarse a informar de que el cuerpo no era válido, sin decir qué esperaba.

Merece la pena decirlo claro porque los destinos vecinos no se comportan así. Mandar el mismo archivo a CSV, a TSV, a XLSX o a Parquet aplana cada objeto anidado en columnas con el nombre separado por puntos y reconcilia todos los registros contra un único juego de columnas. Aquí no ocurre nada de eso: un registro con un objeto tres niveles adentro llega con ese objeto tres niveles adentro.

Los tipos sobreviven por el mismo motivo. Un número sigue siendo un número, un valor lógico sigue siéndolo, un nulo sigue siendo nulo y una cadena que parece un número sigue entrecomillada. No se infiere nada, porque no hace falta inferir: el origen ya era JSON y el destino es JSON. El orden de las claves dentro de cada registro también se conserva, lo que hace que la salida se pueda comparar contra otra exportación de los mismos datos.

Si alguna línea no se puede interpretar, no se escribe nada. El mensaje identifica la línea por su número, contando desde uno, así que sabes exactamente dónde mirar. No se produce ningún documento parcial y no se salta ningún registro en silencio.

Para este destino esa conducta vale más que para una hoja de cálculo. Una última línea truncada —la causa habitual, por un proceso cortado a media escritura o por un archivo rotado en mitad de un registro— produciría si no un documento que se interpreta bien, valida bien y le faltan un número indeterminado de registros. Borrar o reparar la línea señalada es un momento, y sabes exactamente qué has quitado. Las líneas en blanco no molestan: se descartan, incluida la del final que deja casi cualquier escritor.

La salida va con sangría de dos espacios, de modo que un registro que ocupaba una línea densa en el origen pasa a ocupar una línea por cada valor más las llaves. Un archivo de registros planos con una docena de campos crece por tanto alrededor de una docena de líneas por registro, y el recuento de bytes crece además con la sangría de cada una de ellas.

Nada de eso son datos y todo eso desaparece al comprimir por la red. Si el destino es una persona o una comparación entre versiones, la sangría es justo lo que se quería. Si el destino es un campo de subida con un tope de tamaño, comprime el archivo o plantéate si el sistema receptor necesitaba de verdad un único documento: unos cuantos que lo parecen aceptan las líneas si se les pregunta.

Las dos mitades de esta conversión trabajan sobre el valor completo. Las líneas se interpretan en un array antes de escribir nada, y el array se serializa de una pasada, así que el coste máximo es el origen más la estructura interpretada más la cadena de salida. Nada va en flujo, y nada puede ir: un array no está terminado hasta que llega su último elemento.

El techo gratuito son 100 MB por archivo y el techo práctico es la pestaña. Decenas de megabytes no dan ningún problema; varios cientos de megabytes de registros es donde un navegador empieza a sufrir, y es exactamente el tamaño a partir del cual convertir un flujo en un solo documento deja de ser buena idea. El NDJSON se puede partir sin riesgo por cualquier salto de línea, así que trocearlo antes te da archivos que se convierten sin sobresaltos.

Convertir el resultado en sentido contrario devuelve lo que tenías. Un array de nivel superior se escribe con un elemento por línea, así que los registros, sus claves, el orden de las claves y sus tipos vuelven sin cambios. No hay ningún paso con pérdida en ninguna de las dos direcciones que se pueda acumular.

Eso hace que el par sirva como movimiento de trabajo y no como migración. Conviertes a JSON, pasas el validador o la comprobación de esquema, arreglas lo que se queje en un editor de JSON en condiciones con emparejamiento de llaves, vuelves a convertir, y le das el flujo corregido al cargador que quería líneas desde el principio. El NDJSON sigue siendo el formato de transporte y el JSON es la forma en la que se trabaja.

Si el consumidor acepta entrada delimitada por líneas, dale eso. Un único array obliga al lector a sostenerlo todo a la vez, y convertir para satisfacer una preferencia en lugar de un requisito hace el archivo mayor y la carga más lenta sin ganar nada.

Conserva el original en cualquier caso. El array no tiene ninguna ventaja que las líneas no tengan, salvo ser un único valor; las líneas tienen varias que el array no: se añaden al final sin reescribir el archivo, se filtran sin cargarlo entero y un byte corrompido estropea un registro en vez del documento completo.

La conversión es JavaScript corriente dentro de la página. No se descarga ningún motor, ninguna petición lleva el archivo, no hay cuenta ni cupo diario, y el panel de red durante una conversión es la comprobación en lugar de esta frase.

Aquí eso importa especialmente, porque los archivos que necesitan esta conversión rara vez son públicos. Una exportación de eventos, un registro de auditoría, un extracto de clientes camino de un validador de esquema: todos ellos son justo el material que una organización prohíbe pegar en un servicio web. No hay nada que prohibir cuando no se envía nada.