OKF (Open Knowledge Format)의 사양을 정리해 보았다

개발 프로젝트에서는 테이블 정의, 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 관리 가능, 차이점(diff) 리뷰 용이
관계 표현	표준 Markdown 링크를 통한 cross-linking
네비게이션	index.md (디렉토리 목록), log.md (업데이트 이력)
신뢰성 보장	# Citations 섹션에서 외부 소스를 명시
소비 규칙	알 수 없는 type, 알 수 없는 필드, 깨진 링크가 있어도 거부하지 않음 (관대한 소비 모델)

OKF는 데이터와 시스템을 둘러싼 메타데이터, 컨텍스트, 큐레이션된 통찰력을 나타내기 위한, 인간과 에이전트 모두에게 친화적인 오픈 포맷입니다. 사람이 작성하고, 에이전트가 생성하며, 조직 간에 교환되고, 양쪽 모두에 의해 소비되도록 설계되었습니다.

이 포맷은 의도적으로 최소한의 구성을 가집니다: YAML frontmatter가 포함된 Markdown 파일들의 디렉토리입니다. 스키마 레지스트리(schema registry), 중앙 권위 기관, 필수 도구는 없습니다.

Google Cloud가 2026-06-12에 v0.1로 공개한 오픈 사양입니다. Markdown + YAML frontmatter 파일군으로 "조직의 지식"을 표현합니다.

OKF에서 사용되는 용어를 정리합니다.

용어	의미
Knowledge Bundle	자기 완결적인 지식의 집합. 배포의 단위. 디렉토리 트리로 표현
...

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 # 임의. 업데이트 이력
...

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 리포지토리 (Repository) (권장 — 이력, 속성, 차분이 남음)
• tarball / zip 아카이브 (Archive)
• 큰 리포지토리 내의 서브디렉토리 (Subdirectory)

다음 파일 이름들은 계층 구조의 어느 수준에서든 정의된 의미를 가지며, 컨셉 문서 (Concept documents) 용도로 사용해서는 안 됩니다.

— OKF SPEC §3.1

이 외의 .md 파일은 모두 컨셉 (Concept) 문서입니다.

• index.md
  • 디렉토리 목록 (Directory listing)
• log.md
  • 업데이트 이력 (Update history)

모든 컨셉은 UTF-8 마크다운 (Markdown) 파일입니다. 파일은 두 부분으로 구성됩니다: 1. 파일 시작 부분의 별도 줄에 있는 ---와 종료되는 ---로 구분되는 YAML 프론트매터 (YAML frontmatter) 블록. 2. 자유 형식의 콘텐츠를 포함하는 마크다운 (Markdown) 본문 (Body).

— OKF SPEC §4

각 컨셉은 UTF-8 마크다운 (Markdown) 파일입니다.

파일은 아래의 두 부분으로 구성됩니다:

• YAML 프론트매터 (YAML Frontmatter)

  • 메타데이터 (Metadata)
  • ---로 시작하여 ---로 닫힘

• 마크다운 (Markdown) 본문 (Body)

  • 자유 형식의 콘텐츠

• YAML 프론트매터 (YAML Frontmatter)

---
type: <Type 명> # 필수
title: <표시 명칭> # 권장
...

Type 값은 중앙에서 등록되지 않습니다. 생성자 (Producers)는 설명적이고 자기 설명적인 (self-explanatory) 값을 선택해야 하며 (SHOULD), 소비자 (Consumers)는 알 수 없는 타입을 유연하게 허용해야 합니다 (MUST).

— OKF SPEC §4.1

필수는 type 뿐입니다. type의 값은 중앙 관리되지 않습니다. 이해하기 쉬운 값을 자유롭게 지정할 수 있습니다 (예: BigQuery Table, API Endpoint, Metric, Playbook 등).

확장 (Extensions): 생성자 (Producers)는 임의의 추가 키를 포함할 수 있습니다 (MAY). 소비자는 라운드트립 (round-tripping) 시 알 수 없는 키를 보존해야 하며 (SHOULD), 인식되지 않는 필드가 있는 문서를 거부해서는 안 됩니다 (SHOULD NOT).

용어	의미	구체적인 예시
Producer	OKF 파일을 작성하는 측	사람, AI 에이전트 (AI agent), 생성 스크립트
Consumer	OKF 파일을 읽는 측	AI 에이전트 (AI agent), 검색 도구, Obsidian

• Producer (작성하는 측): 프론트매터 (frontmatter)에 원하는 키를 추가할 수 있습니다 (예: source:, owner:, priority: 등 무엇이든 가능).
• Consumer (읽는 측): 모르는 키가 있더라도 무시하지 않고 유지해야 합니다. "이 키를 모르기 때문에 읽을 수 없습니다"라며 거부해서는 안 됩니다.

즉, "프론트매터 (frontmatter)는 자유롭게 확장할 수 있다. 읽는 측은 그것을 파괴하지 마라"라는 규칙입니다. Source 열을 독자적으로 추가할 수 있는 것도 이 사양 덕분입니다.

생성자 (Producers)는 자유 형식의 산문 (prose)보다 구조적인 마크다운 (structural markdown) — 제목 (headings), 목록 (lists), 테이블 (tables), 코드 블록 (fenced code blocks) — 을 사용하는 것을 권장합니다 (SHOULD). 구조화는 인간의 읽기와 에이전트의 검색 (retrieval) 모두를 돕기 때문입니다.

— OKF SPEC §4.2

헤딩 (Heading)	목적 (Purpose)
# Schema	자산(asset)의 컬럼/필드에 대한 구조화된 설명.
...

---
type: BigQuery Table
title: Customer Orders
...

---
type: Playbook
title: Incident response — data freshness alert
...

개념 A에서 개념 B로의 링크는 관계를 주장합니다. 구체적인 관계의 종류(부모/자식, 참조, 조인(joins-with), 의존(depends-on) 등)는 링크 자체가 아니라 주변의 산문(prose)을 통해 전달됩니다.

— OKF SPEC §5.3

개념 간의 관계는 표준 Markdown 링크로 표현합니다. 링크의 종류(의존, 참조, JOIN 등)는 링크 자체가 아니라 주변의 문맥으로 전달합니다.

[이웃 개념](./other.md)을 참조하세요.
`customer_id`를 기준으로 [customers](/tables/customers.md)와 조인(Joined)되었습니다.

소비자는 끊어진 링크(broken links)를 반드시(MUST) 허용해야 합니다. 번들(bundle) 내에 대상이 존재하지 않는 링크라고 해서 형식이 잘못된 것은 아니며, 단지 아직 작성되지 않은 지식을 나타내는 것일 수 있습니다.

— OKF SPEC §5.3

끊어진 링크가 있어도 부정(malformed)한 것이 아닙니다. 아직 작성되지 않은 지식에 대한 참조일 수 있기 때문입니다.

index.md 파일은 번들 루트를 포함한 모든 디렉토리에 나타날 수 있습니다(MAY). 이는 점진적 공개(progressive disclosure)를 지원하기 위해 디렉토리의 내용을 나열하며, 이를 통해 인간이나 에이전트가 개별 문서를 열기 전에 무엇을 사용할 수 있는지 확인할 수 있게 합니다.

— OKF SPEC §6

임의의 디렉토리에 index.md를 두어 해당 디렉토리의 내용을 목록화할 수 있습니다. 이는 인간이나 AI가 개별 파일을 열기 전에 무엇이 있는지 파악하기 위한 메커니즘(progressive disclosure)입니다.

# Tables
* [Customer Orders](orders.md) - 완료된 고객 주문당 하나의 행
* [Customers](customers.md) - 고객 마스터 데이터

자동 생성해도, 손으로 직접 작성해도 괜찮습니다.

log.md 파일은 해당 범위(scope)의 변경 이력을 기록하기 위해 계층 구조의 어느 수준에서나 나타날 수 있습니다(MAY). 형식은 날짜별로 그룹화된 항목들의 평면 리스트(flat list)이며, 최신 항목이 가장 먼저 옵니다.

— OKF SPEC §7

log.md로 변경 이력을 기록할 수 있습니다. 최신 항목이 위로 옵니다.

# Directory Update Log
## 2026-05-22
* **Update**: [Customer Metrics](/tables/customer-metrics.md)에 대한 새로운 테이블 참조를 추가했습니다.
...

개념의 본문이 외부 자료에서 가져온 주장을 할 때, 해당 출처들은 문서 하단의 # Citations 헤딩 아래에 번호를 매겨 나열하는 것을 권장합니다(SHOULD):

어떤 개념의 본문 중에서 외부 자료에 기반한 주장을 할 경우, 해당 출처들은 문서 하단의 "# Citations" 헤딩 아래에 번호를 매겨 나열해야 합니다(SHOULD).

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

번들이 OKF v0.1을 준수하려면 다음 조건을 만족해야 합니다: 1. 트리 내의 모든 비예약(non-reserved) .md 파일이 파싱 가능한 YAML frontmatter 블록을 포함해야 합니다. 2. 모든 frontmatter 블록은 비어 있지 않은 type 필드를 포함해야 합니다. 3. 모든 예약된 파일명 (index.md, log.md)은 존재하는 경우 각각 §6 및 §7에서 설명하는 구조를 따라야 합니다.

— OKF SPEC §9

OKF v0.1에 부합하는 번들의 조건:

• 모든 비예약 .md 파일에 파싱 가능한 YAML frontmatter가 있음
• 모든 frontmatter에 비어 있지 않은 type 필드가 있음
• 예약 파일 (index.md, log.md)이 사양에 따른 구조를 따름

이 허용적인 소비 모델(permissive consumption model)은 의도된 것입니다: OKF는 번들이 성장하고, 리팩터링(refactored)되며, 에이전트(agents)에 의해 부분적으로 생성되더라도 유용성을 유지하도록 설계되었습니다.

— OKF SPEC §9

소비 측의 규칙 (허용적인 소비 모델):

• 옵션 frontmatter 필드가 누락되어도 거부하지 않음

• 알 수 없는 type 값이 있어도 거부하지 않음

• 알 수 없는 추가 필드가 있어도 거부하지 않음

• 깨진 링크가 있어도 거부하지 않음

• index.md가 없어도 거부하지 않음

• OKF 사양 자체는 매우 단순하며, 필수 사항은 type뿐입니다. 기존의 Markdown 문서에 frontmatter를 추가하는 것만으로도 준수할 수 있어 도입 장벽이 낮습니다. 허용적인 소비 모델 덕분에 단계적으로 지식을 추가해 나갈 수 있으며, 처음부터 완벽할 필요가 없습니다.

• frontmatter의 자유로운 확장이 허용되므로, 고유한 키(예: Source 열)를 추가하여 프로젝트 특유의 요구사항에 대응할 수 있습니다.

• 교차 링크(cross-linking)를 통해 개념(Concept) 간의 관계를 추적할 수 있도록 해두면, AI가 횡단적인 분석을 수행할 가능성이 있습니다. 다음에는 이를 활용하여 데이터 리니지(data lineage)의 자동 생성을 시도해 보고 싶습니다.