Por Jerry Fan

Buenas prácticas para trabajar con JSONL

Una guía completa para crear archivos JSONL limpios, fiables y eficientes. Aprende las reglas de formato, cómo diseñar esquemas, cómo gestionar errores y qué técnicas de optimización aplicar a las cargas de trabajo en producción.

Por qué son importantes las buenas prácticas en JSONL

JSONL (JSON Lines) parece muy sencillo: un objeto JSON por línea, con saltos de línea como separadores. Pero esa sencillez no impide que surjan errores. Los esquemas inconsistentes, los problemas de codificación, las comas al final y los saltos de línea dentro de los valores son algunas de las causas más habituales de errores de parseo en los pipelines de datos en producción. Seguir unas buenas prácticas claras permite evitar estos problemas antes de que aparezcan.

Esta guía recoge las reglas esenciales para generar y consumir datos JSONL de forma fiable. Tanto si creas conjuntos de datos para aprendizaje automático como si transmites logs de aplicaciones en streaming o intercambias datos entre servicios, estas prácticas te ayudarán a evitar errores difíciles de detectar y a mejorar el rendimiento de tus flujos de trabajo con JSONL.

Reglas de formato

Para que un archivo JSONL sea válido, debe cumplir estrictamente unas pocas reglas de formato. Si incumples cualquiera de ellas, la mayoría de los parsers rechazarán el archivo.

Cada línea de un archivo JSONL debe contener un valor JSON completo e independiente. Nunca repartas un mismo objeto JSON entre varias líneas. El JSON con sangría y saltos de línea no es JSONL válido. Serializa siempre en formato compacto, sin sangría ni espacios adicionales entre las claves y los valores.

Un objeto JSON por línea
# Valid JSONL - one complete JSON per line
{"id":1,"name":"Alice","tags":["admin","user"]}
{"id":2,"name":"Bob","tags":["user"]}


# INVALID - pretty-printed JSON spans multiple lines
{
  "id": 1,
  "name": "Alice"
}

Los archivos JSONL deben estar codificados en UTF-8. Es la codificación que dan por sentada prácticamente todos los parsers de JSONL, las herramientas de streaming y los servicios en la nube. Evita UTF-16, Latin-1 y otras codificaciones. Si los datos de origen tienen otra codificación, conviértelos a UTF-8 antes de escribirlos en JSONL.

Usa siempre la codificación UTF-8
# Python: always specify UTF-8 when reading/writing
with open('data.jsonl', 'w', encoding='utf-8') as f:
    f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Node.js: UTF-8 is the default for fs
fs.appendFileSync('data.jsonl', JSON.stringify(record) + '\n', 'utf-8');

Usa un único carácter de avance de línea (LF, \n) como separador. Es el estándar en Linux, macOS y la mayoría de los entornos en la nube. Evita la combinación de retorno de carro y avance de línea (CRLF, \r\n) que usa Windows, ya que puede causar problemas de parseo. La mayoría de los editores y herramientas actuales se encargan de esto automáticamente, pero revisa la configuración si trabajas en varias plataformas.

Qué carácter usar como salto de línea
# Correct: LF line endings (\n)
{"id":1}\n{"id":2}\n


# Avoid: CRLF line endings (\r\n)
{"id":1}\r\n{"id":2}\r\n


# Tip: configure Git to normalize line endings
# .gitattributes
*.jsonl text eol=lf

Coherencia del esquema

Aunque JSONL no exige un esquema, mantener una estructura coherente entre los registros facilita mucho el trabajo con los datos. Los esquemas inconsistentes provocan errores en tiempo de ejecución, valores null inesperados y fallos de importación.

Usa los mismos nombres de campo, el mismo orden y los mismos tipos de datos en todos los registros. Aunque JSON no exige un orden concreto para los campos, mantenerlo mejora la legibilidad y facilita la compresión. Nunca mezcles tipos en un mismo campo: por ejemplo, el campo "price" no debería ser una cadena en algunos registros y un número en otros.

Mantén el orden y los tipos de los campos
# Good: consistent field order and types
{"id":1,"name":"Alice","age":30,"active":true}
{"id":2,"name":"Bob","age":25,"active":false}
{"id":3,"name":"Charlie","age":35,"active":true}


# Bad: inconsistent order, mixed types, missing fields
{"name":"Alice","id":1,"active":true}
{"id":"2","age":25,"name":"Bob"}
{"id":3,"active":"yes","name":"Charlie"}

Cuando un campo no tenga valor, inclúyelo con el valor null de JSON en vez de omitir la clave. Así simplificas el procesamiento posterior, porque todos los registros contienen el mismo conjunto de claves. Los sistemas que consumen los datos no tienen que distinguir entre «el campo no existe» y «el campo es null».

Indica explícitamente los valores ausentes
# Good: include all fields, use null for missing values
{"id":1,"name":"Alice","email":"[email protected]","phone":null}
{"id":2,"name":"Bob","email":null,"phone":"+1-555-0100"}


# Avoid: omitting keys for missing data
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","phone":"+1-555-0100"}

Gestión de errores

En la práctica, los archivos JSONL suelen contener algunas líneas no válidas debido a problemas de codificación, escrituras truncadas o errores en los sistemas de origen. Un sistema robusto debe poder gestionar estos casos sin detenerse al encontrar la primera línea incorrecta.

Coloca la operación de parseo de cada línea dentro de un bloque try-catch y, si falla, registra el número de línea y el mensaje de error. Esto te permite omitir las líneas no válidas y conservar un registro de lo ocurrido. En los pipelines críticos, guarda las líneas erróneas en un archivo aparte para revisarlas después.

Parseo tolerante a errores con registro de líneas
import json


def parse_jsonl_safe(path: str):
    """Parse JSONL with error tolerance."""
    valid, errors = [], []
    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                valid.append(json.loads(line))
            except json.JSONDecodeError as e:
                errors.append({'line': line_num, 'error': str(e), 'raw': line})
    print(f'Parsed {len(valid)} records, {len(errors)} errors')
    return valid, errors

En los pipelines de datos, añade un paso de validación antes de la lógica principal de procesamiento. Comprueba que cada registro contenga los campos y tipos esperados. Rechaza o pon en cuarentena los registros que no cumplan estos requisitos. Así evitarás que los errores de tipo aparezcan en etapas avanzadas del pipeline, donde resulta más difícil depurarlos.

Valida antes de procesar
def validate_record(record: dict) -> list[str]:
    """Validate a JSONL record against expected schema."""
    issues = []
    required = ['id', 'name', 'timestamp']
    for field in required:
        if field not in record:
            issues.append(f'Missing required field: {field}')
    if 'id' in record and not isinstance(record['id'], int):
        issues.append(f'Field "id" should be int, got {type(record["id"]).__name__}')
    return issues


# Usage in pipeline
for record in parse_jsonl_safe('data.jsonl')[0]:
    issues = validate_record(record)
    if issues:
        log_warning(f'Record {record.get("id")}: {issues}')
    else:
        process(record)

Optimización del rendimiento

En los flujos de trabajo de ingeniería de datos y aprendizaje automático, los archivos JSONL pueden alcanzar varios gigabytes. Una estrategia de procesamiento adecuada permite limitar el consumo de memoria y mantener una alta capacidad de procesamiento.

Nunca cargues un archivo JSONL entero en memoria. Lee y procesa una línea o un lote de líneas cada vez. Así el consumo de memoria se mantiene constante, independientemente del tamaño del archivo. En Python, la iteración sobre archivos ya se realiza línea a línea; Node.js ofrece las APIs readline y stream para el mismo fin.

Procesamiento en streaming
# Python: stream with constant memory
import json


count = 0
with open('large.jsonl', 'r', encoding='utf-8') as f:
    for line in f:  # One line at a time, not f.readlines()!
        record = json.loads(line)
        process(record)
        count += 1
print(f'Processed {count} records')

Al escribir en una base de datos o hacer llamadas a APIs, agrupa varios registros en lotes en lugar de procesarlos uno a uno. El procesamiento por lotes reduce la sobrecarga de E/S y puede multiplicar el rendimiento entre 10 y 100 veces. Los lotes de entre 1,000 y 10,000 registros funcionan bien en la mayoría de los casos.

Operaciones por lotes
import json


def process_in_batches(path: str, batch_size: int = 5000):
    """Process JSONL records in batches for better throughput."""
    batch = []
    with open(path, 'r', encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            batch.append(json.loads(line))
            if len(batch) >= batch_size:
                bulk_insert(batch)  # Send batch to database
                batch.clear()
    if batch:
        bulk_insert(batch)  # Flush remaining records

JSONL se comprime muy bien porque las líneas consecutivas suelen compartir las mismas claves y tener valores similares. Usa gzip al almacenar y transferir archivos para reducir su tamaño entre 5 y 10 veces. La mayoría de los lenguajes permiten leer directamente archivos JSONL comprimidos con gzip, sin tener que descomprimirlos antes en disco.

Comprime los archivos para almacenarlos y transferirlos
import gzip
import json


# Write compressed JSONL
with gzip.open('data.jsonl.gz', 'wt', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Read compressed JSONL
with gzip.open('data.jsonl.gz', 'rt', encoding='utf-8') as f:
    for line in f:
        record = json.loads(line)
        process(record)

Errores habituales que conviene evitar

Estos son los problemas que encontramos con más frecuencia cuando los usuarios validan archivos JSONL con nuestras herramientas. Todos provocan errores de parseo que pueden ser difíciles de diagnosticar si no se abordan de la manera adecuada.

JSON no admite una coma después del último elemento de un objeto o array. Es uno de los errores más habituales, sobre todo entre quienes vienen de JavaScript, donde sí se permiten estas comas. Elimina siempre las comas finales de los datos de salida.

Comas al final
# INVALID: trailing comma after last property
{"id": 1, "name": "Alice",}


# VALID: no trailing comma
{"id": 1, "name": "Alice"}


# INVALID: trailing comma in array
{"tags": ["admin", "user",]}


# VALID: no trailing comma in array
{"tags": ["admin", "user"]}

Si una cadena contiene un carácter de salto de línea literal, incumplirá la regla de una línea por registro y dañará el archivo JSONL. Dentro de las cadenas JSON, usa siempre la secuencia de escape \n, nunca un salto de línea literal. La mayoría de los serializadores JSON se encargan de esto automáticamente, pero ten cuidado si construyes las cadenas JSON a mano.

Saltos de línea dentro de las cadenas
# INVALID: raw newline inside a string value breaks JSONL
{"id": 1, "bio": "Line one
Line two"}


# VALID: escaped newline keeps everything on one line
{"id": 1, "bio": "Line one\nLine two"}


# Tip: json.dumps() in Python handles this automatically
import json
record = {"bio": "Line one\nLine two"}
print(json.dumps(record))
# Output: {"bio": "Line one\nLine two"}

Mezclar UTF-8 y Latin-1, u otras codificaciones, en un mismo archivo produce caracteres ilegibles y errores de parseo. Suele ocurrir al añadir datos de distintas fuentes. Convierte siempre los datos a UTF-8 antes de escribirlos. Si recibes datos con una codificación desconocida, detéctala con una biblioteca como chardet antes de convertirlos.

Codificaciones mezcladas o incorrectas
# Python: detect and convert encoding
import chardet


def normalize_to_utf8(input_path: str, output_path: str):
    """Detect encoding and convert to UTF-8."""
    with open(input_path, 'rb') as f:
        raw = f.read()
    detected = chardet.detect(raw)
    encoding = detected['encoding'] or 'utf-8'
    print(f'Detected encoding: {encoding}')
    text = raw.decode(encoding)
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(text)

Nombres y organización de archivos

Una buena convención de nombres y una estructura de directorios bien organizada facilitan la localización, la gestión y el procesamiento de los datos JSONL en pipelines automatizados.

Usa .jsonl como extensión predeterminada. Es la más reconocida para los archivos JSON Lines y la que esperan herramientas como la API de fine-tuning de OpenAI, BigQuery y la mayoría de las plataformas de datos. La extensión .ndjson (Newline Delimited JSON) corresponde, técnicamente, al mismo formato con otro nombre. Elige una convención y aplícala en todo el proyecto.

Extensiones .jsonl y .ndjson
# Recommended file naming conventions
data.jsonl              # Standard JSONL file
users_2026-02-14.jsonl  # Date-stamped export
train.jsonl             # ML training data
validation.jsonl        # ML validation split
events.jsonl.gz         # Compressed JSONL

Organiza los archivos JSONL según su finalidad y fecha. Separa los datos de entrada sin procesar de los datos de salida ya procesados. Para las series temporales o los logs, usa particiones por fecha: así podrás procesar intervalos concretos y eliminar datos antiguos con facilidad.

Estructura de directorios para proyectos con JSONL
project/
  data/
    raw/                  # Original unprocessed files
      events_2026-02-13.jsonl
      events_2026-02-14.jsonl
    processed/            # Cleaned and transformed
      events_clean.jsonl
    schemas/              # Schema documentation
      event_schema.json
  scripts/
    validate.py           # Validation script
    transform.py          # Transformation pipeline

Comprueba tus archivos JSONL ahora

Valida y formatea archivos JSONL de hasta 1GB directamente en tu navegador. Detecta al instante errores de formato y problemas de esquema o codificación.

Preguntas frecuentes

Referencias