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?

Sam McVeety e Amir Hormati (Tech Leads, Data Analytics Engineering, Google Cloud) projetaram e anunciaram o OKF em 12 de junho de 2026 via Google Cloud Blog.

Publicado sob Apache 2.0 no repositório GoogleCloudPlatform/knowledge-catalog.

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 funcional e utilizável.

O que é o pattern “LLM Wiki”?

OKF formaliza um pattern que reaparece sob diferentes nomes: dar a agentes de IA uma biblioteca compartilhada em Markdown que fica mais útil com o tempo.

Andrej Karpathy articulou a ideia com clareza no seu LLM Wiki gist: “LLMs don’t get bored, don’t forget to update a cross-reference, and can touch 15 files in one pass.” A burocracia que faz humanos abandonarem wikis pessoais é exatamente o que LLMs fazem bem.

O mesmo pattern aparece como vaults Obsidian conectados a coding agents, a família de arquivos AGENTS.md / CLAUDE.md, repos cheios de index.md e log.md que agentes consultam antes de agir, e repositórios “metadata as code” dentro de times de dados.

O problema: cada instância é artesanal. O wiki do Karpathy e o wiki do seu time podem parecer iguais (markdown, frontmatter, cross-links), mas nenhum foi desenhado para interoperar com outro. Não existe acordo sobre quais campos todo documento deveria ter.

OKF é a camada de interoperabilidade que faltava. Define o set mínimo de convenções pra que wikis de diferentes produtores sejam consumidos por diferentes agentes sem tradução.

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): Temos um validador client-side em /validador — 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.

OKF vs llms.txt vs schema.org?

Três formatos, três audiências, três propósitos. Não competem — se empilham.

Na prática: schema.org é pro Google te entender. llms.txt é pro ChatGPT te encontrar. OKF é pro seu agente saber o que sua org sabe.

Faz os três. Não são excludentes. São camadas de uma mesma stack de visibilidade.

Posso vender bundles OKF?

Não há impeditivo técnico. A licença é Apache 2.0, o formato é aberto, o conteúdo é seu.

Quem já poderia fazer isso amanhã:

• Advogados empacotando jurisprudência curada
• SEOs vendendo bundles de keyword research estruturados
• Data teams entregando dicionários de dados como produto
• Consultores vendendo playbooks operacionais

O problema hoje: falta infraestrutura de distribuição. Não existe um “npm de bundles OKF” — sem registry, sem billing, sem discovery padronizado.

Então por enquanto, bundle OKF é como qualquer digital asset: empacota num ZIP, vende no Gumroad, entrega via git privado. Funciona, mas é artesanal.

A oportunidade tá aí pra quem quiser construir o marketplace.

Como agentes descobrem meu OKF?

Não existe mecanismo oficial de discovery. A spec não define como um agente externo encontra seu bundle — ela define o formato, não a distribuição.

Caminhos prováveis:

1. Via llms.txt — Incluir link pro bundle no seu llms.txt. É o mais natural: “aqui tá meu conhecimento estruturado”
2. Via auth.md — Padrão emergente pra agentes autenticados descobrirem recursos
3. Via .well-known/okf — Convenção que pode surgir (tipo .well-known/security.txt)
4. Via MCP server card — Se seu agente usa MCP, declarar o bundle como resource disponível
5. Hardcoded — Seu AGENTS.md manda o agente olhar /knowledge/bundle/

Pra agentes internos (seu Cursor, seu Claude Code), não precisa discovery — você configura o path. O problema de discovery é mais relevante pra cenários cross-org, e isso ainda tá verde.

OKF substitui RAG?

Não. Muda o que RAG recupera, não elimina RAG.

A distinção:

• Fatos estáveis (definições, schemas, playbooks, decisões documentadas) → OKF funciona por leitura direta. O agente lê o bundle, tem o contexto. Sem embedding, sem vector search, sem chunk splitting.
• Queries dinâmicas (buscar em milhões de documentos, dados que mudam constantemente) → RAG continua necessário.

Karpathy colocou isso bem: a diferença entre build once e re-derive every time. OKF é conhecimento construído uma vez e consumido N vezes por leitura. RAG é retrieval sob demanda de corpora imensos.

Na prática, os dois coexistem: seu agente lê o bundle OKF pro contexto base (o que são nossas tabelas, quais métricas importam, qual o playbook de incident response) e usa RAG pra queries ad-hoc contra fontes maiores.

OKF reduz a superfície onde você precisa de RAG. Não mata RAG.

O que o W3C tá fazendo com OKF?

O Holon Community Group do W3C — 30+ participantes — teve sua primeira reunião em 19 de junho de 2026. Objetivo: formalizar OKF como padrão web interoperável.

A direção técnica é tratar o conceito de “DataBook” (bundle OKF) como um profile dentro da stack de padrões web:

• IRI pra identificação única de conceitos
• RDF pra representação semântica
• SPARQL pra queries sobre bundles
• SHACL pra validação de conformidade

Traduzindo: o W3C quer que OKF fale a língua da web semântica sem perder a simplicidade do Markdown. DataBook vira um profile — tipo como Schema.org é um profile de RDF.

Isso é bom? Depende. Se conseguirem manter a barreira de entrada baixa (editar Markdown) enquanto adicionam interoperabilidade formal por baixo dos panos, é win-win. Se virarem XHTML 2.0 de tão complexos, a comunidade ignora e segue com o Markdown puro.

Acompanhe: é cedo, mas o fato de ter W3C olhando dá legitimidade institucional.

E se o Google abandonar o OKF?

Preocupação válida. O cemitério de produtos do Google é lendário.

Mas o risco aqui é menor que o habitual:

1. Apache 2.0 — A spec já tá publicada, licença irrevogável. Ninguém precisa de permissão do Google pra continuar usando.
2. Custo zero pra entrar, zero pra sair — Você não tá deployando infra proprietária. São arquivos Markdown. Se o Google sumir amanhã, seus bundles continuam funcionando.
3. W3C Holon CG — Já existe grupo fora do Google dando legitimidade institucional.
4. O formato é só Markdown — Pior cenário: você tem uma pasta de documentos Markdown bem organizados. Isso não “quebra”.

O risco real não é perder seus dados — é perder momentum. Se o Google parar de investir, o ecossistema de tooling (validadores, CLIs, integrações) estagna. Mas como a base é Markdown + YAML, qualquer comunidade pode manter.

Comparação honesta: Google matou o Reader, o Wave, o Plus. Mas não matou Kubernetes, Go, Protobuf, ou Terraform (ok, esse é HashiCorp). Specs abertas com comunidade ativa tendem a sobreviver ao criador.

Qual a diferença entre OKF e knowledge graph?

OKF é implicitamente um graph. Knowledge graph é formalmente um graph.

OKF é graph-adjacent: os links entre conceitos formam um grafo implícito, mas você não precisa pensar em termos de nós e arestas pra usar. É tipo a diferença entre linkar páginas na Wikipedia e modelar o Wikidata.

Se você precisa de queries formais sobre relações tipadas (“me dê todas as tabelas que alimentam esta métrica via este pipeline”), um knowledge graph faz isso melhor. Se você precisa que um agente entenda seu domínio lendo documentação, OKF é mais prático.

E sim — um knowledge graph pode exportar pra OKF, e um bundle OKF pode ser importado num knowledge graph. São representações diferentes do mesmo conhecimento.

OKF ajuda com SEO?

Não. E o Google foi explícito sobre isso.

OKF não é indexado por search engines. Não gera rich results. Não melhora ranking. Não aparece no Google Search.

Pra SEO, use:

• schema.org — Structured data que o Google entende (JSON-LD nas páginas)
• llms.txt — Pra AI crawlers encontrarem seu conteúdo
• Conteúdo limpo e bem estruturado — O básico que sempre funcionou

OKF é infraestrutura de conhecimento interno. É pra seus agentes, seus times, seus sistemas consumirem. Não é pra o Googlebot.

Confundir OKF com ferramenta de SEO é como usar um ERP pra fazer landing page. Ferramentas diferentes, problemas diferentes.

Como OKF funciona com MCP?

kcmd é um MCP server. Qualquer agente que fale Model Context Protocol pode consumir bundles OKF via tools padronizadas.

Tools disponíveis:

Além do kcmd, qualquer MCP server pode servir um bundle OKF como resources — o bundle vira um recurso que agentes consultam via protocolo padrão.

Na prática: seu Claude Code, Cursor, ou qualquer agente MCP-compatible pode fazer lookup-entry("métrica de churn") e receber o conceito OKF com definição, fórmula, owner, e links relacionados. Sem precisar jogar o bundle inteiro no contexto.

É a diferença entre dar um livro pro agente ler inteiro e dar acesso a um índice remissivo.

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