Proposta: camada OCDS (tabular) sobre as views de compras públicas

[yolile]

Motivação

O MVP do Colibri prevê disponibilizar os dados no formato OCDS. O Open Contracting Data Standard (OCDS) é o padrão aberto de dados de contratações públicas adotado por mais de 50 governos; padronizar nossas tabelas ao OCDS permite que pesquisadores reutilizem metodologias, indicadores e ferramentas já existentes (ex.: análises de competição, red flags, comparação de preços) sem precisar remapear o schema específico do ComprasGOV.

Embora o OCDS proponha JSON, para cálculo e queries as tabelas são mais práticas — por isso esta proposta prioriza uma camada OCDS tabular, deixando o JSON como opção sob demanda (ver "Trabalho futuro").

Proposta (v1): camada OCDS tabular em dbt

Criar um novo domínio dbt ocds/ que reaproveita as views existentes (mrt_pncp_comprasgov_compras, _itens, _resultados) e as reorganiza em tabelas com nomes e estrutura OCDS, seguindo a serialização multi-tabela do padrão (arrays viram tabelas ligadas por ocid + ids locais — a mesma convenção do Flatten Tool, o que facilita um futuro export para JSON).

Mapeamento das entidades ComprasGOV → OCDS (a v1 cobre tender e award):

Entidade ComprasGOV	Objeto OCDS	Tabela proposta
compra (mrt_pncp_comprasgov_compras)	contracting process + tender + buyer	mrt_ocds__releases, mrt_ocds__tender
item (mrt_pncp_comprasgov_itens)	tender/items	mrt_ocds__tender_items
resultado (mrt_pncp_comprasgov_resultados)	awards (+ suppliers, items)	mrt_ocds__awards, mrt_ocds__awards_suppliers
órgão/unidade + fornecedores	parties (buyer/supplier, com identifier CNPJ)	mrt_ocds__parties

Notas de mapeamento:

• Campos-chave: valor_total_estimado/valor_total_homologado → tender.value/award.value; datas de proposta → tenderPeriod; modalidade/modo_disputa → procurementMethod/procurementMethodDetails; situacao_compra → tender.status; classificação de item (CATMAT/NCM) → item.classification.
• ocid: o padrão exige um prefixo registrado por publicador. Como o ComprasGOV/PNCP já tem prefixo OCDS registrado, reutilizá-lo mantém os ocid consistentes com o dado federal (alternativa: registrar prefixo próprio do Colibri). Ponto em aberto.
• Nomes de campos em inglês canônico OCDS (interoperabilidade com ferramentas), com descrições em Português no _ocds__models.yml. Versão alvo: OCDS 1.1.
• O TB já possui um mapeamento completo do compras.gov que podemos reutilizar.

Flexibilidade multi-fonte (esquema conformado)

Para o Colibri ir agregando outras fontes de compras públicas com o tempo, o desenho é uma camada conformada (source-agnostic):

• intermediate/ocds/int_ocds__<fonte>__<objeto>.sql: cada fonte mapeia suas marts para as mesmas colunas canônicas OCDS.
• marts/ocds/mrt_ocds__<objeto>.sql: UNION ALL de todas as fontes conformadas, com uma coluna sistema_origem e ids namespaced por fonte para evitar colisões.

Assim, adicionar uma nova fonte = escrever apenas seus int_ocds__<fonte>__* conformes; as marts finais e os consumidores (queries, export) não mudam.

Trabalho futuro (em aberto): export para OCDS JSON (seguinte sprint)

O caso de uso de JSON ainda é pouco claro; documentamos as opções para decidir depois:

• A — CLI local sob demanda: colibri ocds export --fonte ... --de <data> --ate <data>, lendo as views OCDS filtradas por período e usando bibliotecas maduras (ocdskit / OpenDataServices flatten-tool unflatten) para gerar release/record packages. Custo zero de storage; o usuário paga só o próprio cômputo.
• B — Pré-gerar no bucket: mantenedores geram JSON periodicamente em R2 para download direto. Adiciona custo de storage (JSON é volumoso) e de manutenção.
• Como as tabelas são enormes, qualquer export precisa ser filtrado (ex.: por intervalo de tempo).
• Decisão adiada até haver um caso de uso concreto.

Prós / Contras da abordagem tabular-em-dbt

• Prós: segue o padrão atual do projeto (SQL/dbt, sem novo runtime); consultável direto no lakehouse; views não custam storage extra; base pronta para o export JSON reutilizar.
• Contras / limitações: a v1 cobre só tender + award + items (o Colibri ainda não tem dados de planning/contract/implementation); mapear OCDS fielmente exige decisões de negócio (ocid, códigos de modalidade → codelists OCDS) que precisam de revisão.
• Alternativas descartadas para v1: transformação em Python (quebra o padrão SQL-first, duplica lógica); gerar JSON direto sem camada tabular (pior para o caso de uso de análise).

Perguntas para o time

1. Reutilizar o prefixo ocid do ComprasGOV/PNCP ou registrar um do Colibri?
2. Há demanda real por JSON OCDS (opção A vs B), ou o formato tabular já cobre os casos de uso?

@heitorgama @LarrissaSilva