Ir para o conteúdo

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.