# ADR-018 — Dados Abertos como capacidade de primeira classe

| Campo | Valor |
|---|---|
| **Status** | Aceito (2026-10-20) |
| **Data** | 2026-10-14 |
| **Plano de origem** | `wiki/plan/17-dados-abertos-lgpd-governanca.md` |
| **Relacionadas** | ADR-016, ADR-017, ADR-015, ADR-019 |

## Contexto

O sistema é um CMS governamental **focado em publicações e dados abertos**. Hoje o plano cobre
conteúdo editorial e busca, mas **não** trata "dados abertos" como capacidade: catálogo de
conjuntos de dados, metadados padronizados, exportação legível por máquina, licença aberta,
versionamento e API. Sem isso, "transparência" fica só no HTML.

## Decisão

- **Conjunto de dados (dataset) é entidade de domínio** (módulo próprio), não um anexo qualquer:
  título, descrição, periodicidade, última atualização, responsável, licença, recursos (arquivos).
- **Metadados padronizados**: **DCAT/INDA (gov.br)** + `schema.org/Dataset` (JSON-LD) para SEO.
- **Exportação legível por máquina**: **CSV, JSON, XML** por recurso; URLs estáveis e
  versionadas; download em massa; checksum por recurso.
- **Licença aberta por padrão**: **CC-BY 4.0** (ou ODbL quando cabível), com atribuição; a
  licença é **dado** do dataset (editável), nunca texto solto na view.
- **API pública** para datasets (JSON), versionada, paginada, com `ETag` e rate-limit
  (ver ADR-021, se aplicável) — reaproveita `Search`/`Seo`/`Media`.
- **CORS aberto, sem credenciais** (`security.open-cors`, decisão UPDATE_INFRA I5): a API é
  dado público sem PII, então `GET/HEAD/OPTIONS` respondem `Access-Control-Allow-Origin: *`,
  o preflight `OPTIONS` responde **204** e `ETag`/`X-Checksum-Sha256` são expostos
  (`Access-Control-Expose-Headers`) para o consumidor browser aproveitar o 304. `*` +
  credenciais é proibido; o resto da plataforma (`/cms`, portal, exports) continua
  same-origin. O CORS é declarado **na rota**, nunca global (`config/cors.php` vazio).
- **Catálogo** `/dados-abertos` (portal) e gestão no CMS; **JSONB** para metadados extensíveis
  (ADR-017); **sem** portal externo (nada de CKAN) — nativo.
- **Proveniência/atualização**: `atualizado_em`, `frequencia`, `origem`, `versao` — dado, não código.

## Justificativa (alternativas descartadas)

- **CKAN / portal externo** — descartada: dependência pesada e infra extra; o domínio cabe no V7.
- **Só publicar PDFs/HTML** — descartada: não é "dado aberto" (não é legível por máquina).
- **Metadados em texto livre** — descartada: quebra interoperabilidade (DCAT/INDA).

## Consequências

**Positivas**
- Transparência real (dados reutilizáveis), SEO (`Dataset`), interoperabilidade gov.br.
- Reaproveita os services existentes; nada de infraestrutura nova.

**Custos / negativas**
- Exige governança editorial dos datasets (licença, periodicidade, qualidade).
- Exportações precisam de jobs (fila) e cache para volume.

## Exemplo mínimo (comparativo)

```php
// ❌ "Dados abertos" como link para um PDF no conteúdo
$noticia->corpo = [['tipo' => 'link', 'href' => '/arquivos/dados.pdf']];

// ✅ Dataset como entidade + export legível por máquina + metadados
// modules/.../DadosAbertos: Dataset(titulo, licenca='CC-BY-4.0', frequencia='mensal')
// recurso: /dados-abertos/{slug}/recurso/{id}.csv  (ETag, checksum, versão)
// JSON-LD: { "@type": "Dataset", "license": "https://creativecommons.org/licenses/by/4.0/" }
```

## Verificação

- Catálogo lista datasets com metadados DCAT e `schema.org/Dataset`.
- Cada recurso baixa em CSV/JSON/XML com URL estável, `ETag` e checksum.
- Licença (CC-BY) visível e correta; atribuição presente.
- API pública paginada/versionada responde sem expor dados pessoais (ADR-019).

## Referências

- INDA / DCAT (gov.br); `schema.org/Dataset`; `wiki/plan/17-dados-abertos-lgpd-governanca.md`.