Validación de esquemas en JSONL: garantiza la calidad de los datos
Una guía completa para validar archivos JSONL con JSON Schema. Aprende a definir esquemas, validar registros en Python y Node.js, automatizar las comprobaciones en pipelines de CI/CD y diagnosticar los errores de validación más comunes.
Por qué los archivos JSONL necesitan validación de esquemas
Los archivos JSONL (JSON Lines) se utilizan habitualmente para la ingesta de logs, los conjuntos de datos de aprendizaje automático, el procesamiento por lotes en APIs y los pipelines de datos. Como cada línea es un objeto JSON independiente, el formato no incluye ningún mecanismo que garantice una estructura uniforme en todos los registros. Basta con una línea mal formada, la ausencia de un campo obligatorio o un tipo de dato inesperado para alterar el procesamiento posterior sin que se detecte, interrumpir el entrenamiento de modelos o hacer que una tarea por lotes de una API falle a mitad de la ejecución.
La validación de esquemas resuelve este problema al definir un contrato formal que todos los registros deben cumplir. JSON Schema es el estándar del sector para describir la estructura, los tipos y las restricciones de los datos JSON. Si validas cada línea de un archivo JSONL con un JSON Schema antes de incorporarla a tu pipeline, detectas los errores a tiempo, reduces el tiempo de depuración y garantizas la calidad de los datos a gran escala. Esta guía te acompaña en todo el proceso, desde la creación de tu primer esquema hasta la integración de la validación en flujos de trabajo automatizados de CI/CD.
Fundamentos de JSON Schema para JSONL
JSON Schema es un lenguaje declarativo que permite describir la estructura que debe tener un objeto JSON. Con él defines qué campos son obligatorios, qué tipos de datos deben contener, los rangos de valores admitidos, los patrones que deben cumplir las cadenas y otras restricciones. Al validar un archivo JSONL, se aplica el mismo esquema a cada una de sus líneas. Así se garantiza que todos los registros tengan una estructura uniforme, algo esencial para procesar los datos de forma fiable.
Este ejemplo de JSON Schema describe un registro de evento de usuario. Exige los campos id (entero), event (cadena con un valor de un conjunto fijo) y timestamp (en formato ISO 8601), y permite un objeto metadata opcional. El campo additionalProperties está configurado como false para rechazar cualquier clave inesperada.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "event", "timestamp"],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event": {
"type": "string",
"enum": ["click", "view", "purchase", "signup"]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"properties": {
"source": { "type": "string" },
"campaign": { "type": "string" }
},
"additionalProperties": false
}
},
"additionalProperties": false
}Este archivo JSONL contiene registros que cumplen el esquema anterior. Cada línea es un objeto JSON completo que representa un evento de usuario. Observa que el campo opcional metadata aparece en algunas líneas y en otras no: ambos casos son válidos según el esquema.
{"id":1,"event":"click","timestamp":"2026-02-15T10:30:00Z","metadata":{"source":"google","campaign":"spring"}}
{"id":2,"event":"purchase","timestamp":"2026-02-15T11:00:00Z"}
{"id":3,"event":"view","timestamp":"2026-02-15T11:15:00Z","metadata":{"source":"direct"}}
{"id":4,"event":"signup","timestamp":"2026-02-15T12:00:00Z"}Cómo validar archivos JSONL con Python, Node.js y la línea de comandos
Hay varias herramientas consolidadas para validar datos JSONL con un JSON Schema. La mejor opción depende de tu stack. Quienes desarrollan en Python suelen usar la biblioteca jsonschema; en JavaScript, la opción habitual es Ajv. Los equipos que prefieren trabajar con scripts de shell pueden recurrir a validadores de línea de comandos. A continuación se muestran las tres opciones.
La biblioteca jsonschema es el paquete de Python más popular para validar datos con JSON Schema. Instálala con pip install jsonschema. El siguiente script lee un archivo JSONL línea por línea, valida cada registro y recopila todos los errores junto con sus números de línea para facilitar la depuración.
import json
from jsonschema import validate, ValidationError
def validate_jsonl(file_path, schema):
errors = []
with open(file_path, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, start=1):
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
validate(instance=record, schema=schema)
except json.JSONDecodeError as e:
errors.append({
'line': line_num,
'error': f'Invalid JSON: {e.msg}'
})
except ValidationError as e:
errors.append({
'line': line_num,
'error': e.message,
'path': list(e.absolute_path)
})
return errors
# Load schema and validate
with open('schema.json', 'r') as f:
schema = json.load(f)
errors = validate_jsonl('data.jsonl', schema)
if errors:
print(f'Found {len(errors)} validation errors:')
for err in errors:
print(f" Line {err['line']}: {err['error']}")
else:
print('All records are valid!')Ajv (Another JSON Schema Validator) es el validador de JSON Schema más rápido para JavaScript. Instálalo con npm install ajv ajv-formats. El paquete ajv-formats añade compatibilidad con palabras clave de formato como date-time. Este script procesa el archivo JSONL en streaming, línea por línea, para reducir el consumo de memoria.
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import schema from './schema.json' assert { type: 'json' };
const ajv = new Ajv({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(schema);
async function validateJsonl(filePath) {
const errors = [];
let lineNum = 0;
const rl = createInterface({
input: createReadStream(filePath, 'utf-8'),
crlfDelay: Infinity,
});
for await (const line of rl) {
lineNum++;
const trimmed = line.trim();
if (!trimmed) continue;
try {
const record = JSON.parse(trimmed);
if (!validate(record)) {
errors.push({
line: lineNum,
errors: validate.errors.map(e =>
`${e.instancePath || '/'}: ${e.message}`
),
});
}
} catch (e) {
errors.push({ line: lineNum, errors: [`Invalid JSON: ${e.message}`] });
}
}
return errors;
}
const errors = await validateJsonl('data.jsonl');
if (errors.length) {
console.log(`Found ${errors.length} invalid records:`);
errors.forEach(e =>
console.log(` Line ${e.line}: ${e.errors.join(', ')}`)
);
process.exit(1);
} else {
console.log('All records are valid!');
}Para comprobaciones puntuales o flujos de trabajo basados en shell, puedes combinar jq y ajv-cli. El siguiente ejemplo separa el archivo JSONL en objetos JSON individuales y valida cada uno con el esquema. Es una opción útil si no quieres escribir un script a medida.
# Install ajv-cli globally
npm install -g ajv-cli ajv-formats
# Validate each line of a JSONL file against a schema
line_num=0
errors=0
while IFS= read -r line; do
line_num=$((line_num + 1))
if [ -z "$line" ]; then continue; fi
echo "$line" | ajv validate -s schema.json -d /dev/stdin --all-errors 2>/dev/null
if [ $? -ne 0 ]; then
echo " Error on line $line_num"
errors=$((errors + 1))
fi
done < data.jsonl
if [ $errors -eq 0 ]; then
echo "All records are valid!"
else
echo "Found $errors invalid records"
exit 1
fiAutomatiza la validación en pipelines de CI/CD
La validación manual sirve para conjuntos de datos pequeños, pero los flujos de trabajo en producción necesitan automatización. Al integrar la validación de esquemas JSONL en tu pipeline de CI/CD, se comprueba cada cambio en los datos antes de que llegue a producción. Así evitas que los datos incorrectos entren en tu data warehouse, interrumpan el entrenamiento de modelos o alteren las tareas por lotes de las APIs. El siguiente flujo de trabajo de GitHub Actions valida los archivos JSONL en cada push y pull request.
name: Validate JSONL
on:
push:
paths: ['data/**/*.jsonl']
pull_request:
paths: ['data/**/*.jsonl']
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: pip install jsonschema
- name: Validate all JSONL files
run: |
python -c "
import json, glob, sys
from jsonschema import validate, ValidationError
with open('schemas/events.json') as f:
schema = json.load(f)
total_errors = 0
for path in glob.glob('data/**/*.jsonl', recursive=True):
with open(path) as f:
for num, line in enumerate(f, 1):
line = line.strip()
if not line: continue
try:
validate(json.loads(line), schema)
except (json.JSONDecodeError, ValidationError) as e:
print(f'{path}:{num}: {e}')
total_errors += 1
if total_errors:
print(f'\nFailed: {total_errors} errors found')
sys.exit(1)
print('All JSONL files are valid!')
"Este flujo de trabajo solo se activa cuando cambian los archivos JSONL del directorio data, para que la CI siga siendo rápida. El script de validación carga el esquema una sola vez y comprueba todos los archivos JSONL que encuentra mediante una búsqueda recursiva. Si algún registro no supera la validación, el flujo termina con un código de salida distinto de cero y bloquea el merge. Puedes ampliar este patrón con varios esquemas para distintos tipos de archivo, notificaciones de Slack cuando falle la validación o informes de validación que se suban como artefactos de compilación.
Errores de validación habituales y cómo corregirlos
Al activar por primera vez la validación de esquemas en un conjunto de datos JSONL existente, es habitual descubrir problemas de calidad que habían pasado inadvertidos. Estos son los tres errores de validación más comunes y cómo resolverlos.
Tipo de dato incorrecto
Este error aparece cuando un campo contiene un valor de un tipo distinto al esperado. El caso más habitual es el de los identificadores numéricos almacenados como cadenas, algo que suele ocurrir al exportar datos de hojas de cálculo o archivos CSV. Para corregirlo, convierte el valor al tipo adecuado durante el proceso ETL o modifica el esquema para que acepte varios tipos si ambos son válidos.
// Schema expects: { "type": "integer" }
// Invalid record:
{"id": "42", "event": "click", "timestamp": "2026-02-15T10:00:00Z"}
// Fix: cast to integer during processing
// Python: record['id'] = int(record['id'])
// JS: record.id = Number(record.id)Faltan campos obligatorios
Este error indica que a un registro le falta una propiedad incluida en el array required del esquema. Suele ocurrir cuando los sistemas de origen cambian su formato de salida o cuando se omiten campos opcionales por error. Incorpora valores predeterminados en tu pipeline de datos o modifica el esquema para que el campo sea opcional si realmente no está siempre presente.
// Schema requires: ["id", "event", "timestamp"]
// Invalid record (no timestamp):
{"id": 5, "event": "view"}
// Fix option 1: add default timestamp
// Python: record.setdefault('timestamp', datetime.utcnow().isoformat() + 'Z')
// Fix option 2: make timestamp optional in schema
// Change required to: ["id", "event"]Propiedades adicionales inesperadas
Si additionalProperties está configurado como false en tu esquema, cualquier campo que no figure explícitamente en properties provocará un error de validación. Es una restricción estricta, pero resulta útil para detectar errores tipográficos y fugas de datos. Si quieres permitir campos adicionales, configura additionalProperties como true o utiliza patternProperties para definir un patrón que deban cumplir los nombres de las propiedades permitidas.
// Schema has: "additionalProperties": false
// Invalid record (extra field "user_agent"):
{"id": 6, "event": "click", "timestamp": "2026-02-15T14:00:00Z", "user_agent": "Mozilla/5.0"}
// Fix option 1: remove the extra field before validation
// Fix option 2: add "user_agent" to schema properties
// Fix option 3: set "additionalProperties": trueValida archivos JSONL en línea
¿Quieres comprobar tus datos JSONL rápidamente sin escribir un script? Usa nuestras herramientas gratuitas para validar, dar formato e inspeccionar archivos JSONL desde el navegador. Todo el procesamiento se realiza localmente en tu navegador, por lo que tus datos se mantienen privados.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Domina las buenas prácticas de JSONL: formato, coherencia del esquema, gestión de errores, optimización del rendimiento y organización de archivos. Evita los errores habituales con ejemplos prácticos.
Guía completa para preparar archivos JSONL para OpenAI. Incluye el formato de los datos de fine-tuning, las solicitudes de Batch API, los errores habituales y consejos de validación.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Guía completa para trabajar con archivos JSONL en Python. Aprende a leer, escribir y parsear JSONL con json, pandas y orjson, y a usar streaming para archivos grandes.