Cómo validar esquemas JSON de una API de Datos en Python: paso a paso

Este tutorial muestra cómo validar esquemas JSON de una API de Datos en Python para garantizar que los datos recibidos están en el formato esperado y reducir errores en downstream. La validación es útil para detectar campos faltantes, tipos incorrectos y estructuras inesperadas antes de procesar o cargar datos.

Requisitos previos

• Python 3.8+ instalado
• Pip para instalar paquetes (requests, jsonschema)
• Conocimientos básicos de JSON y Python

Paso 1: Por qué validar JSON de una API de Datos

Las APIs pueden cambiar, devolver campos opcionales o tipos diferentes. Validar con un esquema evita que el código de procesamiento falle de forma silenciosa y facilita el logging y las alertas. Se usa un esquema JSON Schema (estándar) para describir estructura, tipos y campos obligatorios.

Paso 2: Instalar dependencias

Instala los paquetes necesarios: requests para llamar a la API y jsonschema para validar. Es sencillo y rápido.

pip install requests jsonschema

Paso 3: Definir un JSON Schema mínimo

Crea un esquema que describa los campos esenciales que esperas de la API. Aquí tienes un ejemplo para datos de usuarios con id, nombre y correo electrónico. Ajusta según tu API.

user_schema = {
    "type": "object",
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"},
        "created_at": {"type": "string", "format": "date-time"}
    },
    "required": ["id", "name", "email"]
}

Paso 4: Hacer la llamada a la API y validar una respuesta única

Usa requests para obtener JSON y jsonschema.validate para verificar. Maneja excepciones para reportar errores claros (tipo, campo ausente, formato).

import requests
from jsonschema import validate, ValidationError

url = "https://api.exemplo.com/users/123"  # substitui pela tua endpoint
resp = requests.get(url, timeout=10)
resp.raise_for_status()
data = resp.json()

try:
    validate(instance=data, schema=user_schema)
    print("Validação OK")
except ValidationError as e:
    print("Validação falhou:", e.message)

Paso 5: Validar listas de registros y recopilar errores

Cuando la API devuelve una lista, valida cada ítem y acumula errores. Así puedes procesar registros válidos y registrar los inválidos para inspección.

url = "https://api.exemplo.com/users"
resp = requests.get(url, params={"page": 1}, timeout=10)
resp.raise_for_status()
items = resp.json()

valid_items = []
errors = []
for i, item in enumerate(items):
    try:
        validate(instance=item, schema=user_schema)
        valid_items.append(item)
    except ValidationError as e:
        errors.append({"index": i, "error": e.message, "item": item})

print(f"{len(valid_items)} registos válidos, {len(errors)} inválidos")

Paso 6: Manejar campos opcionales y esquemas flexibles

Si la API tiene campos adicionales, usa "additionalProperties": true o define un subschema para campos extra. Para esquemas que cambian con frecuencia, valida solo los campos esenciales (minimizar falsos positivos).

flex_schema = {
    "type": "object",
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string"}
    },
    "required": ["id"],
    "additionalProperties": True
}

Paso 7: Errores comunes y cómo resolverlos

Errores habituales: formato faltante (usar formats o validar manualmente), enteros enviados como string (convertir o aceptar ambos con "oneOf"), y campos opcionalmente ausentes. Registra la respuesta en bruto al detectar un error para diagnóstico.

from jsonschema import Draft7Validator

validator = Draft7Validator(user_schema)
for error in sorted(validator.iter_errors(data), key=str):
    print(error.message)

Verificar el resultado

Prueba con llamadas reales: deberías ver "Validação OK" para registros conformes y recibir mensajes claros para fallos. Para listas, confirma que valid_items contiene solo registros válidos y que errors tiene entradas con mensajes de error. Añade logs con URL, status code y payload cuando una validación falla.

Conclusión

Validar esquemas JSON de una API de Datos en Python reduce fallos y facilita la detección de cambios en la API. Próximos pasos: integrar la validación en un pipeline ETL, automatizar pruebas con fixtures y usar CI para alertar cuando la API cambia. Consejo: empieza por validar solo los campos críticos y expande el esquema conforme ganes confianza — ¿tienes alguna API específica que quieras validar?