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

Como fazer validação de esquemas JSON em Python para dados

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

Este tutorial mostra como validar esquemas JSON em Python para dados usando jsonschema, uma tarefa útil para garantir que ficheiros JSON têm as chaves e tipos esperados antes do processamento ETL ou ingestão em bases de dados. A validação ajuda a prevenir falhas tardias no pipeline, a produzir registos de erro consistentes e a aplicar regras de qualidade antes de transformação ou carregamento.

Pré-requisitos

  • Instalar Python 3.8+ (recomendado 3.9 ou 3.10 para compatibilidades modernas)
  • Conhecimentos básicos de Python e JSON (estruturas object/array, tipos primitivos)
  • Biblioteca jsonschema (instalar com pip)

Passo 1: Porquê validar esquemas JSON?

Ficheiros JSON podem variar: campos em falta, tipos inesperados ou estruturas aninhadas diferentes. Validar esquemas evita erros mais tarde no pipeline e permite rejeitar, corrigir ou registar registos inválidos cedo. Num exemplo prático, se tens 10 000 registos por dia e 2% têm problemas de formato, validar logo reduz em centenas os registos que causariam falhas no processamento ETL. Além disso, um schema bem definido serve como contrato entre produtores e consumidores de dados, tornando claro quais campos são obrigatórios, quais são opcionais e que formatos (por exemplo ISO8601 para datas) são aceitáveis.

Passo 2: Instalar jsonschema

Usa jsonschema porque é simples, compatível com Drafts comuns e amplamente usado em pipelines de dados. Para instalar:

pip install jsonschema

Nota: jsonschema suporta vários Drafts (p.ex. Draft4, Draft7). A maioria dos exemplos usa Draft7, suficiente para requisitos típicos (type, required, format, minimum, etc.).

Passo 3: Definir o schema JSON (exemplo)

Cria um schema que descreve a estrutura esperada. Aqui temos um exemplo para registos de vendas com campos obrigatórios e tipos claros. Este schema especifica também limites (minimum) para quantidade e preço, o que evita aceitar números negativos por engano.

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}
    }
}

Exemplos concretos: um registo válido tem total 123.45 e items length 2; um registo inválido pode ter "qty": 0 ou "date": "2020/01/01" (formato errado).

Passo 4: Validar um único ficheiro JSON

Exemplo mínimo para validar um ficheiro JSON com jsonschema. O código lê o ficheiro, valida e trata erros comuns como ValidationError. Para validar formatos (ex.: 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('Validação bem-sucedida')
except ValidationError as e:
    print('Erro de validação:', e.message)
    # Para debug: print(e.path, e.schema_path)

Se o ficheiro tiver um único registo, este fluxo deixa pronto para carregar para a base de dados. Se falhar, devolve uma mensagem legível com a razão (p.ex. "'date' is a required property" ou "0 is less than the minimum of 1").

Passo 5: Validar múltiplos registos e registar erros

Num pipeline é comum receber muitos ficheiros ou um ficheiro com vários registos. Itera, valida com Draft7Validator para obter todos os erros e regista-os num ficheiro de log. Aqui tens uma função que separa válidos e inválidos e grava os erros num 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)

Exemplo prático: num lote de 5 000 registos, obteres rapidamente uma contagem e um ficheiro validation_errors.json com entradas como {"index": 37, "errors": ["'total' is a required property"]} para posterior análise.

Passo 6: Erros comuns e como os resolver

Erros frequentes: tipos errados (string em vez de number), campos em falta, datas em formato desconhecido. Resolução: ajustar o producer do JSON, normalizar dados antes de validar (por exemplo converter strings para números), ou actualizar o schema para reflectir campos opcionais. Algumas estratégias concretas:

  • Pre-processamento: converter "qty": "2" → int(2) antes de validar se o producer envia strings.
  • Schema mais tolerante: usar "anyOf" para aceitar string ou number em campos legacy.
  • Registar métricas: conta % de registos inválidos por dia e define um threshold (por ex., acima de 5% parar ingestão automática).

Verificar o resultado

Confirma que a validação funcionou verificando a saída: ficheiro validation_errors.json com erros detalhados e o número de registos válidos/ inválidos. Para um teste rápido, altera um campo no sale_example.json para um tipo errado e confirma que aparece um erro de validação. Em ambiente de testes, cria conjuntos de dados com 10, 100 e 1 000 registos para medir desempenho: jsonschema é suficientemente rápido para centenas de milhares de verificações por minuto em CPU moderno, mas para milhões considera validar em paralelo ou usar validação em streaming.

Conclusão

Validar esquemas JSON em Python para dados com jsonschema reduz falhas em pipelines e facilita o tratamento de registos inválidos. Próximos passos: integrar esta validação numa etapa ETL, normalizar dados antes de validar ou usar schemas mais avançados (ex.: formats personalizados). Dica prática: começa por criar testes unitários com exemplos válidos e inválidos (p.ex. 10 casos de cada) para garantir que o schema cobre os casos reais e monitoriza a percentagem de erros após a integração.