O que Quebrou Quando Transformamos Dados Abertos do Governo em Evidências Chamáveis por Agentes

Os dados abertos do governo parecem enganosamente fáceis à distância.

Encontre um endpoint. Faça uma solicitação. Normalize o JSON. Envie uma API.

Isso é suficiente para uma demonstração. Não é suficiente para um sistema de produção que precisa responder a uma pergunta consequente no próximo mês, depois que o editor mudar um campo, limitar uma resposta, mover um endpoint ou retornar uma página vazia que parece exatamente como "não há registros."

Temos construído o CivicDataForge em torno de uma pergunta:

O que precisa existir entre um editor oficial do governo e um sistema de software—ou um agente de IA—antes que o resultado mereça ser chamado de evidência?

Este post é a resposta prática que alcançamos até agora. Não é uma afirmação de que os dados do governo podem ser tornados perfeitamente limpos. É um relato dos modos de falha que encontramos, da arquitetura que adotamos e dos limites que nos recusamos a apagar.

1. Uma resposta HTTP bem-sucedida não é um conjunto de dados completo

O primeiro modo de falha sério é a paginação.

As plataformas de dados do governo frequentemente impõem um limite máximo de registros. Uma resposta pode ser um JSON válido, ter um status 200 e ainda assim representar apenas a primeira página.

Os serviços de recursos do ArcGIS expõem controles como resultOffset e resultRecordCount, e podem sinalizar que um limite de transferência foi excedido. Os conjuntos de dados do Socrata também suportam paginação e controles de consulta. Se um coletor ignorar esses contratos, "a fonte retornou 1.000 linhas" pode silenciosamente se tornar "a jurisdição tem 1.000 registros."

Essas não são a mesma declaração.

Nossa regra de coleta se tornou:

1. Descubra o limite de página do editor.
2. Solicite cada página em uma ordem estável.
3. Acompanhe a contagem de páginas, a contagem de linhas observadas e os totais relatados pela fonte, quando disponíveis.
4. Rejeite uma linha de base de monitoramento quando a consulta selecionada estiver limitada, parcial ou estruturalmente inconsistente.
5. Vincule o escopo concluído a um recibo.

A decisão de produto importante é o passo quatro. Uma página parcial é útil para exploração, mas não pode provar que um registro desapareceu entre duas execuções.

Referências oficiais:

• Camada de serviço de consulta de recurso do ArcGIS
• Documentação de consulta do Socrata

2. "Sem correspondência" não é uma conclusão legal negativa

Suponha que uma busca de endereço não retorne nenhum registro de permissão.

É tentador retornar NOT_PERMITTED ou ILLEGAL. Isso geralmente é mais forte do que a evidência.

O editor selecionado pode não cobrir todo o regime legal. O endereço pode estar formatado de maneira diferente. Uma permissão local pode existir em outro sistema. A fonte pode estar desatualizada. A consulta pode estar incompleta. Ou pode simplesmente não haver correspondência publicada.

Usamos um vocabulário de decisão explícito e que falha de forma fechada:

EVIDENCE_FOUND
NO_PUBLISHED_MATCH
REVIEW_REQUIRED
SOURCE_UNAVAILABLE
SCOPE_INCOMPLETE

Esse vocabulário é deliberadamente menos dramático do que um resultado binário de sim/não. Esse é o ponto.

Uma API não deve fabricar certeza porque um consumidor deseja um Booleano. Se um fluxo de trabalho a montante requer um Booleano, o cliente deve possuir a política que mapeia os estados de evidência para uma ação—e deve preservar o estado original para revisão.

3. A proveniência deve sobreviver à normalização

A normalização é necessária. É também onde a evidência pode perder sua identidade.

Normalizamos nomes, endereços, datas, identificadores e status específicos da fonte, mas mantemos linhagens suficientes para responder:

• Qual autoridade publicou este registro?
• De qual endpoint, arquivo ou conjunto de dados ele veio?
• Que consulta e escopo o produziram?
• Quando foi recuperado?
• Como o editor chamou este campo?
• Qual transformação produziu o valor normalizado?
• O registro e a decisão podem ser impressos novamente?

Um envelope de evidência mínima se parece aproximadamente com isto:

{
  "source": {
    "publisher": "autoridade emissora",
    "url": "https://official.example/dataset",
    "retrieved_at": "2026-08-24T12:00:00Z"
  },
  "scope": {
    "query": "consulta de fonte delimitada",
    "complete": true
  },
  "record": {
    "source_id": "chave-de-propriedade-do-editor",
    "normalized_identifier": "identificador-estável",
    "record_hash": "sha256:..."
  },
  "decision": {
    "state": "EVIDENCE_FOUND",
    "receipt_hash": "sha256:..."
  }
}

Os campos exatos variam de acordo com a fonte. O invariante é que o resultado normalizado não rompe o caminho de volta para o registro oficial.

4. A saúde da fonte e a frescura dos dados são dimensões diferentes

Uma fonte pode ser acessível e desatualizada.

Ela pode ter um esquema estável e retornar dados incompletos. Pode publicar um arquivo recente cujas datas internas são antigas. Pode mudar o conteúdo sem mudar uma URL. Pode mudar um esquema sem falhar em uma solicitação.

Então, um sinal verde não é suficiente.

Monitoramos dimensões independentes:

• disponibilidade
• compatibilidade de esquema
• comportamento da contagem de registros
• integridade da data da fonte
• frescura, quando o editor expõe um sinal de frescura defensável
• impressão digital do conteúdo
• compatibilidade de contrato

Quando a frescura não pode ser medida, dizemos freshness_not_measured. Não permitimos que uma verificação de disponibilidade implique que os dados estão atuais.

Essa distinção é importante porque um monitor de produção deve ser capaz