Validação de schema em JSONL: garanta a qualidade dos dados
Um guia completo para validar arquivos JSONL com JSON Schema. Aprenda a definir schemas, validar registros em Python e Node.js, automatizar verificações em pipelines de CI/CD e diagnosticar erros comuns de validação.
Por que arquivos JSONL precisam de validação de schema
Arquivos JSONL (JSON Lines) são muito usados na ingestão de logs, em datasets de aprendizado de máquina, no processamento em lote de APIs e em pipelines de dados. Como cada linha é um objeto JSON independente, o formato não oferece um mecanismo próprio para garantir que todos os registros tenham uma estrutura consistente. Uma única linha malformada, um campo obrigatório ausente ou um tipo de dado inesperado pode comprometer silenciosamente as etapas seguintes do processamento, interromper o treinamento de modelos ou fazer um job de processamento em lote de uma API falhar no meio da execução.
A validação de schema resolve esse problema ao definir um contrato formal que todos os registros devem cumprir. JSON Schema é o padrão do setor para descrever a estrutura, os tipos e as restrições dos dados JSON. Ao validar cada linha de um arquivo JSONL com um JSON Schema antes de os dados entrarem no seu pipeline, você detecta erros logo no início, reduz o tempo de depuração e garante a qualidade dos dados em escala. Este guia acompanha você em todo o processo, da criação do seu primeiro schema à integração da validação em workflows automatizados de CI/CD.
Fundamentos de JSON Schema para JSONL
JSON Schema é uma linguagem declarativa que permite descrever a estrutura esperada de um objeto JSON. Você define quais campos são obrigatórios, os tipos de dados de cada um, os intervalos de valores aceitos, os padrões para strings e muito mais. Na validação de JSONL, cada linha do arquivo é validada com o mesmo schema. Isso garante uma estrutura consistente entre todos os registros, algo essencial para um processamento de dados confiável.
O exemplo abaixo mostra um JSON Schema para um registro de evento de usuário. Os campos obrigatórios são id (inteiro), event (string com um dos valores de um conjunto fixo) e timestamp (no formato ISO 8601). O objeto metadata é opcional. O campo additionalProperties está definido como false para rejeitar qualquer chave inesperada.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "event", "timestamp"],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event": {
"type": "string",
"enum": ["click", "view", "purchase", "signup"]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"properties": {
"source": { "type": "string" },
"campaign": { "type": "string" }
},
"additionalProperties": false
}
},
"additionalProperties": false
}Este arquivo JSONL contém registros que seguem o schema acima. Cada linha é um objeto JSON completo que representa um evento de usuário. Observe que o campo opcional metadata aparece em algumas linhas e não em outras: as duas situações são válidas de acordo com o schema.
{"id":1,"event":"click","timestamp":"2026-02-15T10:30:00Z","metadata":{"source":"google","campaign":"spring"}}
{"id":2,"event":"purchase","timestamp":"2026-02-15T11:00:00Z"}
{"id":3,"event":"view","timestamp":"2026-02-15T11:15:00Z","metadata":{"source":"direct"}}
{"id":4,"event":"signup","timestamp":"2026-02-15T12:00:00Z"}Como validar arquivos JSONL com Python, Node.js e CLI
Há várias ferramentas consolidadas para validar JSONL com JSON Schema. A melhor escolha depende da stack que você já usa. Quem desenvolve em Python costuma usar a biblioteca jsonschema; em JavaScript, a escolha mais comum é o Ajv. Equipes que preferem scripts de shell podem usar validadores de linha de comando. Veja as três abordagens a seguir.
A biblioteca jsonschema é o pacote Python mais popular para validação com JSON Schema. Instale com pip install jsonschema. O script abaixo lê um arquivo JSONL linha por linha, valida cada registro e reúne todos os erros com os respectivos números de linha para facilitar a depuração.
import json
from jsonschema import validate, ValidationError
def validate_jsonl(file_path, schema):
errors = []
with open(file_path, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, start=1):
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
validate(instance=record, schema=schema)
except json.JSONDecodeError as e:
errors.append({
'line': line_num,
'error': f'Invalid JSON: {e.msg}'
})
except ValidationError as e:
errors.append({
'line': line_num,
'error': e.message,
'path': list(e.absolute_path)
})
return errors
# Load schema and validate
with open('schema.json', 'r') as f:
schema = json.load(f)
errors = validate_jsonl('data.jsonl', schema)
if errors:
print(f'Found {len(errors)} validation errors:')
for err in errors:
print(f" Line {err['line']}: {err['error']}")
else:
print('All records are valid!')Ajv (Another JSON Schema Validator) é o validador de JSON Schema mais rápido para JavaScript. Instale com npm install ajv ajv-formats. O pacote ajv-formats adiciona suporte a palavras-chave de formato, como date-time. O script lê o arquivo JSONL em streaming, linha por linha, para reduzir o uso de memória.
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import schema from './schema.json' assert { type: 'json' };
const ajv = new Ajv({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(schema);
async function validateJsonl(filePath) {
const errors = [];
let lineNum = 0;
const rl = createInterface({
input: createReadStream(filePath, 'utf-8'),
crlfDelay: Infinity,
});
for await (const line of rl) {
lineNum++;
const trimmed = line.trim();
if (!trimmed) continue;
try {
const record = JSON.parse(trimmed);
if (!validate(record)) {
errors.push({
line: lineNum,
errors: validate.errors.map(e =>
`${e.instancePath || '/'}: ${e.message}`
),
});
}
} catch (e) {
errors.push({ line: lineNum, errors: [`Invalid JSON: ${e.message}`] });
}
}
return errors;
}
const errors = await validateJsonl('data.jsonl');
if (errors.length) {
console.log(`Found ${errors.length} invalid records:`);
errors.forEach(e =>
console.log(` Line ${e.line}: ${e.errors.join(', ')}`)
);
process.exit(1);
} else {
console.log('All records are valid!');
}Para verificações rápidas e pontuais ou workflows baseados em shell, você pode combinar jq e ajv-cli. A abordagem abaixo separa o arquivo JSONL em objetos JSON individuais e valida cada um com o schema. É uma opção útil quando você não quer escrever um script próprio.
# Install ajv-cli globally
npm install -g ajv-cli ajv-formats
# Validate each line of a JSONL file against a schema
line_num=0
errors=0
while IFS= read -r line; do
line_num=$((line_num + 1))
if [ -z "$line" ]; then continue; fi
echo "$line" | ajv validate -s schema.json -d /dev/stdin --all-errors 2>/dev/null
if [ $? -ne 0 ]; then
echo " Error on line $line_num"
errors=$((errors + 1))
fi
done < data.jsonl
if [ $errors -eq 0 ]; then
echo "All records are valid!"
else
echo "Found $errors invalid records"
exit 1
fiComo automatizar a validação em pipelines de CI/CD
A validação manual funciona para datasets pequenos, mas workflows de produção exigem automação. Ao integrar a validação de schema dos arquivos JSONL ao seu pipeline de CI/CD, toda alteração nos dados é verificada antes de chegar à produção. Isso evita que dados incorretos entrem no seu data warehouse, interrompam o treinamento de modelos ou comprometam jobs de processamento em lote de APIs. O workflow do GitHub Actions abaixo valida arquivos JSONL a cada push e pull request.
name: Validate JSONL
on:
push:
paths: ['data/**/*.jsonl']
pull_request:
paths: ['data/**/*.jsonl']
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: pip install jsonschema
- name: Validate all JSONL files
run: |
python -c "
import json, glob, sys
from jsonschema import validate, ValidationError
with open('schemas/events.json') as f:
schema = json.load(f)
total_errors = 0
for path in glob.glob('data/**/*.jsonl', recursive=True):
with open(path) as f:
for num, line in enumerate(f, 1):
line = line.strip()
if not line: continue
try:
validate(json.loads(line), schema)
except (json.JSONDecodeError, ValidationError) as e:
print(f'{path}:{num}: {e}')
total_errors += 1
if total_errors:
print(f'\nFailed: {total_errors} errors found')
sys.exit(1)
print('All JSONL files are valid!')
"Esse workflow só é acionado quando há alterações em arquivos JSONL no diretório data, o que mantém o CI rápido. O script de validação carrega o schema uma única vez e verifica todos os arquivos JSONL encontrados na busca recursiva. Se algum registro falhar na validação, o workflow termina com um código de saída diferente de zero e bloqueia o merge. Você pode ampliar essa abordagem com vários schemas para diferentes tipos de arquivo, notificações no Slack em caso de falha ou o upload de relatórios de validação como artefatos de build.
Erros comuns de validação e como corrigi-los
Ao ativar a validação de schema pela primeira vez em um dataset JSONL existente, é comum descobrir problemas de qualidade dos dados que passaram despercebidos. Veja os três erros de validação mais frequentes e como resolver cada um.
Incompatibilidade de tipo
Esse erro ocorre quando um campo contém um valor de um tipo diferente do esperado. O caso mais comum é o de IDs numéricos armazenados como strings, algo que acontece na exportação de dados de planilhas ou arquivos CSV. Para corrigir, converta o valor para o tipo correto durante o processo de ETL ou atualize o schema para aceitar vários tipos, caso ambos sejam válidos.
// Schema expects: { "type": "integer" }
// Invalid record:
{"id": "42", "event": "click", "timestamp": "2026-02-15T10:00:00Z"}
// Fix: cast to integer during processing
// Python: record['id'] = int(record['id'])
// JS: record.id = Number(record.id)Campos obrigatórios ausentes
Esse erro indica que falta no registro uma propriedade listada no array required do schema. Isso costuma acontecer quando os sistemas que fornecem os dados mudam o formato de saída ou quando campos opcionais são omitidos por engano. Adicione ao seu pipeline de dados um tratamento para preencher valores padrão ou atualize o schema para tornar o campo opcional, caso ele realmente nem sempre esteja presente.
// Schema requires: ["id", "event", "timestamp"]
// Invalid record (no timestamp):
{"id": 5, "event": "view"}
// Fix option 1: add default timestamp
// Python: record.setdefault('timestamp', datetime.utcnow().isoformat() + 'Z')
// Fix option 2: make timestamp optional in schema
// Change required to: ["id", "event"]Propriedades adicionais inesperadas
Quando additionalProperties está definido como false no schema, qualquer campo que não esteja explicitamente listado em properties gera um erro de validação. Essa regra é rigorosa, mas ajuda a detectar erros de digitação e vazamentos de dados. Se a intenção é permitir campos extras, defina additionalProperties como true ou use patternProperties para definir um padrão para os nomes de propriedades permitidos.
// Schema has: "additionalProperties": false
// Invalid record (extra field "user_agent"):
{"id": 6, "event": "click", "timestamp": "2026-02-15T14:00:00Z", "user_agent": "Mozilla/5.0"}
// Fix option 1: remove the extra field before validation
// Fix option 2: add "user_agent" to schema properties
// Fix option 3: set "additionalProperties": trueValide arquivos JSONL online
Quer conferir seus dados JSONL rapidamente, sem escrever um script? Use nossas ferramentas gratuitas para validar, formatar e inspecionar arquivos JSONL no navegador. Todo o processamento é feito localmente no seu navegador, mantendo a privacidade dos seus dados.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
Domine as boas práticas de JSONL para formatação, consistência de schema, tratamento de erros, otimização de desempenho e organização de arquivos. Evite problemas comuns com exemplos práticos.
Guia completo para preparar arquivos JSONL para a OpenAI. Conheça o formato dos dados de fine-tuning, as requisições da Batch API, os erros comuns e as dicas de validação.
Estratégias para processar gigabytes de dados JSONL: leitura por streaming, gerenciamento de memória, divisão de arquivos, compressão e ferramentas online.
Guia completo para trabalhar com arquivos JSONL em Python. Aprenda a ler, escrever e interpretar JSONL com json, pandas e orjson, além de usar streaming para arquivos grandes.