14  Validação

Uma referência plausível e falsa é o pior defeito possível num livro didático: é invisível, sobrevive à revisão e chega ao estudante. Por isso a bibliografia da casa é validada por scripts, em duas camadas, e a validação bloqueia a publicação.

14.1 Regra zero: nada inventado

A regra vale para o autor, para os revisores e para a IA que ajuda a escrever (Capítulo 22):

  • Nenhum dado verificável (autor, ano, periódico, DOI, ISBN, páginas) é escrito de memória. Ou o dado foi recuperado da fonte, ou não é escrito.
  • Nenhuma entrada do .bib nasce do que se “lembra” do artigo. Toda entrada nova vem de metadados recuperados: DOI no Crossref ou DataCite, PMID no PubMed, página do editor ou o PDF em mãos.
  • O que não foi confirmado é marcado com note = {pending-verification}, e não aceito em silêncio.
  • “Não encontrei” é resposta aceitável e preferível a preencher a lacuna.

14.2 Validação rápida

O script code/validate_bib.py roda em segundos, sem rede, e é o que bloqueia o CI:

.venv/bin/python code/validate_bib.py --no-doi
.venv/bin/python code/validate_bib.py --no-doi --json validation-basic.json

Ele lê o .bib, varre todos os .qmd atrás de citações e reporta:

O que a validação rápida verifica
Verificação Nível
chave citada que não existe no .bib erro
entrada sem os campos mínimos do tipo erro
chave fora do padrão autor_palavra_ano erro
entrada no .bib não citada em nenhum .qmd aviso
entrada marcada pending-verification relatório
entrada marcada keywords = {sugestao} aviso

Sem --no-doi, o script também resolve cada DOI em doi.org. Linhas dentro de blocos de código são ignoradas, o que permite mostrar a sintaxe de citação num manual como este; fora de bloco de código, qualquer arroba seguida de chave conta como citação, exceto os prefixos de referência cruzada.

14.3 Validação profunda

O script code/deep_validate_bib.py consulta o Crossref (e, para DOIs que não estão lá, o DataCite) e compara campo a campo o que está no .bib com o registro oficial: primeiro autor, ano, título, periódico. O resultado vai para validation-deep.html, com um veredito por entrada.

.venv/bin/python code/deep_validate_bib.py

WARN é para ser resolvido, não ignorado. Um título truncado no Crossref (sem o subtítulo) é diferença aceitável; um sobrenome diferente ou um ano diferente é erro. Nunca se apaga o campo doi para o validador calar. No CI a validação profunda gera o relatório mas não bloqueia o build, porque serviços externos podem falhar por limite de requisições.

14.4 Checklist para uma referência nova

  1. Recupere o registro de uma fonte externa; não digite o DOI de cabeça.
  2. Confira campo a campo contra o registro recuperado.
  3. Se a referência vai sustentar uma afirmação específica, leia pelo menos o resumo recuperado.
  4. Rode a validação profunda e abra o relatório.
  5. Se não conseguiu confirmar, marque pending-verification em vez de aceitar.
  6. Ao remover uma citação do texto, confira se a chave ficou órfã no .bib.

14.5 Fontes em PDF

Os PDFs das fontes ficam em references/pdfs/, ignorados pelo Git: o repositório é público e o material tem direitos autorais. Nenhum PDF, imagem de página ou extração de texto de fonte entra no histórico, em pasta nenhuma.

NotaPontos-chave
  • Nada é escrito de memória; toda entrada nova nasce de metadados recuperados.
  • A validação rápida (sem rede) bloqueia o CI: chaves órfãs, campos faltando, padrão de chave.
  • A validação profunda confere cada entrada contra o Crossref e gera um relatório HTML.
  • O que não foi confirmado leva pending-verification; PDFs de fontes nunca entram no Git.