open-knowledge-format

Open Knowledge Format (OKF) — v0.1

Google Cloud は 2026年6月12日 にOpen Knowledge Format v0.1を公開しました。これは、LLM-wiki パターンを、AI エージェントの知識を扱うポータブルでベンダー中立な形式として正式化するオープンな仕様です。

設計は意図的に最小限に抑えられています。 YAML フロントマターを含む Markdown ファイルのディレクトリで構成されます。スキーマレジストリも中央機関も、必須のツールもありません。

「ファイルを cat できれば OKF を読めます。リポジトリを git clone できれば、配布できます。」

コアコンセプト

コンセプト	定義
ナレッジバンドル	Markdown ファイルで構成される、自己完結したディレクトリツリーです。配布の単位となります。
コンセプト	知識の単一単位で、1 つの Markdown ファイルです。テーブル、指標、プレイブック、API、その他あらゆるアイデアについて記述できます。
コンセプト ID	.md を除いたファイルパスです（例：tables/users.md の ID は tables/users です）。
フロントマター	各ファイルの先頭にある、構造化メタデータを含む YAML ブロックです。
本文	フロントマターの後に続く標準的な Markdown コンテンツです。
リンク	あるコンセプトから別のコンセプトへの Markdown リンクで、関係性を表します。

リファレンスファイル

リファレンス	読み込むタイミング	ファイル
仕様の概要	OKF v0.1 の完全な仕様、適合基準、フィールド定義が必要な場合	references/spec-summary.md
バンドルのアーキテクチャ	OKF バンドルを作成または構成する場合 — ディレクトリ構成、インデックスファイル、相互リンクの規則	references/bundle-architecture.md
ユースケース	実例、サードパーティの実装、採用パターンが必要な場合	references/use-cases.md

スクリプト

スクリプト	目的	読み込むタイミング
okf-bundle-validate.py	OKF バンドルのディレクトリを検証します — フロントマター、必須フィールド、予約済みファイル名、相互リンクの整合性を確認します	OKF バンドルを作成または変更し、適合性を確認したい場合

アセット

アセット	目的	パス
コンセプトテンプレート	推奨されるすべてのフロントマターフィールドと本文セクションを含む Markdown ファイルのテンプレート	assets/concept-template.md
バンドルの例	ディレクトリ構成、インデックスファイル、相互リンクされたコンセプトを示す、最小限でありながら完全な OKF バンドル	assets/example-bundle/

バンドル構造

path/to/bundle/
├── index.md                      # Optional. Directory listing for progressive disclosure.
├── log.md                        # Optional. Chronological update history.
├── <concept>.md                  # A concept at the bundle root.
└── <subdirectory>/               # Subdirectories organize concepts into groups.
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── …

index.md および log.md という名前のファイルは予約済みです。定義済みの意味を持つため、コンセプト文書には使用できません。

フロントマターフィールド

---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, …]            # Optional
timestamp: <ISO 8601 datetime>     # Optional last-modified time
# … other producer-defined key/value pairs
---

必須： type — コンセプトの種類を示す短い文字列です。種類は中央で登録されません。作成者は説明的な値を選び、利用者は未知の種類を適切に許容します。

慣例的な本文セクション：

見出し	目的
# Schema	アセットの列やフィールドを構造的に説明します
# Examples	多くの場合、コードブロックで具体的な使用例を示します
# Citations	本文中の主張を裏付ける外部ソースを示します

相互リンク

コンセプト同士は、標準的な Markdown リンクを使って相互にリンクします。

• 絶対パス（バンドル相対）： バンドルのルートを基準に、/ で始めます。文書が移動しても安定するため、推奨されます。
• 相対パス： 標準的な Markdown の相対パスです。

コンセプト A からコンセプト B へのリンクは、両者の関係性を示します。参照、依存、結合などの具体的な種類はリンク構文ではなく、周囲の文章で伝えます。

利用者はリンク切れを許容しなければなりません（MUST）。 リンク先が存在しないリンクも不正な形式ではありません。まだ書かれていない知識を表している場合があります。

適合性

バンドルが OKF v0.1 に適合するのは、次の条件を満たす場合です。

1. 予約済みではないすべての .md ファイルに、解析可能な YAML フロントマターが含まれている
2. すべてのフロントマターブロックに、空ではない type フィールドが含まれている
3. 予約済みファイル名（index.md、log.md）が定義された構造に従っている

コンシューマーは、次の理由でバンドルを拒否してはなりません。 任意のフロントマターフィールドの欠落、未知の type 値、未知のフロントマターキー、壊れた相互リンク、または index.md ファイルの欠落。

他のフォーマットとの関係

フォーマット	OKF との違い
Karpathy の LLM Wiki	OKF は相互運用性の範囲（必須フィールド、予約済みファイル名、適合性基準）を定めています
Obsidian / Notion vaults	OKF はフォーマットのみを定めています。ツール、ランタイム、UI はありません。どのエディターでも使えます
AGENTS.md / CLAUDE.md	OKF は複数ファイル、階層構造、相互リンクに対応しており、単一の規約ファイルではありません
メタデータをコードとして扱うリポジトリ	OKF はファイルフォーマットを標準化し、異なるプロデューサーとコンシューマー間の相互運用を可能にします
ドメインスキーマ（Avro、Protobuf、OpenAPI）	OKF はこれらを参照しますが、包含したり置き換えたりするものではありません

クイックスタート

# 1. Create a bundle directory
mkdir my-knowledge && cd my-knowledge

# 2. Create a concept file
cat > datasets/sales.md << 'EOF'
---
type: BigQuery Dataset
title: Sales
description: All sales-related tables for the retail business.
tags: [sales]
timestamp: 2026-06-18T00:00:00Z
---
The sales dataset contains [orders](/tables/orders.md) and [customers](/tables/customers.md).
EOF

# 3. Add an index for navigation
cat > index.md << 'EOF'
# Knowledge Bundle

* Sales Dataset (`datasets/sales.md`) - Retail sales data in an example OKF bundle
EOF

# 4. Validate your bundle
python3 scripts/okf-bundle-validate.py .

注意点

• type 値は一元的に登録されません。 説明的な type（BigQuery Table、Playbook、Metric）を選んでください。コンシューマーは未知の type を適切に処理する必要があります。
• ファイルパスが識別子です。 ファイル名を変更すると、そのコンセプト ID も変わります。安定したパスを使用するか、ドキュメントにリダイレクトを追加してください。
• index.md はフロントマターを使用しません（バンドルのルートで okf_version を任意に指定する場合を除く）。本文はリンク付きの Markdown リストです。
• log.md の日付見出しは ISO 8601（YYYY-MM-DD）でなければなりません。
• 相互リンクに型はありません。 関係性の意味はリンク構文ではなく、文章に記述します。グラフビルダーはすべてのリンクを有向エッジとして扱います。
• OKF はタグ閲覧用フォーマットを定めていません。 タグの集約が必要なプロデューサーは、フロントマターをスキャンして、コンシューマー側でその時点に集約データを生成してください。
• OKF v0.1 はドラフトです。 仕様は今後変更されます。マイナーバージョンの更新では後方互換性のある機能が追加され、メジャーバージョンの更新では必須フィールドが変更される可能性があります。未知のバージョンに対して、コンシューマーは可能な範囲で処理してください。