¿Qué es NDJSON? Registros de transmisión, sintaxis y casos de uso

La API de scraping sin scrap devuelve JSON estructurado que una tubería a monte puede enmarcar como NDJSON cuando se requieren registros independientes para transmisión o almacenamiento orientado a líneas.

¿Qué es NDJSON?

NDJSON es un formato de texto para una secuencia de valores JSON separados por caracteres de nueva línea. Cada línea física contiene un texto JSON completo. Un consumidor lee una línea, analiza esa línea como JSON, procesa el valor resultante y pasa al siguiente registro.

El especificación NDJSON requiere que cada texto JSON se ajuste a las reglas de JSON y sea seguido por una nueva línea. Especifica UTF-8, acepta LF y CRLF como delimitadores de línea para el análisis, y recomienda application/x-ndjson con la .ndjson extensión.

NDJSON es una convención de enmarcado en torno a JSON, no un nuevo modelo de objeto. Una línea puede contener técnicamente cualquier valor JSON, aunque el patrón dominante para registros, ingestión a granel, exportaciones y tuberías de datos es uno por línea. La gramática JSON sigue siendo la definida por RFC 8259.

¿Cómo se ve un archivo NDJSON?

Un flujo de observación de productos podría contener tres registros independientes:

{"sku":"A-17","price":34.5,"currency":"USD"}
{"sku":"B-08","price":28,"currency":"USD"}
{"sku":"C-31","price":null,"currency":"EUR"}

No hay un corchete de apertura de arreglo, coma entre registros o corchete de cierre. Cada línea puede ser analizada por sí sola. La última línea debe terminar con una nueva línea bajo la regla de serialización NDJSON, aunque los visores de texto no siempre hacen visible el delimitador final.

JSON bien formateado no funciona como un registro NDJSON porque la indentación escribe un valor a través de varias líneas físicas. Los productores deben serializar cada valor en forma compacta. Una cadena que contiene un salto de línea lógico sigue siendo válida porque JSON lo escapa:

{"id":41,"message":"first line\nsecond line"}

Los dos caracteres de barra invertida y n permanecen dentro de la cadena JSON en una línea física. Un analizador JSON reconstruye el carácter de salto de línea después de que el enmarcado de registro ya ha tenido éxito.

NDJSON vs un arreglo JSON

Por qué NDJSON funciona para streaming

El JSON estándar no define un límite entre dos valores top-level adyacentes. Escribir {}{} deja un analizador sin un separador estándar. NDJSON asigna ese rol a la nueva línea. El lector no necesita buscar llaves equilibradas porque las llaves dentro de las cadenas JSON son caracteres de cadena ordinarios y el límite físico de la línea termina el registro.

Un productor puede vaciar cada línea cuando el registro está listo. Un consumidor puede aplicar contra presión a través de su interfaz de stream, analizar una línea, validar el valor y liberar memoria después del procesamiento. Esto mantiene el uso de memoria vinculado al registro más grande y a los buffers de la tubería en lugar de al conjunto de datos completo.

NDJSON no es el único formato de secuencia JSON. RFC 7464 define secuencias de texto JSON usando un carácter separador de registro ASCII antes de cada texto JSON. Ese marco puede tolerar valores impresos en bonito porque los límites de registro no dependen únicamente de los finales de línea. Los productores y consumidores deben acordar qué formato de secuencia utilizan.

Diseño de Registro NDJSON

Un stream NDJSON sólido proporciona a cada línea suficiente contexto para ser procesada de forma independiente. Incluya un tipo de registro estable o versión de esquema cuando varias formas de evento compartan un stream. Incluya un identificador que soporte desduplicación cuando el transporte pueda entregar el mismo registro lógico más de una vez. Agregue tiempos de evento y observación solo con formatos documentados y semántica de zona horaria.

Mantenga el contenido binario grande fuera del JSON orientado a líneas a menos que el contrato exija explícitamente bytes codificados. Base64 aumenta el tamaño y crea registros muy largos. Un mejor evento puede llevar una referencia de objeto controlada más metadatos de integridad, sujeto a autorización en el momento de recuperación.

El orden debe ser explícito. NDJSON preserva el orden físico de las líneas, pero productores distribuidos, particiones y consumidores paralelos pueden cambiar el orden de procesamiento observado. Si el orden importa dentro de una entidad, incluya una secuencia o versión y defina cómo se manejan los registros con huecos y fuera de orden.

Validación de Esquema

JSON válido no es necesariamente un registro comercial válido. Una línea puede analizarse con éxito mientras falta un identificador requerido o almacena un número donde el contrato espera una cadena. Valide cada valor analizado contra un esquema de registro antes de usarlo.

Streams con múltiples tipos de registro pueden elegir un esquema basado en un discriminador estable. El despachador debe rechazar tipos desconocidos o enviarlos a un camino de cuarentena controlada. Las versiones de esquema deben definir compatibilidad para que los consumidores puedan continuar cuando se agregan campos opcionales.

La validación a nivel de registro permite que un lote informe fallas específicas sin perder la ubicación de registros aceptables. Almacene el número de línea física, el desplazamiento en bytes cuando esté disponible, el error de esquema y un identificador de registro redactado de manera segura. No copie secretos o cargas sensibles en los registros de errores.

Casos de Uso Comunes de NDJSON

NDJSON, CSV y Parquet

NDJSON preserva estructuras JSON anidadas y permite registros con campos opcionales. CSV es más compacto y accesible cuando cada registro es una fila de tabla plana. Parquet agrega almacenamiento columnar tipado para análisis repetidos en muchos registros.

Un canal común recolecta o recibe JSON, escribe NDJSON en bruto para trazabilidad amigable con adiciones, valida y normaliza registros, luego publica Parquet para consultas analíticas. CSV sigue siendo útil para exportaciones planas seleccionadas a usuarios de hojas de cálculo. Cada etapa tiene un consumidor diferente y, por lo tanto, un formato óptimo diferente.

Compresión y División

Los registros de texto a menudo se comprimen bien porque las claves y patrones de valor se repiten. La compresión de archivo completo reduce el tamaño de almacenamiento y transferencia, pero algunos códecs dificultan el comienzo de lectura desde el medio de un stream comprimido. La compresión divisoria o bloques comprimidos de forma independiente pueden ser mejores para el procesamiento paralelo.

Divídase solo en límites de registro completos. Un corte de rango de bytes a través del medio de una cadena JSON crea fragmentos no válidos. Los sistemas que necesitan acceso paralelo pueden mantener índices de bloque, dividir el stream en varios objetos, o usar formatos de almacenamiento creados para lecturas selectivas.

La concatenación de archivos NDJSON válidos generalmente preserva el enmarcado de línea válido cuando cada entrada termina con una nueva línea. Si un archivo carece del delimitador final, su último registro puede correr hacia el primer registro del siguiente archivo. Los escritores deben terminar siempre los registros serializados, incluido el último.

Seguridad y Límites Operacionales

Aplique límites a bytes totales, longitud de línea, profundidad de anidamiento, longitud de cadena, magnitud numérica y cantidad de propiedades permitidas. Una sola línea NDJSON puede ser arbitrariamente grande a menos que la aplicación imponga un límite. Lea con un búfer limitado o una estrategia de streaming que informe un registro sobredimensionado sin agotar la memoria.

No ejecute campos como comandos o plantillas. Escape valores cuando ingresen a contextos HTML, SQL, shell o de registro. Proteja contra la forja de registros cuando los registros NDJSON se convierten más tarde en texto plano. Mantenga la autorización a nivel de stream y registro cuando un archivo pueda contener datos para varios inquilinos.

Cómo procesar NDJSON de manera confiable

1. Abre la transmisión como UTF-8. Define cómo se informan las secuencias de bytes inválidas; la sustitución silenciosa puede cambiar identificadores.
2. Lee una línea física con límite. Acepta los finales de línea acordados y aplica un tamaño máximo de registro.
3. Maneja líneas vacías por contrato. Decide si se ignoran o se rechazan, y aplica la regla de manera consistente.
4. Analiza un valor JSON. Rechaza el contenido no blanco al final de esa línea y define el comportamiento de miembros duplicados.
5. Valida el esquema del registro. Verifica el tipo, las propiedades requeridas, los límites de valor y las versiones soportadas.
6. Procesa de manera idempotente cuando sea posible. Los identificadores de registro estables ayudan a prevenir efectos colaterales duplicados cuando un registro aparece más de una vez.
7. Registra el progreso de forma segura. Los puntos de control deben identificar un registro durable o un límite de bytes sin reclamar que se procesó una línea incompleta.

Cuándo no usar NDJSON

Usa un documento JSON normal cuando el payload es pequeño, debe llevar metadatos de nivel superior, o se beneficia de la impresión bonita. Usa CSV cuando los datos son una tabla plana para consumidores de hojas de cálculo. Usa Parquet cuando los motores analíticos necesitan poda de columnas, almacenamiento tipado y compresión en grandes conjuntos de datos.

NDJSON también es una mala opción cuando los valores individuales deben contener formato de línea física no escapado para la edición humana. Una secuencia JSON basada en separadores de registro o un protocolo binario enmarcado pueden coincidir mejor con ese requerimiento.

Conclusión

NDJSON añade una regla práctica al intercambio de JSON: cada línea es un valor JSON completo. Esa regla soporta archivos amigables para el apendimiento, analizadores de transmisión, validación a nivel de registro y memoria limitada. No define el esquema comercial, garantías de orden, política de seguridad o semántica de entrega. Un flujo de trabajo NDJSON confiable usa registros compactos en UTF-8, esquemas explícitos, límites de tamaño, identificadores estables, comportamiento claro de líneas vacías y puntos de control conscientes de las líneas.