JSONL (JSON Lines) Format Guide

Specification

JSONL (JSON Lines), también conocido como JSON delimitado por líneas nuevas (NDJSON), es un formato de datos basado en texto donde cada línea es un objeto JSON válido separado por un carácter de nueva línea. A diferencia del JSON estándar, que envuelve todos los datos en un solo arreglo u objeto, JSONL almacena un registro por línea, lo que lo hace ideal para streaming, adición y procesamiento de grandes datasets sin cargar el archivo completo en memoria. El formato está definido informalmente por la especificación jsonlines.org y se ha convertido en el estándar de facto para datasets de fine-tuning de LLM.

Cada línea en un archivo JSONL debe ser un objeto JSON válido y autónomo. Las líneas están separadas por el carácter de nueva línea (\n), y se permiten líneas nuevas al final. No hay línea de encabezado, no hay corchetes envolventes y no hay comas entre registros. Esta simplicidad hace que JSONL sea extremadamente fácil de parsear, generar y manipular con herramientas estándar de Unix — puedes filtrar filas con grep, contar registros con wc -l, muestrear con shuf y concatenar archivos con cat.

La naturaleza amigable con streaming del formato lo hace particularmente adecuado para pipelines de machine learning que procesan datos de forma incremental. Frameworks de entrenamiento como Hugging Face Transformers, la API de fine-tuning de OpenAI, Axolotl y LLaMA-Factory aceptan JSONL como su formato de entrada principal. Herramientas de procesamiento de datos incluyendo pandas, Polars, DuckDB y Apache Spark proporcionan soporte nativo de JSONL, permitiendo una integración fluida entre las etapas de preparación de datos y entrenamiento de modelos.

When to Use JSONL (JSON Lines)

JSONL es el formato recomendado siempre que estés preparando datos de entrenamiento basados en texto para fine-tuning de modelos de lenguaje grandes. Es el formato de entrada esperado para fine-tuning de OpenAI, datasets de Hugging Face y la mayoría de los frameworks de entrenamiento open-source. Si tus datos de entrenamiento consisten en pares de instrucción-respuesta, intercambios conversacionales, ejemplos de clasificación de texto o cualquier otro dato de texto estructurado, JSONL debería ser tu opción predeterminada.

Elige JSONL sobre CSV cuando tus datos contengan estructuras anidadas, campos de longitud variable o caracteres especiales que requerirían escapado complejo en formato CSV. JSONL maneja naturalmente arreglos, objetos anidados y texto Unicode sin los problemas de delimitadores y entrecomillado que afectan a los archivos CSV. Elige JSONL sobre Parquet cuando necesites datos legibles por humanos que puedan inspeccionarse y editarse con un editor de texto, o cuando tu dataset sea lo suficientemente pequeño como para que las ventajas de compresión de Parquet no sean significativas.

JSONL es menos adecuado para datasets numéricos muy grandes donde los formatos columnares como Parquet proporcionan compresión y rendimiento de consultas dramáticamente mejores. También es menos eficiente que los formatos binarios para datasets que se leen muchas veces pero rara vez se modifican, ya que cada lectura requiere parsear texto JSON. Para datasets que exceden decenas de gigabytes, considera convertir a Parquet para almacenamiento y convertir de vuelta a JSONL para el paso final de entrenamiento.

Schema / Structure

// OpenAI-compatible fine-tuning format
interface ChatCompletionMessage {
  role: "system" | "user" | "assistant";
  content: string;
}

interface FineTuningExample {
  messages: ChatCompletionMessage[];
}

// Instruction-following format (Alpaca-style)
interface InstructionExample {
  instruction: string;
  input?: string;
  output: string;
}

// Text classification format
interface ClassificationExample {
  text: string;
  label: string;
}

Example Data

{"messages": [{"role": "system", "content": "You are a helpful coding assistant."}, {"role": "user", "content": "Write a Python function to reverse a string."}, {"role": "assistant", "content": "def reverse_string(s: str) -> str:\n    return s[::-1]"}]}
{"messages": [{"role": "system", "content": "You are a helpful coding assistant."}, {"role": "user", "content": "How do I read a CSV file in Python?"}, {"role": "assistant", "content": "import pandas as pd\ndf = pd.read_csv('data.csv')\nprint(df.head())"}]}
{"messages": [{"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "The capital of France is Paris."}]}