Como validar esquemas JSON de uma API de Dados em Python: passo a passo

Este tutorial mostra como validar esquemas JSON de uma API de Dados em Python para garantir que os dados recebidos estão no formato esperado e reduzir erros em downstream. A validação é útil para detetar campos em falta, tipos errados e estruturas inesperadas antes de processar ou carregar dados.

Pré-requisitos

• Python 3.8+ instalado
• Pip para instalar pacotes (requests, jsonschema)
• Conhecimentos básicos de JSON e Python

Passo 1: Porquê validar JSON de uma API de Dados

APIs podem mudar, devolver campos opcionais ou tipos diferentes. Validar com um esquema evita que código de processamento falhe de forma silenciosa e facilita logging e alertas. Usa-se um esquema JSON Schema (padrão) para descrever estrutura, tipos e campos obrigatórios.

Passo 2: Instalar dependências

Instala os pacotes necessários: requests para chamar a API e jsonschema para validar. É simples e rápido.

pip install requests jsonschema

Passo 3: Definir um JSON Schema mínimo

Cria um esquema que descreve os campos essenciais que esperas da API. Aqui fica um exemplo para dados de utilizadores com id, nome e e-mail. Ajusta conforme a tua 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"]
}

Passo 4: Fazer a chamada à API e validar uma resposta única

Usa requests para obter JSON e jsonschema.validate para verificar. Trata exceções para reportar erros claros (tipo, campo em falta, 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)

Passo 5: Validar listas de registos e recolher erros

Quando a API devolve uma lista, valida cada item e acumula erros. Assim consegues processar registos válidos e registar os inválidos para inspeção.

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")

Passo 6: Lidar com campos opcionais e esquemas flexíveis

Se a API tem campos adicionais, usa "additionalProperties": true ou define um subschema para campos extra. Para esquemas que mudam frequentemente, valida apenas os campos essenciais (minimizar falsos positivos).

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

Passo 7: Erros comuns e como os resolver

Erros habituais: format missing (usar formats ou validar manualmente), tipos inteiros enviados como string (converter ou aceitar ambos com "oneOf"), e campos opcionalmente ausentes. Regista a resposta bruta ao detectar erro 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 o resultado

Testa com chamadas reais: deves ver "Validação OK" para registos conformes e receber mensagens claras para falhas. Para listas, confirma que valid_items contém apenas registos válidos e que errors tem entradas com mensagens de erro. Adiciona logs com URL, status code e payload quando uma validação falha.

Conclusão

Validar esquemas JSON de uma API de Dados em Python reduz falhas e facilita a deteção de alterações na API. Próximos passos: integrar a validação num pipeline ETL, automatizar testes com fixtures e usar CI para alertar quando a API muda. Dica: começa por validar só os campos críticos e expande o esquema conforme ganhas confiança — tens alguma API específica que queiras validar?