0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@zumax

OKF（Open Knowledge Format）の仕様を整理してみた

0
Posted at

背景・目的

開発プロジェクトでは、テーブル定義・API仕様・ダッシュボード設計などの情報がExcelやConfluence、個人のメモに散在しがちです。AIエージェント（Claude、Kiro等）に質問しても、毎回ドキュメントを掘り起こす必要があり、回答の精度も安定しません。

「設計情報を構造化してAIに読ませる」というアプローチを人から聞いて興味が湧いたので、自分でも調べてみることにしました。

本記事では、Google Cloudが2026年6月に公開した OKF（Open Knowledge Format）の仕様を整理します。

まとめ

下記に特徴をまとめます。

項目 内容
OKFとは Markdown + YAML frontmatter で組織の知識を表現するオープン仕様（Google Cloud、2026-06-12 公開 v0.1）
必須フィールド type のみ。あとは自由
構成単位 Knowledge Bundle（ディレクトリ）→ Concept（1ファイル=1知識単位）
ファイル形式 .md（UTF-8 Markdown）。Git管理可能、差分レビューしやすい
関係性の表現 標準 Markdown リンクによる cross-linking
ナビゲーション index.md（ディレクトリ一覧）、log.md（更新履歴）
信頼性の担保 # Citations セクションで外部ソースを明示
消費ルール 未知のtype、未知のフィールド、壊れたリンクがあっても拒否しない（寛容な消費モデル）

概要

OKF（Open Knowledge Format）とは

OKF is an open, human- and agent-friendly format for representing knowledge — the metadata, context, and curated insight that surrounds data and systems. It is designed to be authored by people, generated by agents, exchanged across organizations, and consumed by both.

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.

OKF SPEC v0.1

Google Cloud が 2026-06-12 に v0.1 として公開したオープン仕様です。Markdown + YAML frontmatter のファイル群で「組織の知識」を表現します。

仕様: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

用語（Terminology）

OKF で使われる用語を整理します。

用語 意味
Knowledge Bundle 自己完結したナレッジの集合。配布の単位。ディレクトリツリーで表現
Concept バンドル内の1つの知識単位。1つのMarkdownファイルで表現
Concept ID ファイルパスから .md を除いたもの（例: tables/users.md → tables/users）
Frontmatter ファイル先頭の YAML メタデータブロック（--- で囲む）
Body Frontmatter 以降の Markdown 本文
Link 他の Concept への Markdown リンク。関係性を表現
Citation 外部ソースへのリンク。主張の根拠を示す

Bundle Structure（バンドル構造）

A bundle is a directory tree of markdown files. The directory structure is independent of the domain — producers organize concepts however makes sense for the knowledge being captured.
— OKF SPEC §3

バンドルは Markdown ファイルのディレクトリツリーです。構造はドメインに依存しません。

path/to/bundle/
├── index.md              # 任意。ディレクトリ一覧（progressive disclosure）
├── log.md                # 任意。更新履歴
├── <concept>.md          # バンドルルートの Concept
└── <subdirectory>/       # サブディレクトリでグループ化
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── …

A bundle MAY be distributed as: A git repository (recommended — provides history, attribution, diffs). A tarball or zip archive of the directory. A subdirectory within a larger repository.
— OKF SPEC §3

配布形式は以下のいずれかになります。

  • Git リポジトリ（推奨 — 履歴・属性・差分が残る）
  • tarball / zip アーカイブ
  • 大きなリポジトリ内のサブディレクトリ

予約ファイル名

The following filenames have defined meaning at any level of the hierarchy and MUST NOT be used for concept documents.
— OKF SPEC §3.1

これ以外の .md ファイルは全て Concept ドキュメントです。

  • index.md
    • Directory listing
  • log.md
    • Update history

Concept Documents（コンセプトドキュメント）

Every concept is a UTF-8 markdown file. It has two parts: 1. A YAML frontmatter block, delimited by --- on its own line at the start of the file and a closing --- on its own line. 2. A markdown body, containing free-form content.
— OKF SPEC §4

  • 各コンセプトは、UTF-8のMarkdownファイル

  • ファイルは下記の2つの部分で構成されている

    1. YAML Frontmatter
      • メタデータ
      • --- で始まり、 --- で閉じられる
    2. Markdown Body
      — 本文
      • 自由形式のコンテンツ

Frontmatter

---
type: <Type名>                     # 必須
title: <表示名>                    # 推奨
description: <一行説明>            # 推奨
resource: <外部リソースURI>        # 任意
tags: [tag1, tag2]                 # 任意
timestamp: <ISO 8601>              # 任意（最終更新日時）
# … その他、独自キー自由
---

Type values are not registered centrally. Producers SHOULD pick values that are descriptive and self-explanatory; consumers MUST tolerate unknown types gracefully.
— OKF SPEC §4.1

必須は type のみ。type の値は中央管理されない。分かりやすい値を自由に付ける（例: BigQuery Table, API Endpoint, Metric, Playbook など）。

Extensions: Producers MAY include any additional keys. Consumers SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject documents with unrecognized fields.

用語 意味 具体例
Producer OKFファイルを書く側 人、AIエージェント、生成スクリプト
Consumer OKFファイルを読む側 AIエージェント、検索ツール、Obsidian
  • Producer（書く側）: frontmatter に好きなキーを追加してよい（例: source:, owner:, priority: なんでもOK）
  • Consumer（読む側）: 知らないキーがあっても無視せず保持すべき。「このキー知らないから読めません」と拒否してはいけない

つまり「frontmatter は自由に拡張してよい。読む側はそれを壊すな」というルール。Source列を独自に追加できるのもこの仕様のおかげ。

Body

Producers SHOULD favor structural markdown — headings, lists, tables, fenced code blocks — over freeform prose, since structure aids both human reading and agent retrieval.
— OKF SPEC §4.2

本文は標準 Markdown 。フリーテキストより構造的なMarkdown（見出し、リスト、テーブル、コードブロック）を使うことが推奨。以下のセクション見出しが慣例的に使われる。

Heading Purpose
# Schema Structured description of an asset's columns/fields.
# Examples Concrete usage examples, often as fenced code blocks.
# Citations External sources backing claims in the body. See §8.

Example a concept bound to a resource

---
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    | Foreign key into [customers](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Order total in US dollars.               |
| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.

# Citations

[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)

Example: a concept not bound to a resource

---
type: Playbook
title: Incident response — data freshness alert
description: Steps to triage a freshness alert on the orders pipeline.
tags: [oncall, incident]
timestamp: 2026-04-12T09:00:00Z
---

# Trigger

A freshness alert fires when `orders` lags more than 30 minutes behind
its expected SLA. See the [orders table](/tables/orders.md).

# Steps

1. Check the [ingestion job dashboard](https://example.com/dash).
2. …

Cross-linking（相互リンク）

A link from concept A to concept B asserts a relationship. The specific kind of relationship (parent/child, references, joins-with, depends-on, etc.) is conveyed by the surrounding prose, not by the link itself.
— OKF SPEC §5.3

Concept 間の関係は標準 Markdown リンクで表現する。リンクの種類（依存、参照、JOINなど）はリンク自体ではなく周囲の文脈で伝えます。

See the [neighboring concept](./other.md).
Joined with [customers](/tables/customers.md) on `customer_id`.

Consumers MUST tolerate broken links — a link whose target does not exist in the bundle is not malformed; it may simply represent not-yet-written knowledge.
— OKF SPEC §5.3

壊れたリンクがあっても不正ではありません。まだ書かれていない知識への参照かもしれないためです。

Index Files

An index.md file MAY appear in any directory, including the bundle root. It enumerates the directory's contents to support progressive disclosure — letting a human or agent see what is available before opening individual documents.
— OKF SPEC §6

任意のディレクトリに index.md を置いて、そのディレクトリの内容を一覧にできます。人間やAIが個別ファイルを開く前に、何があるかを把握するための仕組み（progressive disclosure）です。

# Tables

* [Customer Orders](orders.md) - One row per completed customer order
* [Customers](customers.md) - Customer master data

自動生成しても、手で書いてもOKです。

Log Files（更新ログ）

A log.md file MAY appear at any level of the hierarchy to record the history of changes to that scope. The format is a flat list of date-grouped entries, newest first.
— OKF SPEC §7

log.md で変更履歴を記録できます。新しいものが上です。

# Directory Update Log

## 2026-05-22
* **Update**: Added new table reference for [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).

## 2026-05-15
* **Initialization**: Created foundational directory structure.

Citations

When a concept's body makes claims sourced from external material, those sources SHOULD be listed under a # Citations heading at the bottom of the document, numbered:

ある概念の本文中で外部資料に基づく主張を行う場合、それらの出典は文書の末尾にある「# Citations」という見出しの下に、番号を付して記載すべきです。

# Citations
[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/...)
[2] [Internal data quality runbook](https://wiki.acme.internal/data/quality)

Conformance（適合性）

A bundle is conformant with OKF v0.1 if: 1. Every non-reserved .md file in the tree contains a parseable YAML frontmatter block. 2. Every frontmatter block contains a non-empty type field. 3. Every reserved filename (index.md, log.md) follows the structure described in §6 and §7 respectively when present.
— OKF SPEC §9

OKF v0.1 に適合するバンドルの条件:

  1. 全ての非予約 .md ファイルに解析可能な YAML frontmatter がある
  2. 全ての frontmatter に空でない type フィールドがある
  3. 予約ファイル（index.md, log.md）が仕様通りの構造に従っている

This permissive consumption model is intentional: OKF is meant to remain useful as bundles grow, get refactored, and are partially generated by agents.
— OKF SPEC §9

消費側のルール（寛容な消費モデル）:

  • オプションの frontmatter フィールドが欠けていても拒否しない
  • 未知の type 値があっても拒否しない
  • 未知の追加フィールドがあっても拒否しない
  • 壊れたリンクがあっても拒否しない
  • index.md がなくても拒否しない

考察

  • OKF の仕様自体は極めてシンプルで、必須は type だけ。既存の Markdown ドキュメントに frontmatter を足すだけで適合できるため、導入ハードルが低い
  • 寛容な消費モデルのおかげで、段階的に知識を追加していける。最初から完璧にする必要がない
  • frontmatter の自由拡張が許されているため、独自のキー（例: Source列）を追加してプロジェクト固有のニーズに対応できる
  • cross-linking で Concept 間の関係を辿れるようにしておけば、AIが横断的な分析を行える可能性がある。次回はこれを活用してデータリネージュの自動生成を試したい

参考

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?