okf-open-knowledge-format

Open Knowledge Format (OKF)

OKF は Google Cloud が公開した、ナレッジを YAML フロントマター付きの Markdown ファイルのディレクトリとして表現する、ベンダー中立のオープンな仕様（v0.2）です。SDK は不要です。ファイルを cat できれば、OKF を読み取れます。

これは「LLM Wiki」パターン（Karpathy の gist）を相互運用可能な形式として公式化したものです。異なる作成者が記述した Wiki を、変換せずに異なるエージェントが利用できます。

v0.2 での追加内容： 出典の追跡（sources）、信頼性を示す情報（generated、verified）、ライフサイクル管理（status、stale_after）、および公認された検証可能な計算を表す新しい概念タイプである Attested Computations。

仕様の全文については、以下を参照してください。

• references/spec-v02.md — 現行バージョン（v0.2）
• references/spec-v01.md — 旧バージョン（v0.1）

設計原則

1. 意見を最小限に抑える — 必須なのは type だけです。仕様が定めるのは相互運用の範囲であり、コンテンツモデルではありません。
2. 作成者と利用者の独立性 — 誰が書き、誰が読むかは切り離されています。人間が作成したバンドルをエージェントが利用し、LLM が生成したバンドルを人間が閲覧できます。
3. プラットフォームではなく形式 — クラウド、SDK、ベンダーへの依存はありません。価値は、この形式を利用する関係者の数によって生まれます。
4. 信頼性を第一級の要素として扱う — v0.2 では、出典、検証状況、新しさをフロントマターから照会できるようになっています。

---

主要な用語

用語	定義
Bundle	.md ファイルのディレクトリツリー。配布単位（git リポジトリ、tarball、またはサブディレクトリ）です。
Concept	Markdown ファイル 1 つが、ナレッジの 1 単位（テーブル、メトリクス、プレイブック、API など）に相当します。
Concept ID	バンドル内のファイルパスから .md の拡張子を除いたものです。例：tables/users.md → ID tables/users
Frontmatter	ファイルの先頭にある、--- 区切りの YAML ブロックです。
Body	フロントマター以降のすべてです。標準の Markdown 形式です。
Link	概念間の関係を表す、標準の Markdown リンクです。
Source	概念の由来となる資料で、フロントマターの sources フィールドに記録されます。
Provenance	概念の由来となる一連の資料です。
Actor	識別文字列です。エージェントの場合は <producer>/<version>、人間の場合は human:<id>、自動化処理の場合は process:<id> です。
Trust tier	verified から導出されるレベルです。未検証、機械による確認済み、人間によるレビュー済みがあります。
Attested Computation	値を計算する公認の方法を含む概念（type: Attested Computation）です。

---

クイックリファレンス — フロントマターのフィールド

コアフィールド（すべての概念）

フィールド	必須？	説明
type	YES	概念の種類（自由形式の文字列。例：BigQuery Table、Metric、Playbook、Attested Computation）
title	推奨	人間が読みやすい表示名
description	推奨	1 文での要約
resource	推奨	基盤となるアセットを特定する URI（抽象的な概念の場合は省略）
tags	任意	横断的な分類に使う YAML リスト

信頼性とライフサイクルのフィールド（v0.2）

フィールド	説明
generated	{ by: <actor>, at: <ISO8601> } — このコンテンツを誰が、または何が、いつ作成したか
verified	{ by: <actor>, at: <ISO8601> } のリスト — 正確性を確認した人または処理
status	draft | stable | deprecated — デフォルト：stable
stale_after	ISO 8601 の日時 — この時点以降、コンテンツは古いものとして扱われます

Provenance Fields (v0.2)

フィールド	説明
sources	ソースエントリーのリスト（以下を参照）
usage_window	{ from, to } — usage_count シグナルの時間範囲

各 sources エントリー：

• resource（必須）：URL、バンドル相対パス、またはスコープ記述子
• id：脚注の帰属表示に使う安定したキー
• title：人が読めるラベル
• author：ソースを作成した主体
• usage_count：使用された頻度（稼働状況のシグナル）
• last_modified：ソースが最後に変更された日時

Attested Computation Fields (v0.2)

type: Attested Computation のコンセプトの場合：

フィールド	説明
runtime	必須。実行方法：bigquery、postgres、dbt、python、Looker
parameters	{ name, type, required } のリスト — エージェントが埋める型付きの穴
computation	計算ファイルへのパス（本文にインラインで記載されていない場合）
executor	{ resource, receipt: [...] } — 実行方法と記録する証拠
attester	{ resource } — レシートを検証する決定論的なコード

Reserved Filenames

ファイル	用途	frontmatter はありますか？
index.md	段階的開示のためのディレクトリ一覧	いいえ*
log.md	変更履歴（新しい順）	いいえ

*例外：バンドルルートの index.md には、okf_version: "0.2" を含む frontmatter を記載できます。

Conventional Body Headings

見出し	使用する場合
# Schema	データアセット — 列／フィールドの説明
# Examples	具体的な使用方法の提示（コードブロック、クエリ）
# Computation	Attested Computation — 認可されたコード／クエリ

---

Actor Convention

アイデンティティを記録するフィールド（generated.by、verified[].by、sources[].author）では、次の形式を使用します。

• エージェントの場合は <producer>/<version>：reference_agent/gemini-2.5-pro
• 人の場合は human:<id>：human:ahormati
• 自動化の場合は process:<id>：process:finance-nightly

信頼ティアは human: プレフィックスから導出されます。人による検証済み > マシンによる確認済み > 未検証。

---

Trust Tiers

コンシューマーは verified フィールドから信頼度を導出します。

条件	信頼ティア
verified キーがない	未検証
human: 以外のアクターによる verified のみ	マシンによる確認済み
human:<id> アクターによる verified がある	人によるレビュー済み

信頼ティアは参考情報であり、アクセス制御ではありません。

---

Create a Bundle

ユーザーが OKF バンドルを一から作成したい場合：

1. スコープと構造を決める

質問します：どのような知識を記録しますか？（テーブル、メトリクス、API、プレイブックなど） ドメインに適したディレクトリツリーに整理します。

2. コンセプトドキュメントを作成する

各コンセプトを 1 つの .md ファイルにします。最小限の準拠例：

---
type: Metric
---

# Monthly Recurring Revenue (MRR)

Sum of all active subscriptions normalized to a monthly amount.

出典情報と信頼情報を含む v0.2 の完全な例：

---
type: Metric
title: Monthly Recurring Revenue
description: Sum of all active subscription revenue normalized to monthly.
tags: [revenue, saas, kpi]
status: stable
generated: { by: human:ftelles, at: 2026-08-25T10:00:00Z }
verified: { by: human:finance-lead, at: 2026-08-25T14:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: stripe-docs
    resource: https://stripe.com/docs/billing/subscriptions
    title: Stripe Subscription Billing
    author: team:stripe-docs
    last_modified: 2026-06-01T00:00:00Z
---

# Monthly Recurring Revenue (MRR)

## Definition

Sum of all active subscriptions normalized to a monthly amount.[^stripe-docs]
Excludes one-time fees and overages.

## Formula

`MRR = Σ(active_subscription_monthly_value)`

## Related

- [Churn Rate](./churn.md) uses MRR as denominator
- [ARR](./arr.md) = MRR × 12

[^stripe-docs]: Stripe Subscription Billing

さまざまなドメインの例については、references/examples.md を参照してください。

3. コンセプト間を相互リンクする

標準的な Markdown リンクを使用します。形式は 2 種類あります。

• 絶対リンク（バンドル相対で、/ から始まる）：[customers](/tables/customers.md) — 推奨（ファイルを移動しても安定します）
• 相対リンク：[churn](./churn.md)

リンクは関係性を示します。関係性の種類はリンク構文ではなく、周囲の文章で伝えます。リンク切れは明示的に許可されており、まだ文書化されていない知識を表します。

4. 脚注で出典情報を追加する（v0.2）

主張が外部ソースを参照する場合は、frontmatter の sources と本文の脚注を使用します。

sources:
  - id: ga4-schema
    resource: https://developers.google.com/analytics/bigquery/export-schema
    title: GA4 BigQuery Export schema

The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]

[^ga4-schema]: GA4 BigQuery Export schema

5. index.md を生成する

段階的開示のため、任意のディレクトリに配置します。frontmatter は不要です。形式：

# Metrics

- [MRR](./mrr.md) - Monthly recurring revenue
- [Churn](./churn.md) - Monthly churn rate
- [NPS](./nps.md) - Net Promoter Score

エントリーには、リンク先のコンセプトの frontmatter にある説明を含めてください。

6. log.md を生成する（任意）

変更履歴を時系列順（新しい順）に並べ、日付見出しには ISO 8601 形式を使用します。

# Update Log

## 2026-08-25
- **Creation**: Added MRR, Churn, and NPS metrics.
- **Creation**: Established directory structure.

## 2026-08-20
- **Initialization**: Bundle created.

7. バージョンを宣言する（任意）

バンドルルートの index.md には、仕様のバージョンを宣言する frontmatter を記載できます。

---
okf_version: "0.2"
---

# My Knowledge Bundle

- [Tables](./tables/) - Database tables
- [Metrics](./metrics/) - Business KPIs

8. 配布

バンドルは次の形式で配布できます。

• Git リポジトリ（推奨 — 履歴、帰属、差分を保持できます）
• tarball または zip アーカイブ
• より大きなリポジトリ内のサブディレクトリ

9. 準拠の確認

3 つのルールすべてに合格する必要があります。

1. 予約ファイル以外のすべての .md ファイルに、解析可能な YAML フロントマターがある
2. すべてのフロントマターに、空でない type フィールドがある
3. 予約ファイル（index.md、log.md）が存在する場合、定義された構造に従っている

---

認証付き計算の作成（v0.2）

認証付き計算とは、値の 意味 だけでなく、その値を 計算 するための認可された方法も伴う概念です。検証可能で再現性のある計算が必要な場合に使用します。

使用する場面

• コンプライアンス上、監査証跡が必要な財務指標
• レポート間で一貫して計算する必要がある KPI
• 「認可された処理が実行されたか」が重要となる計算

構造

---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/revenue.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-09-23T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

The computation binds only the declared `parameters`, per the recognition
policy.[^rev-policy]

[^rev-policy]: Revenue recognition policy

主なルール

1. エージェントが入力するのはパラメーターのみ — エージェントは宣言された parameters に 値 を指定します。計算自体は編集しません
2. 計算はインラインまたは外部ファイルに記述できます — インラインの場合は # Computation 見出しを使用し、外部ファイルの場合は computation: フィールドを使用します
3. 実行者がレシートを生成します — アテスターが検査する証拠です
4. アテスターは決定論的です — LLM は使わず、レシートを検証するコードのみを使用します

計算へのリンク

他の概念から認証付き計算にリンクします。

---
type: Metric
title: Revenue
---

# Definition

Recognized revenue for a fiscal year, computed by 
[the revenue computation](../computations/revenue.md).

---

バンドルの検証

推奨：okflint（利用可能な場合）

okflint は、OKF バンドル向けの専用 Python リンターです。3 つのティア（OKF コア、プロファイル、衛生管理）にわたる 18 個のルールを備えています。インストールされている場合は、組み込みの bash スクリプトではなく、常に okflint を優先してください。

エージェントの動作： 検証の前に、okflint がインストールされているか確認します（command -v okflint）。インストールされていない場合は、ユーザーに尋ねます。

「okflint（18 個のルール、マニフェスト経由のプロファイル、wikilink のサポートを備えた OKF 専用リンター）がインストールされていません。インストールしますか？選択肢：

1. uv tool install okflint（推奨、分離環境にインストール）
2. pip install okflint
3. インストールせずに続行する（組み込み bash スクリプトで基本検証）」

ユーザーがインストールに同意した場合：

# Option 1: uv (recommended — installs isolated, no venv needed)
uv tool install okflint

# Option 2: pip (installs in current environment)
pip install okflint

# Verify installation
okflint --version

インストール後（またはすでに利用可能な場合）：

# Full validation with manifest (if okf-base.yaml exists)
if [ -f okf-base.yaml ]; then
  okflint validate --manifest okf-base.yaml ./bundle/
else
  # Core OKF validation only (no manifest needed)
  okflint validate ./bundle/
fi

組み込みスクリプトと比べた okflint の利点：

• マニフェスト駆動のプロファイル（カスタム必須フィールド、ステータスの語彙、タイプごとの制約を適用）
• Obsidian ボルト全体を対象とした wikilink の解決
• CI パイプラインで解析できる JSON 出力（--json）
• 壊れた Markdown リンクと曖昧な wikilink を検出
• 終了コード：0 = 合格、1 = 準拠違反、2 = マニフェスト不正

フォールバック：組み込み bash スクリプト

okflint がインストールされていない場合は、scripts/validate.sh を使用します。このスクリプトは、v0.2 のフィールドに加えて、準拠に関する 3 つの基本ルールを確認します。

検証を依頼された場合は、準拠に関する 3 つのルールを確認します。次のように報告します。

✅ PASS: 12/12 concept files have valid frontmatter with type field
✅ PASS: index.md follows list structure (no frontmatter)
✅ PASS: log.md uses ISO 8601 date headings, newest first

⚠  WARNING: 3 files missing 'description' field (recommended)
⚠  WARNING: 2 broken cross-links (permitted but worth noting)
ℹ  INFO: 5 files with trust fields (generated/verified)
ℹ  INFO: 2 Attested Computation concepts found

スクリプトによる確認については、scripts/validate.sh を参照してください。

エラー（準拠違反）

• E1：ファイル {path} に YAML フロントマターがありません
• E2：ファイル {path} にフロントマターはありますが、type フィールドがありません（または空です）
• E3：予約ファイル {path} の構造が想定と異なります
• E4：認証付き計算に必須の runtime フィールドがありません

警告（ブロックされないもの。仕様上許容されています）

• W1：推奨フィールド title または description がありません
• W2：{file} 内のクロスリンク {link} が壊れています
• W3：generated フィールドがありません（v0.2 で推奨）
• W4：ディレクトリ {dir} に index.md がありません
• W5：log.md の日付が ISO 8601 形式ではありません
• W6：sources エントリーに resource フィールドがありません
• W7：stale_after の日付を過ぎており、コンテンツが古くなっています

コンシューマーは、任意フィールドがないこと、未知のタイプ値、未知のフロントマターキー、壊れたリンク、またはインデックスファイルがないことを理由に、バンドルを拒否してはなりません。

---

概念の拡充

ユーザーが拡充を必要とする既存の OKF 概念を持っている場合：

スキーマセクションの追加

データアセットの場合は、列のテーブルを含む # Schema を追加します。

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique identifier |
| `customer_id` | STRING | FK to [customers](/tables/customers.md) |

例を追加する

API、クエリ、またはツールの場合は、使い方を示すフェンス付きコードブロックを含む # Examples を追加します。

出典情報を追加する（v0.2）

クレームごとの出典を明示するため、フロントマターに sources を追加し、本文に脚注を記載します。

sources:
  - id: official-docs
    resource: https://example.com/docs
    title: Official Documentation
    author: team:product-docs
    last_modified: 2026-07-15T00:00:00Z

信頼性を示す情報を追加する（v0.2）

generated: { by: reference_agent/gemini-2.5-pro, at: 2026-08-25T10:00:00Z }
verified: { by: human:domain-expert, at: 2026-08-25T14:00:00Z }
status: stable
stale_after: 2026-12-31T00:00:00Z

相互リンクを追加する

自然な文章の中にリンクを織り込みます。独立した「リンク」セクションは作らず、関係性が意味を持つ箇所で文脈に沿って表現します。

推奨フィールドを補完する

title、description、tags がない場合は追加します。可能な場合は本文の内容から値を導き出します。

エンリッチメントのワークフローに関する参考情報

公式のエンリッチメントエージェントは、次のパターンに従います。同じロジックを手動で適用してください。

1. メタデータのみのドキュメントから始めます（フロントマターと最小限の本文だけ）
2. ソースシステムからスキーマや構造を追加します
3. 信頼できるドキュメントから sources を追加します
4. 見つかった関連性（FK、共通のタグ、結合パス）に基づいて相互リンクを織り込みます
5. 段階的な情報開示のために index.md ファイルを生成します
6. 信頼性の追跡のために generated と、必要に応じて verified を追加します

---

v0.1 から v0.2 への移行

対応が必要な破壊的変更

1. timestamp → generated.at

   # v0.1
   timestamp: 2026-05-28T22:53:05Z
   
   # v0.2
   generated: { by: human:author, at: 2026-05-28T22:53:05Z }
   

2. # Citations → sources

   # v0.1 body
   # Citations
   [1] https://example.com/docs
   
   # v0.2 frontmatter
   sources:
     - id: docs
       resource: https://example.com/docs
       title: Example Documentation
   

移行スクリプトのパターン

# For each .md file:
# 1. Extract timestamp, convert to generated
# 2. Parse # Citations, convert to sources
# 3. Add footnotes in body for citations

# Consumers MAY fall back to legacy fields when v0.2 fields absent

後方互換性

v0.2 のコンシューマーは、次のようにすることが望ましいです。

• generated がない場合は timestamp にフォールバックする
• sources がない場合は従来の # Citations を解析する

---

ソースを OKF に変換する

詳細な変換ガイドについては、references/conversion.md を参照してください。

クイックルール

Notion エクスポート： プロパティをフロントマターに変換します。ファイル名から UUID の接尾辞を削除します。Notion のリンクを相対マークダウンリンクに変換します。

Obsidian ボルト： [[wikilinks]] を [title](./file.md) に変換します。type フィールドがあることを確認します。インラインの #tags をフロントマターに移します。

CSV／スプレッドシート： 各行を 1 つの概念として扱います。列をフロントマターのフィールドに割り当てます。最初の列をファイル名にします。

---

ガードレール

1. データを決して捏造しないでください。 正しい type が分からない場合は質問してください。スキーマ情報がない場合は、省略してください。URL や列名を捏造してはいけません。
2. 不明なフィールドを保持してください。 OKF では拡張が明示的に許可されています。認識できないフィールドを削除しないでください。
3. 分類体系を押し付けないでください。 型の値は自由形式の文字列です。説明的な値を提案してもかまいませんが、想定外の型が含まれていることを理由にバンドルを拒否してはいけません。
4. リンク切れは問題ありません。 仕様では明示的に許可されています。まだ書かれていないナレッジを表しているためです。
5. デフォルトでは最小限にします。 type（必須）と、妥当な場合に限り推奨フィールドのみを生成します。空の値で水増ししないでください。
6. 決めつける前に質問してください。 ドメインが不明確な場合は、どのような型や構造が適切かを質問してください。
7. 信頼性の階層を尊重してください。 実際に人がレビューした場合に限り、human: による verified を付けてください。検証を捏造してはいけません。
8. 計算の整合性を保ってください。 Attested Computation の概念に含まれる計算は、決して編集せず、パラメーターのみを入力してください。

---

Google Cloud Knowledge Catalog 経由で提供する

Google Cloud の Knowledge Catalog は OKF バンドルをネイティブに取り込み、エージェントに提供します。これはエンタープライズ向けの方法であり、任意ですが強力です。

kcmd CLI（コードとしてのメタデータ）

kcmd は、OKF に似たローカルメタデータと Knowledge Catalog の間で双方向に同期するツールです。「メタデータのための git」と考えてください。

# Initialize from BigQuery dataset
kcmd init --bigquery-dataset <project>.<dataset>

# Pull current state from catalog
kcmd pull

# Push local changes
kcmd push --dry-run
kcmd push

エージェント統合用の MCP サーバー としても提供されています。

{
  "mcpServers": {
    "kc-mac": {
      "command": "kcmd",
      "args": ["mcp", "--path", "/path/to/root"]
    }
  }
}

MCP ツール：pull、push、list-entries、lookup-entry、modify-entry。

リファレンス・エンリッチメントエージェント

公式のエンリッチメントエージェント（Python、ADK、Gemini）は、BigQuery のメタデータから OKF バンドルを自動生成します。2 パスのアーキテクチャです。

1. BQ パス — メタデータからテーブル／ビューごとに 1 つの OKF ドキュメントを作成します
2. Web パス — LLM がシード URL をクロールし、各ページについて次のいずれかを判断します。
   • (a) エンリッチ 引用やスキーマを使って既存の概念を補強します
   • (b) 新規作成 references/<slug> ドキュメントを作成します
   • (c) スキップ 関連性のないコンテンツを除外します

制御オプション：--web-seed-file、--web-max-pages、--web-allowed-host、--no-web。

ビジュアライザー

リファレンスエージェントには、任意の OKF バンドルを自己完結型のインタラクティブな HTML ファイルとしてレンダリングする visualize サブコマンドがあります。

python -m reference_agent visualize --bundle ./bundles/<name>

機能：

• タイプごとに色分けされたノードを使った、概念の力学モデルグラフ
• フロントマターとレンダリングされたマークダウンを表示する詳細パネル
• 「引用元」へのバックリンク
• 検索とタイプによるフィルタリング

ユーザーに案内するタイミング： BigQuery データセットを拡充する場合は、リファレンスエージェントを案内してください。エンタープライズカタログとの統合を希望する場合は、kcmd を案内してください。

---

出力形式

バンドルを作成する際は、次の形式で結果を提示します。

1. ディレクトリツリー：全体の構造を表示
2. 各ファイルの内容：フェンス付きコードブロックで表示
3. 適合性チェック：バンドルが 3 つのルールに準拠していることを確認
4. 信頼性の概要（v0.2）：検証済み／未検証の件数を表示

saas-metrics/
├── index.md
├── log.md
├── metrics/
│   ├── index.md
│   ├── mrr.md
│   ├── churn.md
│   └── nps.md
└── computations/
    └── mrr-calculation.md

続けて各ファイルを表示し、最後に次のとおり確認します。

Bundle is OKF v0.2 conformant ✅
- 4 concept files
- 1 Attested Computation
- 3 human-verified, 1 unverified
- 0 stale concepts