Por Jerry Fan

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.

Define un JSON Schema
{
  "$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.

Datos JSONL de ejemplo
{"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.

Python con jsonschema
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.

Node.js con Ajv
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.

Validación desde la línea de comandos
# 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
fi

Automatiza 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.

Flujo de trabajo de GitHub Actions
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.

Ejemplo: ID como cadena en lugar de entero
// 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.

Ejemplo: falta el campo timestamp
// 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.

Ejemplo: campo desconocido en el registro
// 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": true

Valida tus archivos JSONL ahora

Carga tu archivo JSONL y detecta al instante errores de sintaxis, problemas de estructura y fallos de formato. El archivo no se envía a ningún servidor: 100% privado.

Preguntas frecuentes

Referencias