Navegação de Dados¶
O sistema de IDs permite navegar bidirecionalmente entre o cliente que consome um dado e a fonte original de onde ele veio.
Customer → Source¶
Partindo do cliente, é possível rastrear até a fonte original de cada dado:
Customer
└── consumes → SVC-BR-001 (serviço)
└── exposes → API-BR-001 (api)
└── endpoint → EP-BR-001-005
└── returns → DATA-BR-001 (dataset)
└── field → FIELD-BR-001-003
└── derived_from → PIPE-BR-001
└── source → SRC-BR-001 (IBGE)
Source → Customer¶
Partindo da fonte, é possível identificar quem consome cada dado:
SRC-BR-001 (IBGE)
└── ingested_by → PIPE-BR-001
└── produces → DATA-BR-001
└── exposed_by → API-BR-001
└── part_of → SVC-BR-001
└── consumed_by → Customer
RECOMMENDATION — MVP vs Futuro
Este grafo é mantido inicialmente como referências em campos YAML dentro dos arquivos dataset.yaml, service.yaml e source.yaml.
Em escala, pode ser representado em um graph database ou service catalog. Isso não é requisito técnico do MVP.
Implementação no MVP — Referências em YAML¶
Os arquivos YAML fazem o papel de "edges" no grafo durante os estágios iniciais:
# DATA-BR-001.yaml
dataset:
id: DATA-BR-001
name: Municípios Brasileiros Normalizados
source: SRC-BR-001 # ← link para IBGE
exposed_by: API-BR-001 # ← link para a API
transformed_by: PIPE-BR-001 # ← link para o pipeline
# API-BR-001/service.yaml
service:
id: SVC-BR-001
api: API-BR-001
data:
datasets:
- DATA-BR-001
sources:
- SRC-BR-001
Perguntas que o Sistema Deve Responder¶
Com o grafo de IDs corretamente preenchido, qualquer pessoa deve conseguir responder:
| Pergunta | Ponto de Partida | Direção |
|---|---|---|
| De onde veio esse campo da API? | FIELD-BR-001-003 |
→ PIPE → SRC |
| Qual API expõe este dataset? | DATA-BR-001 |
→ exposed_by → API |
| Quais clientes são afetados se esta fonte falhar? | SRC-BR-001 |
→ PIPE → DATA → API → SVC → Customer |
| Quais dados este pipeline produz? | PIPE-BR-001 |
→ produces → DATA |
| Quais fontes esta API depende? | API-BR-001 |
→ service.yaml → sources |
Data Provenance — Rastreabilidade de Transformações¶
Além da navegação estrutural entre IDs, o sistema de provenance responde perguntas sobre transformações específicas:
| Pergunta | Onde encontrar |
|---|---|
| De onde veio esse dado? | dataset.yaml → campo source |
| Quando foi coletado? | lineage/lineage.md → timestamp da ingestão |
| Qual era a versão da fonte? | sources/SRC-BR-001.yaml → campo last_verified |
| O que foi transformado? | pipelines/ → log de transformações |
| Quem realizou a transformação? | Git history do data-{nome} |
| Qual pipeline foi usado? | dataset.yaml → campo transformed_by |
| Qual versão da API expôs o resultado? | CHANGELOG.md do api-{nome} |
Diagrama de Fluxo — Lineage Completo¶
flowchart LR
SRC["SRC-BR-001<br/>(IBGE)"]
PIPE["PIPE-BR-001<br/>(pipeline)"]
DATA["DATA-BR-001<br/>(dataset)"]
API["API-BR-001<br/>(openapi.yaml)"]
SVC["SVC-BR-001<br/>(service)"]
CLIENT["Customer"]
SRC -->|ingested_by| PIPE
PIPE -->|produces| DATA
DATA -->|exposed_by| API
API -->|part_of| SVC
SVC -->|consumed_by| CLIENT
Próximo passo¶
Com a navegação de dados definida, consulte as Camadas Documentais para ver como os diferentes tipos de documento se organizam por escopo e audiência.