Open Knowledge Formatとは？OKF v0.2の仕様を解説

Open Knowledge Format（OKF）は、組織の知識を「YAML フロントマター付きの Markdown ファイルのディレクトリ」として表すためのオープン仕様です。Google Cloud が 2026 年 6 月に v0.1 を公開し、7 月に v0.2 へ更新しました。専用の SDK もランタイムもデータベースも要らず、必須フィールドは type ひとつだけです。この記事では、OKF の仕様、v0.2 で加わった出所・信頼・鮮度の記述、AGENTS.md や Agent Skills との使い分け、そして gaipack が社内ドキュメントを OKF v0.2 準拠へ移したときに詰まった点を解説します。

Open Knowledge Formatとは何か：エージェントが読む知識の共通形式

OKF は、Google Cloud が 2026 年 6 月 12 日（日本時間 13 日）に公開した、知識を記述するためのベンダー非依存の仕様です。ここでいう知識とは、データやシステムを正しく使うために必要なメタデータ・文脈・整理された知見を指します。テーブルの意味、指標の定義、運用のプレイブックといった、コードにもデータにも書かれていない情報です。

公式ブログは OKF の設計原則を 3 つ挙げています。制限が最小限であること（必須は type のみ）、書き手であるプロデューサーと読み手であるコンシューマーが独立していること、そしてプラットフォームではなく形式であることです。ツールは付属しますが、仕様そのものが本体という位置づけで、公式ブログは次のように書いています。

形式そのものが貢献です。Google がリリースしたツールは、それを実現し、試すためのコストを下げるために存在します。

プレーンな Markdown とディレクトリだけで完結することが、この仕様の実用上の意味です。cat で読めて、git diff で差分が追えて、LLM がそのままコンテキストに載せられます。ナレッジ管理サービスに入れた知識はそのサービスの API を通してしか取り出せませんが、OKF のバンドルはディレクトリなので、tarball で配っても、リポジトリに置いても、別のツールにマウントしても読めます。

仕様書は GitHub の GoogleCloudPlatform/knowledge-catalog にあり、2026 年 8 月には仕様と参照実装だけを切り出した GoogleCloudPlatform/open-knowledge-format も公開されました。どちらも v0.2 の同じ SPEC.md を置いています。

検索するときは略称ではなく正式名称を使うのが確実です。OKF は非営利団体 Open Knowledge Foundation の略称としても使われているため、「OKF」だけで調べると別の話題が混ざります。

OKFの仕様：必須フィールドは type だけ

OKF の仕様は 1 本の SPEC.md に収まっていて、覚えることは多くありません。ディレクトリを「バンドル」、その中の 1 ファイルを「コンセプト」と呼び、ファイルパスから .md を取り除いたものがコンセプト ID になります。

path/to/bundle/
  index.md                # 任意。ディレクトリの目次
  log.md                  # 任意。更新履歴
  tables/
    index.md
    orders.md             # コンセプト ID は tables/orders
    customers.md
  metrics/
    weekly_active_users.md

各コンセプトは frontmatter と本文の 2 部構成です。frontmatter で定義されているキーは次の 5 つで、必須は type だけです。

type の値は中央登録制ではありません。仕様は「プロデューサーは自己説明的な値を選ぶべきで、コンシューマーは知らない type を寛容に扱わなければならない」とだけ定めています。本文も自由で、# Schema・# Examples・# Computation の 3 つが慣用的な見出しとして挙がっているだけです。

コンセプト同士は通常の Markdown リンクでつなぎます。バンドルルート起点の /tables/customers.md 形式が推奨で、リンクが張られていること自体が関係の表明になります。関係の種類（親子、参照、結合）はリンクではなく周囲の文章で伝える設計です。

index.md（目次）と log.md（更新履歴）は予約ファイル名で、コンセプトには使えません。ただし、どちらも作成は任意です。

コンシューマー側の振る舞いも仕様に書かれていて、後付けで導入するときはこの規定が助けになります。適合条件は「予約ファイル以外のすべての .md がパース可能な frontmatter を持ち、type が空でないこと」だけで、未知の type・未知のキー・壊れたリンク・index.md の不在を理由にバンドルを拒否してはならないとコンシューマー側に課しています。壊れたリンクは「まだ書かれていない知識」かもしれない、というのが仕様の立場です。この寛容さのおかげで、全部を整えてから使い始める必要がなくなります。

OKF v0.2で増えた「信頼できるか」を示すフィールド

v0.2 は、知識をエージェントが書き続ける前提を仕様に持ち込んだ版です。日本語の解説記事の多くは 6 月の v0.1 を対象にしているため、ここが今いちばん情報の薄い部分になっています。

仕様書は、機械生成のコンセプトが増えると素の Markdown では答えられない問いが出てくる、と説明しています。何を材料に書かれたのか（出所）、どれだけ信じてよいのか（信頼）、まだ正しいのか（鮮度）、最新版なのか（ライフサイクル）、その数値は決められたやり方で計算されたのか（証明）の 5 つです。v0.2 はこれらを frontmatter の任意フィールドとして足しました。

sources：どの材料から書かれたか

sources は、そのコンセプトが derived した材料を並べます。各エントリで必須なのは resource だけで、そこに author・usage_count・last_modified という信憑性シグナルを付けられます。

sources:
  - id: ga4-schema
    resource: https://developers.google.com/analytics/bigquery/export-schema
    title: GA4 BigQuery Export schema
    author: team:ga4-docs
    usage_count: 5000
    last_modified: 2026-05-30T00:00:00Z
usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }

信憑性スコアは保存しません。スコアは主観的で、コンシューマーごとに基準が違い、すぐ古くなるからです。仕様が持つのは客観的なシグナルだけで、判断は読む側がやります。本文中の個別の記述に出典を紐づけたいときは、sources[].id をラベルにした Markdown の脚注（[^ga4-schema]）を使います。順番ではなく ID で結ぶのは、エージェントが文書を書き換えるたびに順番が変わるためです。

generated と verified：誰が書き、誰が確認したか

generated は内容を書いたアクターと時刻、verified は内容を材料と突き合わせて確認したアクターと時刻です。書いた主体と確認した主体は別物なので、フィールドも分けています。

generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified:
  - { by: human:ahormati, at: 2026-06-25T09:00:00Z }
  - { by: process:finance-nightly, at: 2026-06-26T02:00:00Z }

アクターの書き方は <producer>/<version>（ツール）、human:<id>（人）、process:<id>（自動処理）の 3 通りに決まっています。コンシューマーはこの human: 接頭辞を見て、未検証・機械確認済み・人間レビュー済みの 3 段階の信頼度を導きます。段階そのものはファイルに書きません。

status と stale_after：まだ使ってよいか

status は draft・stable・deprecated の 3 値で、省略時は stable とみなされます。古くなった文書は消さずに deprecated へ落とし、リンクと履歴のために残す運用が想定されています。

stale_after は絶対時刻で、now >= stale_after なら陳腐化していると判定します。相対的な TTL にしなかったのは、「いつ読んだか」を持ち出さずに単純な比較で決められるようにするためです。

Attested Computation：その数値はどう計算されたか

v0.2 では type: Attested Computation という種類のコンセプトが増えました。指標の意味だけでなく、認められた計算方法そのものを持たせ、エージェントが自分で書いた SQL ではなく決められた計算を実行したことを確認できるようにする仕組みです。runtime（bigquery など）、parameters、executor（実行方法と、実行後に返すべき証跡の項目）、attester（証跡を検証する LLM なしのコード）を frontmatter に書きます。

verified と混同しやすいので、仕様は区別を明示しています。verified は定義が方針に合っているかの確認で、文書単位・低頻度・バンドルに記録されます。attestation は 1 回の実行が正しい手順で行われたかの確認で、実行ごと・実行時のもので、バンドルには保存しません。

v0.1 からの互換性が切れた変更は 2 つです。最終更新を表していた timestamp は generated.at に置き換わり、本文末尾の # Citations リストは frontmatter の sources に移りました。仕様自体の更新はリポジトリのコミット履歴で追えます。v0.1 の取り込みが 2026 年 6 月 12 日、v0.2 への移行が 7 月 24 日、タイムスタンプを ISO 8601 の明示オフセット付きに揃える修正が 8 月 21 日でした。

既存ドキュメントにOpen Knowledge Formatを後付けした

gaipack では、社内のナレッジリポジトリにある正本ドキュメントと、サービスサイトのリポジトリ固有のドキュメントを、2026 年 9 月に OKF v0.2 準拠の frontmatter へ統一しました。サービス定義書、ガイドライン、事業戦略、導入事例、研修教材、エージェントのルーチン定義が対象です。新しくバンドルを作ったのではなく、すでに運用しているドキュメント群にあとから適用した形になります。

type 語彙はディレクトリと 1 対 1 で決めた

type の語彙は中央登録制ではないため、各自が好きに決められます。gaipack はディレクトリと type を 1 対 1 で対応させ、語彙表を AGENTS.md に置きました。docs/services/ は Service Definition、docs/guidelines/ は Guideline、docs/cases/ は Case Study、各ディレクトリの README.md は Index という具合です。置き場所が決まれば type も決まるので、書き手が値を考える場面をなくせます。

表を先に置いたのは、あとから文書を足す人（人間とエージェントの両方）が迷わないようにするためです。語彙を増やすときは表に追記する、という手順も同じ場所に書いてあります。

status が二重の意味を持っていた

移行で最初に詰まったのが、既存キーとの意味の衝突です。導入事例のドキュメントには以前から status: published が入っていました。これは「この事例を対外公開してよいか」を表す社内の運用フラグで、OKF の status（文書の成熟度）とは別の概念です。同じキー名で意味が違うまま残すと、コンシューマー側が誤って解釈します。

対応として、既存のキーを publication_status へ退避し、status は OKF の 3 値に明け渡しました。

---
title: "gaipack 公式サイト：AI CMS で開発・運用負荷軽減"
nav_order: 7
parent: 事例
publication_status: published   # 対外公開の可否（社内の運用フラグ）
type: Case Study
description: "AIDD CMS の導入により gaipack 公式サイトの開発・運用負荷を約 50% 軽減した事例。"
status: stable                  # OKF の成熟度（draft / stable / deprecated）
---

サイト生成に使っている既存のキー（title・parent・nav_order・owner）は消さず、その後ろに OKF のキーを足す並びに統一しました。OKF は追加キーを許容するので、既存の用途とぶつからない限り共存できます。

index.md と log.md は作らなかった

仕様の予約ファイルである index.md と log.md は、作成しない判断をしました。ドキュメントサイトが各ディレクトリの README.md を入口として扱う構成になっていて、index.md を新設すると公開 URL の構造が変わってしまうためです。更新履歴は Git のコミット履歴を正本にしています。

どちらも仕様上は任意（MAY）なので、作らなくても適合要件は満たします。準拠の判定基準が「type が空でないこと」に絞られているので、こういう既存構成との折り合いをつけやすいのが実務での利点でした。

適合チェックは 20 行のスクリプトで済ませた

専用のバリデータを入れなくても、適合しているかは標準ライブラリだけで確認できます。gaipack が移行時に使ったのは次のスクリプトです。

#!/usr/bin/env python3
"""docs/ 配下が OKF v0.2 の必須要件を満たすか確認する。"""
import pathlib
import sys
import yaml
STATUSES = {"draft", "stable", "deprecated"}
ng = []
for path in sorted(pathlib.Path("docs").rglob("*.md")):
    if path.name in ("index.md", "log.md"):
        continue
    text = path.read_text(encoding="utf-8")
    if not text.startswith("---\n"):
        ng.append(f"{path}: frontmatter がない")
        continue
    front = yaml.safe_load(text.split("---\n", 2)[1]) or {}
    if not front.get("type"):
        ng.append(f"{path}: type が空")
    if front.get("status", "stable") not in STATUSES:
        ng.append(f"{path}: status が不正 ({front.get('status')})")
print("\n".join(ng) if ng else "OK: すべて OKF v0.2 の必須要件を満たしています")
sys.exit(1 if ng else 0)

移行作業そのものは frontmatter を足すだけで、時間がかかったのは語彙の設計とキーの衝突の整理でした。検索や生成の品質がどう変わったかはこれから測るところで、現時点で言えるのは「文書の種類と要約と鮮度が機械可読になった」という構造面の変化までです。社内ナレッジを検索させる仕組みそのものについては、RAG と MCP で社内ナレッジを資産化した事例でも扱っています。

OKFを小さく試すときの最小構成

社内の全ドキュメントを一度に整える必要はありません。適合要件が type だけなので、数ファイルから始めて広げられます。

最小のバンドルは、ディレクトリ 1 つとコンセプト 1 ファイルです。

---
type: Playbook
title: "障害対応：データ鮮度アラート"
description: 受注パイプラインの鮮度アラートを切り分ける手順。
status: draft
generated: { by: "human:your-id", at: 2026-09-15T09:00:00Z }
---
# Trigger
受注テーブルの更新が想定より 30 分以上遅れるとアラートが出ます。
# Steps
1. 取り込みジョブのダッシュボードを確認する。
2. 直近の実行ログでエラーの有無を見る。

あとは、このディレクトリを AI エージェントに読ませるだけで消費側が成立します。専用のサーバーもインデックスも要りません。書き手が増えてきたら description を埋め、機械生成が混ざり始めたら generated と verified を足す、という順に育てられます。

バンドルの全体像を確認したいときは、Google の参照実装に付属するビジュアライザが使えます。公式リポジトリの visualize サブコマンドは、バンドルを 1 枚の自己完結した HTML に書き出し、コンセプト同士のリンクを力学モデルのグラフとして表示します。リポジトリには GA4・Stack Overflow・Bitcoin の公開データセットから生成したサンプルバンドルと、その viz.html が置かれているので、自分で生成する前に完成形を見られます。

OKFとAGENTS.md・Agent Skills・RAGの使い分け

OKF を検討すると、すでに置いてある AGENTS.md や Skills、あるいは RAG 基盤と役割が重なるように見えます。それぞれ書くものと読まれ方が違うので、用途で分けて考えると整理できます。

OKF と RAG は択一ではありません。OKF は知識をどの形式で保管するかの取り決めで、検索の仕組みではないためです。バンドルが数百ファイルを超えると、ディレクトリを辿るだけでは目的の知識に届きません。全文検索やベクトル検索を前に置く必要があり、そこは OKF の守備範囲の外にあります。この住み分けはRAG とエージェンティック検索の違いやMCP の解説記事で扱っている論点とも重なります。

概念同士の関係を厳密に定義したい場合も、OKF 単体では足りません。OKF のリンクは種類を持たない有向辺で、関係の意味は周囲の文章が担います。関係に型を与えて推論させたいなら、オントロジーの設計のように別の語彙を重ねることになります。どこまで構造化するかは、コンテキストエンジニアリングの設計判断そのものです。

Open Knowledge Formatに関するよくある質問

OKF を試そうとしている方から実際に受ける質問をまとめました。

オープンナレッジフォーマットとは何ですか

Google Cloud が 2026 年 6 月に公開した、知識を Markdown と YAML フロントマターで記述するためのオープン仕様です。AI エージェントと人間の両方が読める形で社内の知識を残すことを目的にしています。特定のベンダーやランタイムに縛られず、ディレクトリごと持ち運べます。

OKF形式のファイルは具体的にどんな中身ですか

拡張子は .md で、中身は普通の Markdown です。先頭に --- で囲んだ YAML フロントマターがあり、そこに type を必ず書きます。title・description・resource・tags は推奨で、v0.2 では出所や信頼を示す sources・generated・verified・status・stale_after も書けます。本文の書式は自由です。

OKFとRAGはどちらを選べばよいですか

役割が違うので、片方を選ぶ関係にはなりません。OKF は知識をどう保管するかの形式、RAG は保管された知識をどう検索して渡すかの仕組みです。OKF のバンドルを RAG の取り込み元にする構成も取れます。文書数が少なくディレクトリを辿れば足りる段階なら、OKF だけで始めても動きます。

OKFに対応したツールはありますか

Markdown と YAML フロントマターを扱えるツールはそのまま使えます。Obsidian、Notion、MkDocs、Jekyll などが該当します。Google の参照実装には、バンドルを 1 枚の HTML にまとめて概念の関係をグラフ表示するビジュアライザも含まれていて、GA4・Stack Overflow・Bitcoin の公開データセットから生成したサンプルバンドルが同じリポジトリに置かれています。

まとめ

Open Knowledge Format は、知識をサービスに預けるのではなくファイルとして持つための仕様です。必須は type だけ、コンシューマーは不足を拒否しない、という設計なので、既存のドキュメントに後から足していけます。

• v0.2 で増えたのは信頼にまつわる記述で、sources（出所）、generated と verified（誰が書き誰が確認したか）、status と stale_after（まだ有効か）、Attested Computation（計算の正当性）が任意フィールドとして加わりました
• 既存ドキュメントへの適用でコストがかかるのは frontmatter の付与ではなく、type 語彙の設計と、既存キーとの意味の衝突の解消です
• index.md や log.md を作らなくても適合要件は満たせるため、既存のサイト構成を壊さずに導入できます

gaipack では、社内ナレッジの整備から AI エージェントによる活用までを支援しています。ドキュメントを AI が読める状態にする進め方については、gaibot のページもあわせてご覧ください。お気軽にご相談ください。