FAQ — Open Knowledge Format (OKF)

Perguntas frequentes sobre o OKF, respondidas com honestidade e sem enrolação.

O que é OKF?

OKF (Open Knowledge Format) é uma spec aberta pra representar conhecimento — metadados, contexto e insights curados — de forma que humanos leiam sem ferramentas e agentes de IA consumam sem SDKs proprietários.

Na prática: uma pasta de arquivos Markdown com YAML frontmatter. Cada arquivo é um “conceito” (tabela, métrica, playbook, API). Estrutura hierárquica, versionável com git, simples ao ponto de um cat arquivo.md já te mostrar tudo.

As regras obrigatórias cabem em três linhas:

1. Todo .md (exceto index.md e log.md) precisa de frontmatter YAML parseável
2. Todo frontmatter precisa ter campo type não-vazio
3. Arquivos reservados (index.md, log.md) seguem estrutura definida

Fora isso? Liberdade total. Organiza os conceitos como quiser.

Quem criou o OKF?

O Google Cloud criou, publicou dentro do repo GoogleCloudPlatform/knowledge-catalog no GitHub, sob licença Apache 2.0.

Nasceu no contexto do Knowledge Catalog (antigo Dataplex) — plataforma de catálogo de dados com IA do Google Cloud. Mas a spec é vendor-neutral: não exige Google Cloud, não tem dependência de produto, qualquer organização adota.

Versão atual: 0.1 (Draft) — fase inicial, mas já funcional e utilizável.

Precisa de SDK?

Não. Essa é uma das filosofias fundadoras do OKF.

A spec é explícita: “If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.”

Pra produzir OKF: um editor de texto. Pra consumir OKF: saber ler Markdown. Pra validar: checar 3 regras simples (frontmatter YAML parseável, campo type presente, arquivos reservados com estrutura certa).

Existem ferramentas que facilitam (validadores, geradores de index.md, enrichment agents). Mas nenhuma é requisito. Esse é o ponto.

Qual a diferença pro AGENTS.md?

Propósitos bem diferentes:

AGENTS.md diz ao agente como se comportar. OKF diz ao agente o que existe no mundo — quais tabelas, métricas, APIs, playbooks, processos.

São complementares: seu AGENTS.md pode instruir o agente a “consultar o bundle OKF em /knowledge” pra entender o domínio.

E pro Obsidian?

Obsidian e OKF compartilham DNA — ambos usam Markdown hierárquico com frontmatter e cross-links. Mas o propósito diverge:

Obsidian é ferramenta de personal knowledge management. Notas pessoais, second brain, zettelkasten. Formato proprietário de links ([[wikilinks]]), plugins, graph view — tudo voltado pra um humano individual.

OKF é spec de intercâmbio. O objetivo: um bundle produzido pela equipe A ser consumido pela equipe B (ou agente C) sem perda de informação. É a diferença entre suas anotações pessoais e um manual técnico publicado.

Na prática:

• Links no OKF são Markdown padrão ([texto](caminho.md)), não wikilinks
• OKF exige campos obrigatórios no frontmatter (type é mandatório)
• OKF tem index.md e log.md como arquivos reservados com estrutura definida
• OKF é pensado pra agentes de IA consumirem programaticamente

Dá pra editar bundles OKF no Obsidian sem problema nenhum. Mas OKF não é Obsidian — é formato portável que roda em qualquer lugar.

E pro DESIGN.md?

DESIGN.md é tipicamente um documento único descrevendo decisões arquiteturais, design system, ou design de um componente. É um documento, não um formato.

OKF é formato estruturado com regras de conformidade, hierarquia de conceitos, cross-links, e suporte a múltiplos tipos de conhecimento.

Se o DESIGN.md virasse OKF, seria um conceito dentro de um bundle — talvez type: Architecture Decision ou type: Design Document. OKF é o container; DESIGN.md é algo que vive dentro dele.

Posso usar com Claude/GPT/Gemini?

Sim, todos. Esse é o ponto inteiro.

OKF é Markdown + YAML. Qualquer LLM que leia texto (todos, portanto) consome bundles OKF nativamente. Zero lock-in de provider.

Na prática:

• Claude/Cursor: Jogue o bundle no contexto do projeto. O agente entende quais tabelas existem, como se relacionam, quais métricas importam.
• GPT/ChatGPT: Upload dos .md ou ZIP do bundle. O modelo navega pelos conceitos.
• Gemini: Integração natural via Knowledge Catalog, mas funciona standalone também.
• Qualquer agente MCP: Bundle pode ser servido como recurso via MCP.

A spec foi feita pra ser “parseable by agents without bespoke SDKs” — agnosticismo de modelo é requisito fundacional.

Como validar um bundle?

Validar OKF v0.1 = checar 3 regras.

As 3 regras de conformidade

1. Todo .md não-reservado tem frontmatter YAML parseável — bloco entre --- precisa ser YAML válido
2. Todo frontmatter tem campo type não-vazio — string descrevendo o tipo do conceito
3. Arquivos reservados seguem a estrutura — index.md é listagem; log.md é histórico cronológico

Na prática

Manual (funciona sempre):

# Verifica se todos os .md têm frontmatter com type
for f in $(find ./bundle -name "*.md" ! -name "index.md" ! -name "log.md"); do
  head -50 "$f" | grep -q "^type:" || echo "FAIL: $f sem type"
done

Validador online (em breve): Estamos construindo um validador client-side em okf.md — aceita upload de ZIP/folder, parseia YAML, gera relatório com badge de conformidade.

Programaticamente: Qualquer parser YAML + 3 checks. Sem mistério.

OKF vai substituir catálogos de dados?

Não. A spec é explícita nos non-goals.

OKF não substitui Knowledge Catalog, Datahub, Atlan, Amundsen. Ele complementa:

• Catálogos são plataformas com UI, API, governance, lineage, permissões
• OKF é formato de exportação/troca de conhecimento

O catálogo de dados é o sistema de record. O bundle OKF é o snapshot portável — que você versiona no git, compartilha com outro time, ou injeta no contexto de um agente.

Catálogo pode exportar em OKF. Agente pode consumir OKF gerado pelo catálogo. Camadas diferentes.

É só pra BigQuery?

De jeito nenhum. Os exemplos usam BigQuery porque o OKF nasceu no ecossistema Google Cloud, mas o formato é completamente agnóstico.

O campo type é livre — define seus próprios tipos:

type: PostgreSQL Table       # funciona
type: API Endpoint           # funciona
type: Metric                 # funciona
type: Runbook                # funciona
type: Business Process       # funciona
type: Qualquer Coisa         # funciona também

O campo resource (opcional) é URI genérico — aponta pra dashboard Grafana, endpoint REST, tabela Snowflake, página Confluence, o que for.

OKF serve pra documentar qualquer conhecimento organizacional: dados, APIs, processos, playbooks, métricas, decisões. Se é algo que humano ou agente precisa saber, cabe num bundle.

Como contribuir com a spec?

A spec vive no GitHub, aberta:

1. Repo oficial: GoogleCloudPlatform/knowledge-catalog
2. Issues: Sugestões, dúvidas, propostas de mudança
3. Pull Requests: Texto, exemplos, ferramentas nos diretórios samples/ e toolbox/
4. Licença: Apache 2.0 — use, modifique, distribua

O repo aceita PRs e tem CONTRIBUTING.md. A spec tá em v0.1 Draft — momento ideal pra influenciar direções futuras.

Pra comunidade brasileira, estamos construindo recursos em português no okf.ia.br — docs traduzidos, guias práticos, exemplos pro mercado BR.

Precisa de backend?

Não. OKF é estático por natureza.

Bundle = pasta de .md. Pra servir: qualquer file server estático. Pra validar: roda client-side (JS no browser). Pra versionar: git. Pra distribuir: ZIP ou clone.

Zero banco de dados, zero API, zero infra dedicada.

Se você quiser construir algo em cima do OKF — catálogo com busca, enrichment pipeline, UI de navegação — aí pode precisar de backend. Mas o formato em si? Puro filesystem.

Funciona com git?

Perfeitamente. Git é o método de distribuição recomendado pela spec.

Por quê:

• Histórico: Cada mudança num conceito fica rastreável (quem, quando, o quê)
• Diffs: Markdown é texto puro — diffs legíveis e úteis
• Branches: Propõe mudanças no conhecimento via PR/MR
• Colaboração: Várias pessoas (ou agentes) editam ao mesmo tempo
• Distribuição: git clone e pronto

O log.md da spec é até redundante se você usa git (commits fazem o mesmo trabalho). Mas ele existe pra quando o bundle é distribuído sem VCS (ZIP, tarball).

Git + OKF = conhecimento organizacional com as mesmas práticas que a gente já aplica em código.

Qual o futuro do OKF?

⚠️ Opinião pessoal — análise especulativa, não fatos confirmados.

OKF tá em v0.1 Draft — o Google Cloud testando as águas. Com base no que já existe e no momentum do espaço:

Curto prazo (2026):

• Adoção no ecossistema Knowledge Catalog como formato de export/import
• Tooling oficial (CLI, validador, GitHub Actions)
• Integrações MCP pra servir bundles como recursos pra agentes

Médio prazo (2027+):

• Outros cloud providers reconhecem o formato (ou criam competidores compatíveis)
• Enrichment agents gerando bundles automaticamente de fontes diversas
• Marketplace de bundles públicos (tipo npm, mas pra conhecimento)

Minha aposta: OKF tem potencial pra ser o “Markdown do conhecimento organizacional” — assim como Markdown venceu pra documentação por ser simples e universal, OKF pode vencer pra representação de conhecimento pelo mesmo motivo. O timing é bom: agentes explodindo, todo mundo precisa de contexto estruturado, mercado fragmentado em soluções proprietárias.

O risco? Google não investir em adoção cross-cloud e virar “mais um formato Google”. Mas licença Apache 2.0 e design vendor-neutral jogam a favor.

Recomendação: experimenta agora. Custo zero (é Markdown!) e o upside de estar preparado quando o ecossistema amadurecer é alto.

Mais perguntas?

• 📖 Spec oficial: github.com/GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md
• 🇧🇷 Docs em português: okf.ia.br
• 🌐 Site de referência: okf.md
• 🛠️ Validador: em breve no site