Convertir YAML a NDJSON

NDJSON es JSON con una regla sobre los saltos de línea: un valor completo por línea, sin comas entre ellos y sin corchetes que lo envuelvan todo. Para producirlo, algo tiene que decidir dónde acaba un registro y empieza el siguiente, y lo único en un archivo YAML que marca esa frontera es una secuencia en el nivel superior del documento. Un archivo que empieza con una lista de guiones se convierte en una línea por cada guion.

Todo lo demás sale como una sola línea. Un mapeo en la raíz es un único valor por muy anidado que esté por dentro, así que un manifiesto de despliegue, un docker-compose o la configuración de una aplicación llegan como una línea de varios kilobytes. No es un fallo, y casi nunca es lo que se buscaba al convertir, por eso va primero en esta página en vez de en una nota al pie.

Si los registros que quieres están anidados bajo una clave —una clave usuarios con una lista dentro, una clave eventos con otra lista— la conversión no va a entrar a buscarlos. Solo mira la raíz del documento. La solución es subir esa lista a la parte superior del archivo antes de convertir, que en un editor de texto es borrar la primera línea y quitar la sangría al resto.

La alternativa es convertir primero a JSON y usar jq para seleccionar y volcar el resultado a la vez: extraer el array y emitirlo elemento por elemento es una única expresión. Esa vía es mejor cuando la extracción se va a repetir muchas veces, porque queda scripteada; este conversor es mejor cuando el trabajo se hace una sola vez.

Un anclaje YAML permite definir un bloque una vez y referenciarlo varias, y el analizador resuelve cada alias en una copia completa antes de escribir nada. El NDJSON resultante pesa más que el YAML de origen, a veces bastante más.

Para un flujo eso no es un coste, es un requisito. Quien lee NDJSON procesa una línea cada vez y puede no haber visto ninguna de las anteriores — es exactamente para eso que existe el formato, y es lo que permite repartir un archivo entre varios procesos o reanudar la carga tras un fallo. Una línea que dependiera de una definición leída antes fallaría justo en las condiciones para las que se diseñó el formato. Reducir la duplicación es tarea de después de la carga, no del propio archivo.

Un flujo YAML con varios documentos separados por --- es, conceptualmente, ya NDJSON: un documento por registro, en orden. Es la coincidencia estructural más cercana de toda esta familia de formatos y es precisamente la entrada que esta conversión rechaza, porque el analizador lee un único documento y se detiene al encontrar el segundo.

La solución pasa por editar el texto, no por el conversor. Sustituye cada --- por una marca de elemento de lista en el nivel superior y sangra los documentos debajo, y el archivo se convierte exactamente en el flujo esperado. En un archivo grande, una pasada con sed lo resuelve; con unos pocos documentos, un editor de texto también sirve.

BigQuery y Snowflake aceptan NDJSON directamente como formato de carga. jq lo lee sin necesidad de ningún parámetro y lo escribe de vuelta con la opción compacta. pandas lo lee con el argumento de líneas. Cualquiera de esos destinos consume esta salida tal cual.

Elasticsearch es la excepción con la que la gente tropieza. Su API bulk tiene forma de NDJSON pero espera una línea de acción antes de cada documento, así que un archivo de registros sencillos se rechaza. Intercalar esas líneas de acción es una pasada de jq o awk aparte, y deliberadamente no se hace aquí, porque esa línea nombra un índice y una operación que solo tú conoces.

Cada línea es JSON compacto: sin sangría, sin espacios tras los dos puntos, con las claves en el mismo orden que tenían en el YAML. El archivo es UTF-8 y termina con un salto de línea, que la mayoría de cargadores exige y algunos toleran sin pedirlo.

Los tipos vienen del analizador de YAML, no del escritor. Bajo YAML 1.2 una fecha sin comillas se queda como cadena de texto, así que un campo de fecha llega como texto en vez de como algo que un cargador reconozca como marca temporal sin una pista de esquema. Los enteros grandes son el riesgo silencioso: un identificador escrito como 9223372036854775807 sale como 9223372036854776000, porque los números JSON son de coma flotante de doble precisión. Ponlos entre comillas en el YAML antes de convertir y llegarán como texto, que es lo que un identificador debería haber sido desde el principio.

Una lista cuyos elementos no comparten las mismas claves se convierte sin problema, y cada línea lleva solo las claves que tenía su registro. Es una ventaja real frente a convertir los mismos datos a CSV, donde las columnas tienen que ser la unión de todos los registros y las celdas ausentes hay que rellenarlas con algo.

Si el destino es igual de flexible es otra cuestión. Un almacén de esquema en lectura acepta líneas irregulares sin problema; un cargador de tabla con esquema fijo rechazará o pondrá a nulo los campos inesperados. La conversión conserva lo que decía el YAML, y merece la pena revisar las primeras y últimas líneas de una salida grande para ver cuánto varía la forma a lo largo del archivo.

Los comentarios del YAML se pierden, y NDJSON no tiene sitio para ellos: es JSON línea a línea, y JSON no tiene sintaxis de comentarios. Tampoco hay línea de cabecera, ni declaración de esquema, ni bloque de metadatos, así que el archivo lleva registros y nada más.

Esa ausencia es deliberada en el formato y conviene respetarla en la propia tubería de datos. Si la carga necesita saber un origen, un identificador de lote o una versión de esquema, eso va en un campo de cada registro o en el nombre del archivo, no en un preámbulo — cualquier cosa al principio de un archivo NDJSON es un registro, y un cargador va a intentar leerlo como tal.

Un caso frecuente en equipos que trabajan con Kubernetes o con herramientas de infraestructura como código es tener un archivo de datos de prueba escrito en YAML —una lista de usuarios ficticios, un catálogo de productos de ejemplo, un conjunto de eventos simulados— pensado para leerse cómodamente y del que en algún momento hace falta sacar un flujo de carga real. El archivo nació para que una persona lo edite con comodidad, y el flujo de salida está pensado para que lo lea una máquina sin parar hasta el final.

Ese cambio de propósito es exactamente lo que resuelve esta conversión: la lista sigue siendo la misma, con las mismas claves y el mismo orden, solo que ahora cada elemento vive en su propia línea, listo para entrar en un índice, en una tabla o en una tubería de procesamiento por lotes sin que nadie tenga que escribir un script de por medio.

El plan gratuito acepta archivos de hasta 100 MB, tanto el análisis como la escritura corren como JavaScript en esta misma página, y no hay ningún servidor de por medio: el YAML no sale de tu equipo en ningún momento. Con un archivo de exportación de registros suele sobrar de largo.

Antes de dar por bueno un archivo grande, abre las primeras diez líneas y las últimas diez. Es la forma más rápida de comprobar que la secuencia detectada era la correcta y de detectar de un vistazo si algún registro se ha quedado con una forma inesperada.

Si el YAML es una configuración y no una lista de datos, esta conversión no aporta nada. Una sola línea de JSON minificado es peor que el YAML en todo lo que le importa a una persona, y ningún consumidor de flujos quería un archivo de configuración. Convierte a JSON si necesitas que sea procesable por máquina, y deja el YAML tal cual si no.

La pareja de formatos merece la pena cuando el archivo es de verdad una lista — registros exportados, datos de prueba, un log de eventos escrito a mano, un conjunto de datos semilla— y el destino lee línea a línea. En ese caso la conversión es instantánea, corre entera en tu navegador, y lo único que queda por revisar es la primera línea y la última.