📂 技術調査 - OKF (Open Knowledge Format)

OKF (Open Knowledge Format) は、Google Cloud が 2026 年 6 月に公開した「AIエージェントが読む知識を、どのファイル形式で持つか」を定める軽量フォーマットです。サービスでもプラットフォームでもなく、YAML frontmatter 付き markdown ファイルのディレクトリツリーという取り決めに過ぎません。本記事は spec 原文とリポジトリ実体を一次ソースとして、OKF の構造・データモデル・導入手順・運用までを整理します。

2026 年 7 月に公開された v0.2 の信頼信号、trust tier、Attested Computation は、エージェント知識の信頼信号を記述する形式 - OKF v0.2 で扱っています。

概要

OKF とは何か

OKF は、AIに読ませる知識(テーブル定義・メトリクス・Runbook・ジョイン経路など)を、人間も機械も読めて git で差分管理できる形で置くためのフォーマットです。spec 原文は次のように定義します。

OKF is an open, human- and agent-friendly format for representing knowledge — the metadata, context, and curated insight that surrounds data and systems.
The format is intentionally minimal: a directory of markdown files with YAML frontmatter. There is no schema registry, no central authority, and no required tooling. If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.
（出典: okf/SPEC.md 冒頭）

README は「universal, vendor-neutral format」、ブログは「Format, not platform.」と表現し、特定のクラウド・DB・モデルプロバイダ・エージェントフレームワークに縛られないことを宣言しています。

位置づけ — 「知識をファイルとして整える」層

spec §10 は近縁パターンとして次の 3 つを自認し、OKF の差別化点を「これらに対して specified である(相互運用に必要な最小規則を固定しつつツールを強制しない)」点に置きます。

• LLM "wiki" repositories — markdown + frontmatter をエージェント可読知識ベースとして使う手法。
• Personal knowledge tools — Obsidian・Notion のような階層 markdown + クロスリンク。
• "Metadata as code" — カタログメタデータをレジストリでなくソースコードと並べて管理する手法。

なお、公式は OKF を RAG の代替として名指しで差別化してはいません。spec 本文に "RAG" / "embedding" / "vector" の語はありません。ブログの「同じ文書を何度も検索させる代わりに、育っていく共有ライブラリをエージェントに与える」というフレーミングは RAG 的な都度検索との対比として読めますが、「vs RAG」と明示した一次記述は確認できませんでした。本ドキュメントでは「RAG/KG を作る前段で知識をファイルとして整える層」という positioning として扱います。

リポジトリ・公開情報

特徴

設計軸: Readable / Parseable / Diffable / Portable

spec §1 Motivation が掲げる 4 軸です(原文見出し)。

ニュース記事等で見られる「vendor-neutral / human-readable / agent-parseable / version-control-first」の 4 語は、spec 原文のこの軸を言い換えたものです。spec 本文にこの 4 語そのままの列挙はありません("vendor-neutral" は README の定義文中の修飾語として登場します)。spec §1 は設計姿勢を "minimally opinionated" と明示し、「知識コーパスを self-describing にするのに必要な最小の構造的規約だけを標準化し、それ以外は producer に委ねる」としています。

conformance の「極小契約」

OKF v0.1 が producer(書き手)に要求するのは、驚くほど少ない 2 点です。

• すべての非予約 .md ファイルが、parse 可能な YAML frontmatter を持つこと。
• その frontmatter が、空でない type フィールドを 1 つ持つこと。

ブログは「OKF requires exactly one thing of every concept: a type field.」と表現します。frontmatter の任意フィールドは title / description / resource / tags / timestamp で、独自の拡張キーも自由に追加できます。予約ファイル名は index.md(ディレクトリの入口)と log.md(変更履歴)の 2 つのみです。

permissive consumption model（寛容な消費モデル）

consumer(読み手)に対しては、spec §9 が強い MUST NOT を課します。「壊れていても止まるな、読める範囲を読め」という思想です。

• 未知の type で document を拒否してはならない。
• 未知の frontmatter キーで拒否してはならない。
• 任意フィールドが欠けていることで拒否してはならない。
• リンク切れ(broken link)で拒否してはならない。
• index.md が無いことで拒否してはならない。

型タクソノミーを定めない

type: BigQuery Table のような値はサンプル中に登場しますが、これらは example value に過ぎません。spec の Non-goals に「Defining a fixed taxonomy of concept types」が明記され、定義済み type のレジストリは存在しません。ファイル間のリンクも 型なし(untyped)の有向辺で、関係種別は frontmatter ではなく本文の散文(prose)で表現します(spec §5.3)。

git native と reference 実装

バンドル(配布単位)は git repo / tarball / 大きい repo のサブディレクトリのいずれでも配布でき、テキストである以上 git の差分管理・PR レビューがそのまま効きます。リポジトリには動かせる参照実装が同梱されています。

• Enrichment Agent — Google ADK + Gemini による producer PoC。BigQuery を最初の source として、BQ pass(メタから 1 concept = 1 doc)と web pass(LLM が seed URL をクロールして enrich)の 2 段構成。
• Static HTML Visualizer — OKF バンドルを自己完結 interactive HTML に変換する consumer PoC。Cytoscape.js の force-directed graph と type フィルタを持つ。
• Sample bundles — ga4 / stackoverflow / crypto_bitcoin の 3 つ(いずれも BigQuery public dataset 由来)。

他形式との比較

「AIが読む知識をどのファイル形式で持つか」という空間には、既に複数の層が存在します。層を A(指示書)/ B(セマンティクス記述、OKF の主戦場)/ C(プロトコル・手法)で定義します。

最近接の Croissant は MLCommons が steward で、vendor-neutral・機械可読(JSON-LD)・Web discoverable・MCP 連携実証済み(2025-10)という条件を既に満たします。ただし Croissant は ML データセットに特化し、テーブル定義・メトリクス・Runbook・API 知識などの汎用業務知識は OKF のカバー範囲です。

構造

OKF は「形式 + reference 実装」なので、C4 model を「OKF エコシステムの論理構造」に読み替えて図示します。

システムコンテキスト図

システムコンテキスト要素

コンテナ図

同一リポジトリ内に、純粋な OKF を担う Python 実装(okf/)と、Knowledge Catalog 製品寄りツールチェーンの TypeScript 実装(toolbox/)が同居します。

okf サブグラフ要素

toolbox サブグラフ要素

OKF(okf/)と製品の Metadata as Code(toolbox/)は別表現です。OKF は Knowledge Catalog 製品の交換フォーマットではなく、toolbox/mdcode/demo/okf/ が catalog→OKF の橋渡し demo を示すにとどまります。

コンポーネント図

OKF バンドル内部の構成要素を示します。

バンドルルート要素

Concept Document 内部要素

Concept ID 規約

データ

概念モデル

Bundle がすべてを包み、その中に ConceptDocument と ReservedFile が共存します。ConceptDocument は Frontmatter・Body・Tag・Resource を持ち、Bundle 内の他 ConceptDocument へ CrossLink で参照します。

Tag と Resource は Frontmatter の任意フィールドとして保持されますが、概念的に独立したエンティティとして扱えるため分離して示しています。index.md はバンドルルートに限り frontmatter(okf_version 宣言)を持てます(spec §11)。

情報モデル

各エンティティの主要属性と多重度を示します。概念モデルとエンティティを一致させています。

主要エンティティの属性

concept_id / file_path / is_broken は spec の記述から導出した推測属性です。conformance の実質は spec §9 の 3 点(全非予約 .md が parseable な frontmatter + 空でない type / 予約ファイルは §6・§7 構造に従う)のみです。

構築方法

OKF は「ディレクトリ + Markdown + YAML frontmatter」だけで完結します。専用サーバも SDK も不要で、git clone と任意のテキストエディタがあれば始められます。

reference 実装を動かす前提条件

okf/ に Enrichment Agent(producer PoC)と Static HTML Visualizer(consumer PoC)が含まれます。

• Python 3.11 以上(pyproject.toml の requires-python = ">=3.11")
• Google Cloud プロジェクト(BigQuery を使う場合は API 有効化・課金設定が必要)
• Gemini API キー(AI Studio 発行の GEMINI_API_KEY)または Vertex AI 認証

# 1. リポジトリを clone
git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/okf

# 2. Python 仮想環境を作成してパッケージをインストール
python3 -m venv .venv
.venv/bin/pip install -e .[dev]

# 3. BigQuery 認証（公開データセットの読み取りにも呼び出し側プロジェクトへの課金が発生する）
gcloud auth application-default login
gcloud config set project <your-billing-project>

# 4. Gemini 認証（AI Studio の場合）
export GEMINI_API_KEY=<your-key>

Vertex AI を使う場合は GEMINI_API_KEY の代わりに次を設定します。

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=<project-id>
export GOOGLE_CLOUD_LOCATION=<region>

Enrichment Agent を実行する（サンプルレシピ）

samples/ga4_merch_store/ に BigQuery 公開データセット向けのレシピが用意されています。

pip install -e . で生成される console script は enrichment-agent(pyproject.toml の [project.scripts] enrichment-agent = "enrichment_agent.cli:main")です。

.venv/bin/enrichment-agent enrich \
    --source bq \
    --dataset bigquery-public-data.ga4_obfuscated_sample_ecommerce \
    --web-seed-file samples/ga4_merch_store/seeds.txt \
    --out ./bundles/ga4_merch_store

• --out(出力先バンドルディレクトリ)は 必須フラグです。
• --no-web で Web pass を省略し BQ pass のみ実行できます。
• --concept tables/events_ で対象 concept を絞れます(複数指定可、繰り返し使用)。
• --web-max-pages N(デフォルト 100)で Web クロール上限を変更できます。

実行後、./bundles/ga4_merch_store/ に各テーブル・データセットが 1 ファイル = 1 concept の OKF バンドルとして生成されます。

Visualizer を実行する

.venv/bin/enrichment-agent visualize --bundle ./bundles/ga4_merch_store

バンドルルート直下に viz.html が生成されます。バックエンド不要の自己完結 HTML で、ブラウザで開くだけで concept グラフを閲覧できます。

OKF バンドルをゼロから作る最小手順

reference 実装を使わず手書きで作る手順です。

mkdir -p my-bundle/tables
mkdir -p my-bundle/metrics

各知識の単位を 1 つの .md ファイルとして作成します。my-bundle/tables/orders.md の例(spec §4.3 より):

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column        | Type      | Description                              |
|---------------|-----------|------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.        |
| `customer_id` | STRING    | FK を [customers](/tables/customers.md) に持つ。 |
| `total_usd`   | NUMERIC   | 注文合計（米ドル）。                      |

# Joins

`customer_id` で [customers](/tables/customers.md) と結合する。

完成したバンドルのディレクトリ構成:

my-bundle/
├── index.md          # オプション: ルートのディレクトリ一覧
├── log.md            # オプション: 更新履歴
├── tables/
│   ├── index.md      # オプション
│   ├── orders.md     # concept document
│   └── customers.md  # concept document
└── metrics/
    ├── index.md
    └── weekly_active_users.md

index.md はプログレッシブ開示用のディレクトリ一覧(frontmatter を持たない)、log.md は ISO 8601 日付見出しで新しい順に並ぶ更新履歴です。log.md の例(各見出しの先頭に **Update** / **Creation** / **Deprecation** を付けるのが慣習):

## 2026-06-13

**Creation** — `tables/orders.md` を初稿追加。

## 2026-06-10

**Update** — `tables/customers.md` の Schema に `email` 列を追記。

利用方法

frontmatter フィールド一覧

type のみが唯一の必須フィールドです(spec §4.1 原文: 「A short string identifying the kind of concept.」)。型の語彙はレジストリで管理されず、consumer は未知の type を拒否してはならず(MUST NOT)、典型的には generic concept として扱います。

concept document の書き方

最小構成(type のみ):

---
type: Metric
---

週次アクティブユーザー数。

任意フィールドと本文セクションを加えた実用的な構成(本文の SQL ブロックは body の一部):

---
type: Metric
title: Weekly Active Users
description: 過去 7 日間に 1 回以上イベントを発火したユニークユーザー数。
tags: [engagement, kpi]
timestamp: 2026-06-13T00:00:00Z
---

# 定義

`event_date` が直近 7 日以内かつ `event_name != 'session_start'` のユーザー数を
`user_pseudo_id` で distinct count したもの。

# 計算方法

```sql
SELECT COUNT(DISTINCT user_pseudo_id) AS wau
FROM `project.dataset.events_*`
WHERE _TABLE_SUFFIX BETWEEN
  FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY))
  AND FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY))
```

本文のセクション見出し(# Schema、# Examples、# Citations など)は仕様上の慣習で、必須ではありません(spec §4.2: 「There are no required body sections.」)。

cross-link の張り方

concept 間のリンクは通常の Markdown リンクで表現します。リンク自体は「関係の存在」を示すだけで、関係の種別(JOIN・依存・参照など)は周囲の散文で記述します(spec §5.3)。

# Joins

`customer_id` で [customers](/tables/customers.md) に結合する（LEFT JOIN）。

# Dependencies

このメトリクスは [orders](/tables/orders.md) の `total_usd` 列に依存する。
`orders` が更新されるたびに再計算が必要。

/ で始めるとバンドルルートからの絶対パスとして解釈され、ファイルをサブディレクトリ内で移動しても壊れません(spec §5.1 推奨)。同じディレクトリ内は ../tables/events_.md のような相対リンクも使えます。

consumer 側 permissive parsing の作法

OKF v0.1 の conformance は consumer に明示的な「拒否禁止」ルールを課します(spec §9)。ここで区別したいのは、permissive consumption が対象とするのは「conformant な document に未知の type / 未知キー / 任意フィールド欠落 / broken link / index.md 欠落があるケース」だという点です。type の欠落や parse 不能な frontmatter は **conformance 違反(producer 側の不備)**であり、permissive の許容対象ではありません。次のコード例はそうした非 conformant ファイルにも防御的に振る舞いますが、本来は producer 側の CI(後述)で弾くべきものです。

import os
import yaml

RESERVED = {"index.md", "log.md"}

def parse_okf_document(content: str) -> dict:
    """未知フィールド・未知 type・broken link があっても reject しない。"""
    if not content.startswith("---"):
        return {"type": "Unknown", "body": content}
    parts = content.split("---", 2)
    if len(parts) < 3:
        return {"type": "Unknown", "body": content}
    try:
        frontmatter = yaml.safe_load(parts[1]) or {}
    except yaml.YAMLError:
        # パース失敗はスキップ/ログにとどめ例外を伝播させない
        return {"type": "Unknown", "body": parts[2].strip()}
    # 未知キーは保持、未知 type も通常 concept として扱う
    return {**frontmatter, "body": parts[2].strip()}

def load_bundle(bundle_root: str) -> list:
    concepts = []
    for dirpath, _, filenames in os.walk(bundle_root):
        for filename in filenames:
            if not filename.endswith(".md") or filename in RESERVED:
                continue
            filepath = os.path.join(dirpath, filename)
            with open(filepath, encoding="utf-8") as f:
                concept = parse_okf_document(f.read())
            rel = os.path.relpath(filepath, bundle_root)
            concept["_id"] = rel.replace("\\", "/").removesuffix(".md")
            concepts.append(concept)
    return concepts

拒否してはいけない(MUST NOT)ケースの一覧:

運用

git による知識台帳の差分管理

OKF バンドルはテキストの集合体なので、git の差分管理がそのまま「セマンティクスの変更履歴」になります。

• okf/ ディレクトリを通常のソースコードと同一リポジトリに置き、feature branch で更新する。
• git diff が「concept のどのフィールドが変わったか」「どのリンクが追加・削除されたか」を行単位で示す。
• PR レビューで、意味的な変更(定義の書き換え・table schema の変更・metric の再定義)を人間がゲートとして確認する。

catalog API からの CI 再生成（living contract 運用）

人手で書いた concept document は数週間でドリフトします[二次情報: Atlan "How to Write an AGENTS.md"]。鮮度維持には CI による自動再生成が現実的です。ファイルヘッダに provenance を明記し、自動生成セクションと人手メンテセクションを分離します。次の例の scripts/generate_okf.py は自前で用意する想定のスクリプトです(OKF repo に同梱されるものではありません。reference 実装を使うなら enrichment-agent enrich --source bq --out okf/ に置き換えられます)。

# .github/workflows/okf-refresh.yml
on:
  schedule:
    - cron: '0 2 * * 1'   # 毎週月曜 02:00 UTC
  push:
    paths:
      - 'schema/**'
jobs:
  regenerate-okf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Regenerate OKF from catalog
        run: python scripts/generate_okf.py --source bq --output okf/
      - name: Commit diff
        run: |
          git config user.name "okf-bot"
          git add okf/
          git diff --cached --quiet || git commit -m "chore(okf): auto-regenerate from catalog"
      - name: Open PR
        uses: peter-evans/create-pull-request@v6

CI 再生成のスコープは table/dataset concept に絞り、metric/runbook の意味定義は人手で維持する使い分けが現実的です。

CI での OKF バンドル検証（PR ゲート）

OKF spec は consumer 側に permissive を求めますが、producer 側の品質は CI でゲートにできます。次の okf_lint.py も自前で用意する lint スクリプトの例です(OKF repo には同梱されません)。

python scripts/okf_lint.py okf/ \
  --require-type \
  --check-links \
  --check-timestamps

• type フィールドの必須チェック(空/欠損の検出)
• 内部リンクの死活チェック([customers](/tables/customers.md) 等の lint)
• timestamp の ISO 8601 形式検証
• 同一スコープ内の重複 title 検出

知識の鮮度維持と stale 対策

spec は timestamp を任意フィールドとし、鮮度の強制力は仕様レベルにありません。timestamp を producer 規約として必須化(無い PR は merge しない CI ゲート)し、stale 閾値(例: 30 日)を超えた concept を検出して通知する運用補強を推奨します。

Caveat: stale な知識レイヤーはレイヤー無しより悪い(ground truth を装うため)という指摘があります[二次情報: trysteakhouse "Self-Healing Knowledge Base"]。AI agent は知識の古さを内在的に疑えません。鮮度維持はフォーマット標準化では解けず、運用で別途設計すべき課題です。

ベストプラクティス

Data Contract Specification との補完的な組み合わせ

OKF と Data Contract Specification は競合せず補完関係にあります。

OKF の table concept は「人間向け説明・join path・業務定義」に限定し、スキーマの source of truth は Data Contract に一本化、OKF から Data Contract へリンクを張ることで二重定義を避けます。

dataContractSpecification: 1.2.1
id: orders-latest
info:
  title: Orders
  version: "2.0.0"
  owner: data-platform-team
models:
  orders:
    fields:
      order_id: { type: string, required: true }
      customer_id: { type: string }
servicelevels:
  freshness:
    description: Data is updated every hour
    threshold: 1h

管理対象をテーブル定義以外に広げる

OKF は型タクソノミーを固定しないため、type の値を組織で自由に決められます。

社内ルールの certified 定義の例:

---
type: metric
title: Net Revenue
tags: [finance, certified]
timestamp: 2026-06-13T00:00:00Z
---

# 定義
net_revenue = gross_revenue - returns - discounts
（returns after 30 days は除外する）

# PII・制約
集計に個人情報カラムは使用しない。
`orders_raw` / `orders_staging` は参照禁止。必ず `certified_orders_v2` を使用する。

Croissant との使い分け

• Croissant を選ぶ場面: ML データセットのメタを機械的・推論可能な形で外部公開・共有したい(Hugging Face / Kaggle 連携、構造化ファクトの共有)。
• OKF を選ぶ場面: チーム内の知識(テーブル/メトリクス/Runbook/API)を人間も AI も読める台帳として git 運用したい。型の厳密性より記述の柔軟性・可読性を優先する。

Caveat（類推・二次情報）: JSON-LD ベースの Croissant は hallucination 低減に有利という指摘があります[二次情報: stonegatewebsecurity "JSON-LD vs Markdown for AI Visibility"]。OKF の散文本文は LLM に読みやすい一方で意味の明示では劣るため、エージェントの解釈ブレが許容できない用途では Croissant を先に評価してください。

セキュリティ: markdown への prompt injection 混入リスク

AI が読む markdown 台帳は prompt injection の運搬体になり得ます。エージェント向けファイルへの prompt injection は約 26.1%(42,447 件スキャン)の対象に出現し、自然言語 3 行で agent 挙動を乗っ取れると報告されています[二次情報: Agent Skills スキャン研究。OKF 固有の実証ではなく類推]。OKF は本文が完全自由形式で、permissive 消費(未知 type・壊れたリンクでも止まらない)を求められ、組織横断の交換を前提とするため攻撃面を広げ得ますが、spec に緩和策の記述はありません。

# CI での簡易 injection パターン検出例（完全ではない）
grep -riE "(ignore (previous|all) instructions|disregard|override your|you are now)" okf/ \
  && echo "WARN: potential prompt injection patterns detected"

形式的検出には限界があるため、社外取得 bundle はそのまま agent に読ませず、CI 検出 + 人手レビューを経て、信頼できる出所の台帳のみを agent に読ませる運用ポリシーが根本対策です。

トラブルシューティング

まとめ

OKF (Open Knowledge Format) は、AIが読む知識を中央権威もスキーマレジストリも要求しない type 付き markdown + git 台帳として整える最小フォーマットで、その設計思想は OKF の普及を待たず 今日から手元のリポジトリで実践できます。一方で v0.1 Draft・採用実績ゼロ・Google 単独ガバナンスという段階であり、本番標準として採るのは時期尚早です。鮮度維持・prompt injection・標準乱立といった、フォーマット標準化だけでは解けない課題は運用側で別途設計してください。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

OKF 一次ソース

• Google Cloud Blog — How the Open Knowledge Format can improve data sharing
• GitHub: GoogleCloudPlatform/knowledge-catalog
• OKF SPEC.md (v0.1 Draft)
• OKF README
• サンプルバンドル GA4
• サンプルレシピ GA4
• Knowledge Catalog 製品ページ

周辺・競合フォーマット

• AGENTS.md（Agentic AI Foundation）
• Croissant（MLCommons）
• Croissant × MCP
• schema.org/Dataset
• Data Contract Specification
• dbt — contract config

運用・反証・関連

• Atlan — How to Write an AGENTS.md File
• Soda — Guide to Data Contracts
• trysteakhouse — The Self-Healing Knowledge Base
• fieldnotesondata — How Not to Run an Open Standards Initiative
• arxiv — Agent Skills Enable a New Class of Realistic and Trivially Simple Prompt Injections
• OWASP — LLM Prompt Injection Prevention Cheat Sheet
• stonegatewebsecurity — JSON-LD vs Markdown for AI Visibility