Cómo validar esquemas JSON en Python para datos
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.