(+351) 21 24 10006  ·  info@bconcepts.pt
Carnaxide, Lisboa

Cómo validar esquemas JSON en Python para datos

João Barros 17 de November de 2026 6 min de lectura

Este tutorial muestra cómo validar esquemas JSON en Python para datos usando jsonschema, una tarea útil para garantizar que los archivos JSON tienen las claves y tipos esperados antes del procesamiento ETL o ingestión en bases de datos. La validación ayuda a prevenir fallos tardíos en el pipeline, a producir registros de error consistentes y a aplicar reglas de calidad antes de la transformación o carga.

Requisitos previos

  • Instalar Python 3.8+ (recomendado 3.9 o 3.10 para compatibilidades modernas)
  • Conocimientos básicos de Python y JSON (estructuras object/array, tipos primitivos)
  • Biblioteca jsonschema (instalar con pip)

Paso 1: ¿Por qué validar esquemas JSON?

Los archivos JSON pueden variar: campos ausentes, tipos inesperados o estructuras anidadas diferentes. Validar esquemas evita errores más adelante en el pipeline y permite rechazar, corregir o registrar registros inválidos de forma temprana. En un ejemplo práctico, si tienes 10 000 registros por día y el 2% tienen problemas de formato, validar desde el inicio reduce en cientos los registros que causarían fallos en el procesamiento ETL. Además, un schema bien definido sirve como contrato entre productores y consumidores de datos, dejando claro qué campos son obligatorios, cuáles son opcionales y qué formatos (por ejemplo ISO8601 para fechas) son aceptables.

Paso 2: Instalar jsonschema

Usa jsonschema porque es simple, compatible con Drafts comunes y ampliamente utilizado en pipelines de datos. Para instalar:

pip install jsonschema

Nota: jsonschema soporta varios Drafts (p.ej. Draft4, Draft7). La mayoría de los ejemplos usan Draft7, suficiente para requisitos típicos (type, required, format, minimum, etc.).

Paso 3: Definir el schema JSON (ejemplo)

Crea un schema que describa la estructura esperada. Aquí tenemos un ejemplo para registros de ventas con campos obligatorios y tipos claros. Este schema especifica también límites (minimum) para cantidad y precio, lo que evita aceptar números negativos por error.

sales_schema = {
    "type": "object",
    "required": ["sale_id", "date", "customer", "items", "total"],
    "properties": {
        "sale_id": {"type": "string"},
        "date": {"type": "string", "format": "date"},
        "customer": {
            "type": "object",
            "required": ["id", "name"],
            "properties": {
                "id": {"type": "string"},
                "name": {"type": "string"}
            }
        },
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "required": ["sku", "qty", "price"],
                "properties": {
                    "sku": {"type": "string"},
                    "qty": {"type": "integer", "minimum": 1},
                    "price": {"type": "number", "minimum": 0}
                }
            }
        },
        "total": {"type": "number", "minimum": 0}
    }
}

Ejemplos concretos: un registro válido tiene total 123.45 e items length 2; un registro inválido puede tener "qty": 0 o "date": "2020/01/01" (formato incorrecto).

Paso 4: Validar un único archivo JSON

Ejemplo mínimo para validar un archivo JSON con jsonschema. El código lee el archivo, valida y maneja errores comunes como ValidationError. Para validar formatos (p.ej.: date) usa FormatChecker.

import json
from jsonschema import validate, ValidationError, FormatChecker

with open('sale_example.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

try:
    validate(instance=data, schema=sales_schema, format_checker=FormatChecker())
    print('Validación exitosa')
except ValidationError as e:
    print('Error de validación:', e.message)
    # Para debug: print(e.path, e.schema_path)

Si el archivo contiene un único registro, este flujo deja listo para cargar en la base de datos. Si falla, devuelve un mensaje legible con la razón (p.ej. "'date' is a required property" o "0 is less than the minimum of 1").

Paso 5: Validar múltiples registros y registrar errores

En un pipeline es común recibir muchos archivos o un archivo con varios registros. Itera, valida con Draft7Validator para obtener todos los errores y regístralos en un archivo de log. Aquí tienes una función que separa válidos e inválidos y guarda los errores en un json organizado.

from jsonschema import Draft7Validator, FormatChecker
import json

def validate_records(records, schema):
    validator = Draft7Validator(schema, format_checker=FormatChecker())
    valid = []
    invalid = []
    for i, rec in enumerate(records):
        errors = list(validator.iter_errors(rec))
        if errors:
            invalid.append({
                'index': i,
                'errors': [e.message for e in errors]
            })
        else:
            valid.append(rec)
    return valid, invalid

with open('sales_batch.json', 'r', encoding='utf-8') as f:
    batch = json.load(f)  # assume é uma lista de registos

valid, invalid = validate_records(batch, sales_schema)
print(f'Válidos: {len(valid)}, Inválidos: {len(invalid)}')
with open('validation_errors.json', 'w', encoding='utf-8') as out:
    json.dump(invalid, out, indent=2, ensure_ascii=False)

Ejemplo práctico: en un lote de 5 000 registros, obtienes rápidamente un recuento y un archivo validation_errors.json con entradas como {"index": 37, "errors": ["'total' is a required property"]} para análisis posterior.

Paso 6: Errores comunes y cómo resolverlos

Errores frecuentes: tipos incorrectos (string en lugar de number), campos ausentes, fechas en formato desconocido. Resolución: ajustar el producer del JSON, normalizar datos antes de validar (por ejemplo convertir strings a números), o actualizar el schema para reflejar campos opcionales. Algunas estrategias concretas:

  • Preprocesamiento: convertir "qty": "2" → int(2) antes de validar si el producer envía strings.
  • Schema más tolerante: usar "anyOf" para aceptar string o number en campos legacy.
  • Registrar métricas: cuenta % de registros inválidos por día y define un umbral (p. ej., por encima del 5% detener la ingestión automática).

Verificar el resultado

Confirma que la validación funcionó verificando la salida: archivo validation_errors.json con errores detallados y el número de registros válidos/ inválidos. Para una prueba rápida, cambia un campo en sale_example.json por un tipo incorrecto y confirma que aparece un error de validación. En entorno de pruebas, crea conjuntos de datos con 10, 100 y 1 000 registros para medir rendimiento: jsonschema es lo suficientemente rápido para cientos de miles de verificaciones por minuto en CPU moderna, pero para millones considera validar en paralelo o usar validación en streaming.

Conclusión

Validar esquemas JSON en Python para datos con jsonschema reduce fallos en pipelines y facilita el tratamiento de registros inválidos. Próximos pasos: integrar esta validación en una etapa ETL, normalizar datos antes de validar o usar schemas más avanzados (p.ej.: formatos personalizados). Consejo práctico: comienza por crear tests unitarios con ejemplos válidos e inválidos (p.ej. 10 casos de cada) para asegurar que el schema cubre los casos reales y monitoriza el porcentaje de errores tras la integración.