Open Knowledge Format (OKF) — Tradução Comentada

Versão 0.1 — Rascunho

Tradução e comentários por um dev brasileiro que leu a spec com café e opinião.

OKF é um formato aberto pra representar conhecimento — metadados, contexto e insight curado que orbitam dados e sistemas. Tanto humanos quanto agentes de IA leem sem dor. Foi pensado pra ser escrito por gente, gerado por agentes, trocado entre organizações e consumido pelos dois lados.

O formato é propositalmente magro: um diretório de arquivos markdown com frontmatter YAML. Sem schema registry, sem autoridade central, sem tooling obrigatório. Se você consegue dar um cat num arquivo, consegue ler OKF; se consegue dar git clone num repo, consegue distribuí-lo.

[!note] Pra que serve isso na prática? Pensa no OKF como o “README.md do seu data catalog” — mas com estrutura suficiente pra um agente LLM navegar sozinho. Seu time de dados documenta tabelas, métricas, playbooks. Um agente consegue ler isso sem SDK proprietário. Humanos conseguem ler isso sem abrir nenhuma ferramenta.

1. Motivação

O espaço de representação de conhecimento pra agentes de IA tá evoluindo rápido, e convenções incompatíveis estão brotando por todo lado. OKF parte de uma premissa simples: conhecimento é melhor quando vive em formatos acessíveis e já estabelecidos, que sejam:

Legíveis por humanos sem ferramentas especiais.
Parseáveis por agentes sem SDKs sob medida.
Diffáveis em controle de versão.
Portáveis entre ferramentas, organizações e o tempo.

O formato é minimamente opinado. Padroniza só o mínimo de convenções estruturais pra um corpus de conhecimento se tornar auto-descritivo — o resto fica com o produtor.

[!note] “Minimamente opinado” na prática Isso significa que OKF não te força a usar BigQuery, Snowflake, ou qualquer vendor. Ele define como organizar a documentação, não sobre o quê documentar. Quer catalogar suas DAGs do Airflow? Vai fundo. Quer documentar processos de negócio? Também serve.

Objetivos

Definir um formato universal em que agentes de enriquecimento escrevam.
Dizer como agentes de consumo devem ler e navegar o conteúdo.
Facilitar troca de conhecimento entre sistemas e organizações.
Padronizar os poucos campos obrigatórios que precisam existir pra que o conteúdo seja consumido com sentido.

Não-objetivos

Definir uma taxonomia fixa de tipos de concept.
Prescrever infraestrutura de armazenamento, serving ou consulta.
Substituir schemas específicos de domínio (Avro, Protobuf, OpenAPI, etc.) — OKF referencia eles, não tenta engolir.

[!note] O que isso quer dizer pra você Se você já tem um .proto descrevendo seu schema, ótimo. O OKF não substitui isso — ele complementa, dando contexto de negócio, exemplos, e links entre assets que um arquivo .proto nunca vai ter.

2. Terminologia

Knowledge Bundle — Uma coleção hierárquica e auto-contida de documentos de conhecimento. É a unidade de distribuição. Pensa nele como um “pacote” que você clona ou baixa.
Concept — Uma unidade isolada de conhecimento dentro de um bundle. Representado como um único arquivo markdown. Pode descrever um asset tangível (uma tabela, uma API), uma ideia abstrata (uma métrica, um processo de negócio), ou qualquer coisa no meio.
Concept ID — O caminho do arquivo dentro do bundle, sem o sufixo .md. Exemplo: tables/users.md tem concept ID tables/users.
Frontmatter — Bloco de metadados YAML delimitado por --- no topo de um arquivo markdown.
Body — Tudo no arquivo depois do frontmatter.
Link — Um link markdown padrão de um concept para outro, usado pra expressar relações além da hierarquia pai/filho implícita.
Citation — Um link de um concept para uma fonte externa que sustenta uma afirmação feita no body.

[!note] Analogia rápida Se você usa Obsidian, já sabe o que é a maioria dessas coisas. Bundle = vault. Concept = nota. Frontmatter = aquele YAML no topo. Link = wikilink. A diferença é que OKF formaliza regras mínimas pra interoperabilidade.

3. Estrutura do Bundle

Um bundle é uma árvore de diretórios com arquivos markdown. A estrutura de diretórios independe do domínio — produtores organizam concepts da forma que fizer sentido pro conhecimento sendo capturado.

path/to/bundle/
├── index.md                      # Opcional. Listagem do diretório (progressive disclosure).
├── log.md                        # Opcional. Histórico cronológico de atualizações.
├── <concept>.md                  # Um concept na raiz do bundle.
└── <subdiretorio>/               # Subdiretórios agrupam concepts.
    ├── index.md
    ├── <concept>.md
    └── <subdiretorio>/
        └── …

Um bundle PODE ser distribuído como:

Um repositório git (recomendado — dá histórico, atribuição, diffs).
Um tarball ou zip do diretório.
Um subdiretório dentro de um repositório maior.

[!note] Dica prática Na vida real, o mais comum vai ser um diretório knowledge/ ou docs/catalog/ dentro do seu monorepo. Nada impede de ser um repo separado, mas a conveniência de manter perto do código é grande. O agente pode olhar o schema do dbt E a documentação OKF no mesmo git clone.

3.1 Nomes de arquivo reservados

Os seguintes nomes de arquivo têm significado definido em qualquer nível da hierarquia e NÃO DEVEM ser usados para documentos de concept:

Arquivo	Finalidade
`index.md`	Listagem do diretório. Veja §6.
`log.md`	Histórico de atualizações. Veja §7.

Todos os outros .md são documentos de concept.

Tags continuam sendo cidadãs de primeira classe — veja o campo tags no frontmatter (§4.1). OKF não especifica um formato separado pra agregar documentos por tag; quem quiser uma visualização por tag pode sintetizar uma em tempo de consumo escaneando os frontmatters.

4. Documentos de Concept

Todo concept é um arquivo markdown UTF-8. Tem duas partes:

Um bloco de frontmatter YAML, delimitado por --- em linha própria no início do arquivo e um --- de fechamento em linha própria.
Um body markdown, com conteúdo livre.

4.1 Frontmatter

---
type: <Nome do tipo>               # OBRIGATÓRIO
title: <Nome de exibição opcional>
description: <Resumo em uma linha, opcional>
resource: <URI canônica do asset subjacente, opcional>
tags: [<tag>, <tag>, …]            # Opcional
timestamp: <datetime ISO 8601>     # Opcional, último update significativo
# … outros pares chave/valor definidos pelo produtor
---

Obrigatório:

type — Uma string curta identificando o tipo do concept. Consumidores usam isso pra roteamento, filtragem e apresentação. Exemplos de valores: BigQuery Table, BigQuery Dataset, API Endpoint, Metric, Playbook, Reference.
Valores de type não são registrados centralmente. Produtores DEVEM escolher valores descritivos e auto-explicativos; consumidores DEVEM tolerar tipos desconhecidos graciosamente (tipicamente tratando-os como concepts genéricos).

[!note] Isso é genial e perigoso ao mesmo tempo A decisão de não ter um registro central de tipos é libertadora — você cria type: dbt Model ou type: Kafka Topic sem pedir permissão. Mas sem governança, dois times na mesma empresa podem usar type: Table e type: BigQuery Table pro mesmo conceito. Combinem no design doc.

Recomendados (em ordem de prioridade):

title — Nome legível. Se omitido, consumidores PODEM derivar um título do nome do arquivo.
description — Uma frase única resumindo o concept. Usado por geradores de index.md, snippets de busca e previews.
resource — Uma URI que identifica univocamente o asset que o concept descreve. Ausente pra concepts que descrevem ideias abstratas.
tags — Lista YAML de strings curtas pra categorização transversal.
timestamp — Datetime ISO 8601 da última mudança significativa.

Extensões: Produtores PODEM incluir chaves adicionais. Consumidores DEVEM preservar chaves desconhecidas ao fazer round-trip e NÃO DEVEM rejeitar documentos com campos não reconhecidos.

[!note] Exemplo de extensão útil Imagine adicionar owner: time-de-dados@empresa.com ou freshness_sla: 30m no frontmatter. A spec não proíbe — e um agente esperto pode usar esses metadados extras pra decisões.

4.2 Body

O body é markdown padrão. Produtores DEVEM preferir markdown estrutural — headings, listas, tabelas, blocos de código cercados — em vez de prosa livre, já que estrutura ajuda tanto leitura humana quanto recuperação por agentes.

Não existem seções obrigatórias no body. Os seguintes headings têm significado convencional e DEVEM ser usados quando aplicável:

Heading	Finalidade
`# Schema`	Descrição estruturada das colunas/campos de um asset.
`# Examples`	Exemplos concretos de uso, geralmente em blocos de código.
`# Citations`	Fontes externas sustentando afirmações do body. Veja §8.

[!note] Por que estrutura importa pro agente? Um LLM com RAG funciona melhor quando o documento tem headings claros. Se você pede “me mostra o schema da tabela orders”, o agente consegue ir direto na seção # Schema em vez de parsear um parágrafo de 500 palavras. Markdown bem estruturado é retrieval-friendly.

4.3 Exemplo: concept ligado a um resource

---
type: BigQuery Table
title: Pedidos de Clientes
description: Uma linha por pedido completo de cliente em todos os canais.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [vendas, pedidos, receita]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Coluna        | Tipo      | Descrição                                |
|---------------|-----------|------------------------------------------|
| `order_id`    | STRING    | Identificador único global do pedido.    |
| `customer_id` | STRING    | FK para [customers](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Total do pedido em dólares.              |
| `placed_at`   | TIMESTAMP | Quando o cliente submeteu o pedido.      |

# Joins

Join com [customers](/tables/customers.md) via `customer_id`.

# Citations

[1] [Schema da tabela no BigQuery](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)

4.4 Exemplo: concept sem resource

---
type: Playbook
title: Resposta a incidente — alerta de freshness
description: Passos pra triar um alerta de freshness no pipeline de pedidos.
tags: [oncall, incidente]
timestamp: 2026-04-12T09:00:00Z
---

# Trigger

O alerta de freshness dispara quando `orders` fica mais de 30 minutos
atrás do SLA esperado. Veja a [tabela de pedidos](/tables/orders.md).

# Passos

1. Cheque o [dashboard do job de ingestão](https://example.com/dash).
2. Verifique se o source system está respondendo.
3. Se for falha do source, acione o time parceiro via Slack #dados-incidentes.
4. Se for falha interna, escale via PagerDuty.

[!note] Exemplo extra: um concept de Métrica A spec não mostra esse caso, mas funciona assim:

---
type: Metric
title: Revenue por Cliente (LTV 90d)
description: Receita acumulada por cliente nos últimos 90 dias.
tags: [finance, growth, kpi]
timestamp: 2026-06-01T10:00:00Z
---

# Definição

Soma de `total_usd` da tabela [orders](/tables/orders.md) agrupada
por `customer_id`, filtrada por `placed_at >= CURRENT_DATE - 90`.

# SQL de referência

```sql
SELECT customer_id, SUM(total_usd) AS ltv_90d
FROM `acme.sales.orders`
WHERE placed_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 90 DAY)
GROUP BY customer_id

Limitações

Não inclui reembolsos (tabela refunds ainda não ingestada).
Exclui pedidos com status cancelled.

5. Cross-linking

Concepts PODEM linkar pra outros concepts usando links markdown padrão. Duas formas são suportadas:

5.1 Links absolutos (relativos ao bundle)

Começam com /, interpretados em relação à raiz do bundle.

Veja a [tabela de clientes](/tables/customers.md) para a chave de join.

Essa é a forma recomendada porque permanece estável quando documentos são movidos dentro do seu subdiretório.

5.2 Links relativos

Caminhos relativos padrão do markdown.

Veja o [concept vizinho](./other.md).

5.3 Semântica dos links

Um link do concept A pro concept B afirma uma relação. O tipo específico da relação (pai/filho, referencia, join-com, depende-de, etc.) é transmitido pela prosa ao redor, não pelo link em si. Consumidores que constroem uma visualização de grafo tipicamente tratam todos os links como arestas direcionadas de relação não-tipada.

Consumidores DEVEM tolerar links quebrados — um link cujo alvo não existe no bundle não é malformado; pode simplesmente representar conhecimento ainda não escrito.

[!note] A elegância dos links quebrados Essa decisão é sutil mas importante. Ela permite que você escreva [tabela de refunds](/tables/refunds.md) antes mesmo de criar esse arquivo. É documentation-driven development: primeiro você referencia, depois preenche. Perfeito pra times que documentam incrementalmente.

6. Arquivos de Índice

Um index.md PODE aparecer em qualquer diretório, incluindo a raiz do bundle. Ele lista o conteúdo do diretório pra suportar progressive disclosure — permitindo que humanos ou agentes vejam o que está disponível antes de abrir documentos individuais.

Arquivos de índice não contêm frontmatter. O body usa uma ou mais seções, cada uma agrupando concepts sob um heading:

# Tabelas de Vendas

* [Pedidos](orders.md) - Uma linha por pedido completo
* [Clientes](customers.md) - Dados cadastrais de clientes

# Tabelas de Suporte

* [Tickets](tickets.md) - Chamados de suporte técnico

Entradas DEVEM incluir a description do frontmatter do concept linkado. Produtores PODEM gerar index.md automaticamente; consumidores PODEM sintetizar um on the fly quando nenhum estiver presente.

[!note] Automação do index.md Na prática, você vai querer um script que percorra o bundle e gere os index.md a partir dos campos title e description de cada concept. Algo tipo:
for f in tables/*.md; do
  [ "$(basename $f)" = "index.md" ] && continue
  title=$(grep '^title:' "$f" | sed 's/title: //')
  desc=$(grep '^description:' "$f" | sed 's/description: //')
  echo "* [$title]($(basename $f)) - $desc"
done
Crude? Sim. Funcional? Também.

7. Arquivos de Log (opcional)

Um log.md PODE aparecer em qualquer nível da hierarquia pra registrar o histórico de mudanças naquele escopo. O formato é uma lista plana de entradas agrupadas por data, mais recentes primeiro:

# Log de Atualizações

## 2026-05-22
* **Atualização**: Adicionada nova referência de tabela BigQuery para [Customer Metrics](/tables/customer-metrics.md).
* **Criação**: Estabelecido o [Playbook Dataplex](/playbooks/dataplex.md).

## 2026-05-15
* **Inicialização**: Criada estrutura de diretórios fundacional.
* **Atualização**: Adicionadas diretrizes de progressive-disclosure ao [index](/index.md) raiz.

Headings de data DEVEM usar formato ISO 8601 YYYY-MM-DD. Entradas de log são prosa; a palavra em negrito inicial (**Atualização**, **Criação**, **Deprecação**, etc.) é uma convenção, não um requisito.

[!note] Log vs Git log — quando usar qual? O log.md não substitui o git log. Ele serve pra mudanças de alto nível que um humano ou agente quer ver rapidamente: “ah, em maio adicionaram a tabela de métricas”. O git log conta a história granular dos commits. São complementares.

8. Citations

Quando o body de um concept faz afirmações baseadas em material externo, essas fontes DEVEM ser listadas sob um heading # Citations no final do documento, numeradas:

# Citations

[1] [Anúncio do dataset público BigQuery](https://cloud.google.com/blog/products/data-analytics/...)
[2] [Runbook interno de qualidade de dados](https://wiki.acme.internal/data/quality)

Links de citation PODEM ser URLs absolutas, caminhos relativos ao bundle, ou caminhos dentro de um subdiretório references/ que espelha material externo como concepts OKF de primeira classe.

[!note] Por que citations importam pra agentes Quando um LLM responde “a tabela X tem freshness SLA de 30 minutos”, uma citation permite rastrear de onde veio essa informação. Sem isso, o agente alucina com confiança. Com citation, você pode validar a fonte. É o “mostre seu trabalho” do mundo de IA.

9. Conformidade

Um bundle é conforme com OKF v0.1 se:

Todo arquivo .md não-reservado na árvore contém um bloco de frontmatter YAML parseável.
Todo bloco de frontmatter contém um campo type não-vazio.
Todo nome de arquivo reservado (index.md, log.md) segue a estrutura descrita em §6 e §7, respectivamente, quando presente.

Consumidores DEVEM tratar todas as outras restrições como orientação suave. Em particular, consumidores NÃO DEVEM rejeitar um bundle por causa de:

Campos opcionais de frontmatter ausentes.
Valores de type desconhecidos.
Chaves adicionais de frontmatter desconhecidas.
Cross-links quebrados.
Arquivos index.md ausentes.

Esse modelo de consumo permissivo é intencional: OKF foi feito pra continuar útil conforme bundles crescem, são refatorados, e são parcialmente gerados por agentes.

[!note] A regra de ouro da conformidade Basicamente: se tem frontmatter com type, é OKF válido. Ponto. Todo o resto é “nice to have”. Isso reduz dramaticamente a barreira de adoção — seu time pode começar com concepts mínimos e ir enriquecendo com o tempo.

10. Relação com outros formatos

OKF é intencionalmente próximo de vários padrões estabelecidos:

Repositórios “wiki” pra LLMs que usam markdown + frontmatter como bases de conhecimento legíveis por agentes.
Ferramentas de conhecimento pessoal como Obsidian e Notion, que usam markdown hierárquico com cross-links.
Abordagens “metadata as code” que armazenam metadados de catálogo junto do código-fonte em vez de num registro separado.

OKF difere principalmente por ser especificado — fixando o pequeno conjunto de regras necessárias pra interoperabilidade sem ditar ferramentas.

[!note] Comparação direta
Formato/Ferramenta Legível por humano? Legível por agente? Especificado? Portável?
Obsidian vault ✅ Mais ou menos ❌ ❌ (plugins)
Notion export ✅ ❌ (JSON bagunçado) ❌ ❌
DataHub/OpenMetadata ❌ (precisa UI) ✅ (API) ✅ Parcial
OKF ✅ ✅ ✅ ✅
OKF ocupa um nicho específico: máxima portabilidade com mínima cerimônia.

Formato/Ferramenta	Legível por humano?	Legível por agente?	Especificado?	Portável?
Obsidian vault	✅	Mais ou menos	❌	❌ (plugins)
Notion export	✅	❌ (JSON bagunçado)	❌	❌
DataHub/OpenMetadata	❌ (precisa UI)	✅ (API)	✅	Parcial
OKF	✅	✅	✅	✅

11. Versionamento

Este documento especifica OKF versão 0.1. Revisões futuras seguirão o formato <major>.<minor>:

Um bump de versão minor introduz adições compatíveis com versões anteriores (novos campos opcionais, novos headings convencionais de seção).
Um bump de versão major pode introduzir breaking changes (renomear campos obrigatórios, mudar nomes de arquivos reservados).

Bundles PODEM declarar a versão OKF que targetam incluindo okf_version: "0.1" no frontmatter do index.md na raiz do bundle (o único lugar onde frontmatter é permitido num index.md). Consumidores que não entendem a versão declarada DEVEM tentar consumo best-effort em vez de recusar o bundle.

Apêndice A — Bundle de exemplo mínimo

meu_bundle/
├── index.md
├── datasets/
│   ├── index.md
│   └── sales.md
└── tables/
    ├── index.md
    ├── orders.md
    └── customers.md

datasets/sales.md:

---
type: BigQuery Dataset
title: Sales
description: Todas as tabelas de vendas do negócio de varejo.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
tags: [vendas]
timestamp: 2026-05-28T00:00:00Z
---

O dataset de vendas contém tabelas transacionais, incluindo
[orders](/tables/orders.md) e [customers](/tables/customers.md).

tables/orders.md:

---
type: BigQuery Table
title: Orders
description: Uma linha por pedido completo de cliente.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [vendas, pedidos]
timestamp: 2026-05-28T00:00:00Z
---

# Schema

| Coluna        | Tipo      | Descrição                    |
|---------------|-----------|------------------------------|
| `order_id`    | STRING    | Identificador único.         |
| `customer_id` | STRING    | FK para [customers](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Total do pedido em USD.      |

Faz parte do [dataset de vendas](/datasets/sales.md).

Apêndice B — Guia rápido de adoção (extra)

Isso não está na spec original, mas vale a pena. Um caminho prático pra adotar OKF no seu time:

Passo 1: Escolha seu escopo

Não tente documentar tudo de uma vez. Comece com as 10 tabelas mais acessadas, ou os 5 playbooks de oncall que vivem perdidos no Confluence.

Passo 2: Crie a estrutura mínima

mkdir -p knowledge/{tables,metrics,playbooks}

Passo 3: Escreva seu primeiro concept

---
type: BigQuery Table
title: users
description: Tabela mestra de usuários da plataforma.
resource: bigquery://projeto.dataset.users
tags: [core, identity]
timestamp: 2026-06-01T00:00:00Z
---

# Schema

| Coluna     | Tipo      | Descrição               |
|------------|-----------|-------------------------|
| `user_id`  | STRING    | UUID do usuário.        |
| `email`    | STRING    | Email principal.        |
| `created_at` | TIMESTAMP | Data de criação da conta. |

# Notas

- Dados de PII: `email` é mascarado em ambientes non-prod.
- Particionada por `created_at` (daily).

Passo 4: Automatize

CI que valida se todo .md tem frontmatter com type.
Script que regenera index.md a cada PR.
(Opcional) Agente que enriquece novos concepts com schema real via API do BigQuery/Snowflake.

Passo 5: Distribua

Git push. Pronto. Seu bundle é um repo (ou subdiretório). Outros times clonam e têm acesso.

Notas do tradutor

Algumas observações sobre escolhas de tradução:

Termos mantidos em inglês: bundle, frontmatter, concept, cross-link, body, progressive disclosure, round-trip. São termos técnicos sem tradução consagrada em PT-BR que soaria natural entre devs.
MUST/SHOULD/MAY: Segui a mesma lógica da RFC 2119. Traduzi como DEVE/NÃO DEVE (must), DEVERIA (should) e PODE (may), mas sem o peso burocrático.
Tom: A spec original é neutra e técnica. Adicionei opinião e contexto onde achei que ajudaria um dev brasileiro a entender não só o quê mas por quê. Se discordar de algum comentário meu, leia a spec original em inglês — ela é a fonte de verdade.
Exemplos extras: Adicionei o exemplo de Métrica (§4.4 nota), o script de geração de index (§6 nota), e o Apêndice B inteiro. Nenhum faz parte da spec oficial — são contribuições práticas.

Fonte original: GoogleCloudPlatform/knowledge-catalog — okf/SPEC.md

Tradução: Junho 2026. OKF v0.1 Draft.