Open Knowledge Format (OKF)

요약

OKF(Open Knowledge Format)는 데이터와 시스템을 둘러싼 지식을 YAML frontmatter가 달린 markdown 파일의 디렉토리로 표현하는 벤더 중립 포맷이다. 명세가 말하는 지식은 메타데이터와 컨텍스트, 그리고 큐레이션된 통찰을 아우른다. 스키마 레지스트리도 중앙 권위도 필수 도구도 없으며, 명세는 이 최소주의를 "cat으로 읽을 수 있으면 OKF를 읽는 것이고, git clone할 수 있으면 배포하는 것이다"라는 문장으로 요약한다.

v0.2 명세의 출발점은 지식 코퍼스가 사람이 한 번 쓰고 읽는 자료에서 에이전트가 계속 작성하고 유지하는 자료로 바뀌고 있다는 진단이다. 대부분의 concept이 기계가 만든 것이라면 소비자는 이 문서가 무엇에서 왔는지, 얼마나 믿을 수 있는지, 아직 사실인지, 현행 버전인지, 수치가 정해진 방식대로 계산됐는지를 물어야 한다. v0.2는 이 가운데 provenance, trust, lifecycle, attestation을 frontmatter의 1급 항목으로 올렸다.

저장소가 앞세우는 기여는 포맷 자체다. 동봉된 reference agent는 BigQuery 메타데이터와 웹 문서에서 bundle을 자동 생산하는 PoC이고, visualize 서브커맨드는 bundle을 자기완결 HTML 한 장으로 렌더하는 PoC 소비자다. README는 두 도구가 포맷을 생산과 소비 양단에서 만질 수 있게 하는 장치일 뿐이라고 명시한다.

이 페이지의 근거는 raw에 있는 README.md와 SPEC.md 두 파일이다. 소스 코드, 테스트, 체크인된 bundle 산출물은 raw에 없으므로 내부 구현은 다루지 않는다. 라이선스도 README 본문에 조항이 없어 frontmatter 값(Apache-2.0)을 현재 자료로는 검증할 수 없다.

배경

에이전트가 유지하는 코퍼스

명세 1절은 AI 에이전트를 위한 지식 표현 공간이 빠르게 진화하면서 서로 호환되지 않는 규약이 많이 생기고 있다고 진단한다. OKF는 지식이 널리 접근 가능한 기성 포맷으로 표현되어야 한다는 입장을 취하며, 그 포맷이 갖춰야 할 성질을 네 가지로 든다.

평범한 markdown과 frontmatter 규약으로는 부족한 지점이 있다. 코퍼스의 대부분을 에이전트가 쓰는 상황에서 소비자에게 필요한 질문이 다섯 가지인데, 기존 규약은 이 질문의 답을 1급 항목으로 만들지 않는다.

명세는 이어서 v0.2가 provenance, trust, lifecycle, attestation을 1급으로 만들면서도 포맷을 최소 규정으로 유지한다고 적는다. freshness는 별도 계열 이름 없이 lifecycle 계열의 stale_after가 담당한다. 표준화 대상은 지식 코퍼스를 자기 기술적(self-describing)으로 만드는 데 필요한 소수의 구조 규약뿐이고, 그 너머는 전부 생산자에게 맡긴다.

목표와 비목표

비목표 1과 4는 이 포맷의 성격을 규정하는 결정이다. 타입 어휘를 중앙에 등록하지 않으므로 소비자는 모르는 타입을 만나는 것이 정상 상황이고, 계산 코드의 패키징을 규정하지 않으므로 같은 계약 아래 스킬, 스크립트, 컨테이너가 모두 놓일 수 있다.

파일 기반 선택이 주는 성질

README의 "Why OKF?" 절은 서비스가 소유하는 메타데이터 저장소와 대비해 평범한 markdown 디렉토리가 주는 성질 9개를 나열한다.

README는 이 아홉 성질의 총합을 "reference agent, 소비 에이전트, 사람이 소스 코드에서 이미 협업하는 방식 그대로 같은 산출물 위에서 협업하게 된다"고 정리한다.

핵심 개념

생산자와 소비자

OKF는 쓰는 쪽과 읽는 쪽을 생산자(producer)와 소비자(consumer)로 나누어 부른다. README는 어느 쪽에도 특정 도구를 전제하지 않는다는 점을 강조한다.

bundle, concept, link

명세 2절은 열다섯 개 용어를 정의한다. 구조에 관한 용어를 먼저 보면 다음과 같다.

concept는 bundle 안 지식의 최소 단위로 markdown 문서 하나에 해당한다. 예를 들어 tables/orders.md라는 파일은 concept ID가 tables/orders인 concept이고, 이 문서가 /tables/customers.md를 링크하면 두 concept 사이에 관계가 있다는 사실이 그래프에 기록된다.

provenance, trust, attestation의 구분

v0.2의 핵심은 서로 다른 세 질문을 서로 다른 frontmatter 계열로 분리했다는 점이다. 셋을 구별하지 않으면 "출처가 믿을 만하다"와 "이 수치가 정확하다"가 뒤섞인다.

나머지 용어는 이 구분을 뒷받침한다.

신호와 점수

OKF가 신뢰를 다루는 방식은 "신호를 기록하고 점수를 저장하지 않는다"는 원칙으로 압축된다. 명세는 credibility score를 저장하지 않는 이유를 세 가지로 든다. 점수는 주관적이고, 소비자 사이에서 이식되지 않으며, 시간이 지나면 낡는다. 그래서 source마다 누가 만들었는지, 얼마나 쓰이는지, 언제 바뀌었는지 같은 객관적 사실만 남기고, 그 사실을 어떻게 해석할지는 소비자가 정한다. trust tier도 같은 원칙을 따라 verified 필드에서 소비자가 유도할 뿐 어디에도 저장되지 않는다.

progressive disclosure

progressive disclosure는 bundle 전체를 컨텍스트에 올리지 않고 계층을 한 단계씩 열어보게 하는 설계다. OKF에서는 각 디렉토리의 index.md가 이 역할을 맡는다. 사람이나 에이전트는 index를 읽어 그 디렉토리에 무엇이 있는지 먼저 파악한 뒤 필요한 문서만 연다.

방법

bundle 구조와 배포

bundle은 markdown 파일의 디렉토리 트리다. 디렉토리 구조는 도메인과 독립적이며 생산자가 지식의 성격에 맞게 자유롭게 짠다. 명세가 보이는 배치 예시는 루트에 index.md, log.md, concept 파일이 놓이고 하위 디렉토리마다 다시 index.md와 concept 파일이 반복되는 구조다.

예약된 파일명은 둘뿐이다. 계층의 어느 위치에서든 정해진 의미를 가지며 concept 문서로 쓸 수 없다(MUST NOT). 나머지 모든 .md는 concept 문서다.

태그는 tags frontmatter 필드로 1급 개념이지만 태그별로 문서를 모으는 별도 파일 포맷은 없다. 태그 열람 뷰가 필요한 소비자는 소비 시점에 frontmatter를 훑어 직접 합성한다. 즉 파일 포맷은 원천 데이터만 정하고 뷰는 소비자 몫이다.

concept 문서의 frontmatter

모든 concept은 UTF-8 markdown 파일이고 YAML frontmatter 블록과 markdown 본문 두 부분으로 이루어진다. frontmatter 키는 필수, 권장, 선택 계열, 확장으로 나뉜다.

type은 유일한 상시 필수 키이며 type만 가진 concept도 완전히 적합(conformant)하다. 명세가 든 예시 값은 BigQuery Table, BigQuery Dataset, API Endpoint, Metric, Playbook, Reference, Attested Computation이다. 이 값들은 중앙에 등록되지 않는다. 생산자는 설명적이고 자명한 값을 고르고(SHOULD) 소비자는 모르는 타입을 일반 concept으로 다루어 견뎌야 한다(MUST). 따라서 어떤 조직이 Kafka Topic이라는 타입을 만들어 써도 다른 소비자는 그 문서를 거부하지 않고 일반 concept으로 표시한다.

본문 구조와 관용 헤딩

본문은 표준 markdown이다. 명세는 자유 산문보다 헤딩, 목록, 표, 코드 펜스 같은 구조적 markdown을 권한다(SHOULD). 구조가 사람의 읽기와 에이전트의 retrieval 모두에 도움이 되기 때문이다. 필수 본문 절은 없고 관용 헤딩 셋이 있다.

명세는 두 종류의 concept 예시를 든다. 첫째는 resource가 있는 concept이다. type: BigQuery Table인 Customer Orders 문서는 resource에 BigQuery 콘솔 URL을 두고, generated에 reference_agent/gemini-2.5-pro를 적고, 본문 # Schema 표에 order_id, customer_id, total_usd, placed_at 네 컬럼을 두며 customer_id 설명에서 /tables/customers.md를 링크한다. 둘째는 resource가 없는 concept이다. type: Playbook인 데이터 신선도 경보 대응 문서는 generated.by가 human:ahormati이고 본문에 # Trigger와 # Steps 절을 둔다. 두 예시는 실체 자산과 추상 절차가 같은 골격을 공유한다는 점을 보여 준다.

첫째 예시의 전문은 다음과 같다. resource가 실제 BigQuery 테이블을 가리키고 본문의 # Schema 표와 # Joins 절이 다른 concept을 링크한다.

---
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]
generated: { by: reference_agent/gemini-2.5-pro, at: 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`.

둘째 예시는 resource 없이 사람이 쓴 절차 문서다. generated.by가 human:ahormati라서 이 문서를 확인하는 소비자는 actor 규약만으로 사람이 작성했음을 안다.

---
type: Playbook
title: "Incident response: data freshness alert"
description: Steps to triage a freshness alert on the orders pipeline.
tags: [oncall, incident]
generated: { by: human:ahormati, at: 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. ...

외부 source에 대한 주장별 귀속은 본문 인용 목록이 아니라 sources 항목에 연결된 markdown 각주로 한다. 이 방식은 provenance 절에서 다시 다룬다.

provenance 기록

provenance, trust, lifecycle 세 계열은 "어디서 왔는가", "얼마나 믿을 것인가", "아직 현행인가"를 frontmatter만으로 답하게 만든다. 전부 optional이지만 부재 자체가 의미를 가진다. 검증되지 않은 concept은 검증된 것과 구별되지만 거부되지는 않는다. OKF의 모든 시각 값은 UTC 오프셋을 명시한 ISO 8601 datetime이며 예시는 2026-06-30T14:00:00Z다.

sources는 concept이 파생된 재료를 기록한다. 항목마다 다음 필드를 가진다.

명세 예시는 id: ga4-schema, resource에 GA4 BigQuery Export 스키마 문서 URL, author: team:ga4-docs, usage_count: 5000, last_modified: 2026-05-30T00:00:00Z를 가진 항목 하나와, 형제 키 usage_window: { from: 2026-06-01, to: 2026-06-30 }다.

세 신뢰도 신호는 각각 다른 질문에 답한다.

usage_window는 sources의 형제 키로 한 번 적어 모든 usage_count에 { from, to } 구간을 부여한다. 개별 항목이 자기 usage_window를 가져 공유 값을 덮어써도 된다(MAY). 구간이 없는 사용 횟수는 의미가 없으므로 이 키가 usage_count의 전제가 된다.

usage_count는 명세 스스로 거친 신호라고 못 박는 값이다. 살아 있는지 죽었는지, 자릿수가 어느 정도인지, 그 source 자신의 과거 이력과 비교해 어떤지 수준에서만 비교할 수 있고, 종류가 다른 source 사이의 정밀한 순위로는 쓸 수 없다. 예약 질의의 실행 횟수와 사람이 일부러 본 대시보드 조회 수는 같은 무게가 아니기 때문이다. 따라서 소비자는 이 값을 생존과 추세로 읽어야 한다(SHOULD).

lineage는 별도 필드가 아니라 링크로 표현한다. resource가 같은 bundle의 다른 concept을 가리키면 파생 엣지는 이미 bundle 그래프에 있으므로, 소비자는 그 source의 sources로 재귀해 신뢰도를 전파시켜도 된다(MAY). 외부 말단 source는 자기 고유 신호만 갖는다. 명시적 외부 derived_from이나 데이터 lineage 같은 더 깊은 lineage는 v0.2 범위 밖이다.

주장별 귀속은 라벨이 sources[].id와 같은 markdown 각주로 한다. 명세 예시는 다음과 같다.

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

[^ga4-schema]: GA4 BigQuery Export schema

각주 라벨이 sources로 들어가는 조인 키이고, 소비자는 각주 산문을 파싱하지 않고 일치하는 항목으로 귀속을 해석한다. 라벨을 위치(sources[0])가 아니라 키로 두는 이유는 에이전트가 이 문서들을 끊임없이 다시 쓰기 때문이다. 목록 순서가 바뀌는 순간 위치 인덱스는 조용히 엉뚱한 source를 가리키지만, 안정적 id는 순서가 바뀌어도 같은 항목을 가리킨다.

trust 기록

generated는 현재 내용이 어떻게 만들어졌는지, verified는 누가 또는 무엇이 그 내용을 source나 resource와 대조해 확인했는지 기록한다. 쓴 주체와 확인한 주체가 같을 이유가 없어서 둘을 분리한다. 예를 들어 에이전트가 문서를 쓰고 재무 담당자가 승인하는 경우 generated.by는 에이전트, verified[].by는 사람이 된다.

verified가 목록인 이유는 독립적 검사 여러 건을 담기 위해서다. 명세 예시는 human:ahormati의 승인(2026-06-25)과 process:finance-nightly의 야간 점검(2026-06-26) 두 항목이다.

generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified:
  - { by: human:ahormati, at: 2026-06-25T09:00:00Z }
  - { by: process:finance-nightly, at: 2026-06-26T02:00:00Z }

이 예시에서 concept은 에이전트가 6월 20일에 썼고, 사람이 6월 25일에, 야간 프로세스가 6월 26일에 각각 확인했다. "얼마나 최근에 확인됐는가"는 가장 늦은 6월 26일이고, trust tier는 human: actor가 있으므로 human-reviewed다. verified는 generated.at과 독립적이다. 내용은 재확인 없이 바뀔 수 있고 사실은 재생성 없이 재확인될 수 있다. 확인 주체가 하나면 리스트 대시 없이 { by, at } 매핑 하나로 적어도 되고(MAY), 소비자는 그 매핑을 1개짜리 리스트로 다루어야 한다(MUST).

trust tier는 소비자가 verified에서 유도한다. 낮은 단계부터 높은 단계 순서다.

trust frontmatter가 없는 concept도 소비 가능하며 소비자는 거부해서는 안 된다(MUST NOT). trust tier는 권고 신호이지 접근 제어가 아니다. 즉 unverified 문서를 숨길지 표시할지는 소비자의 결정이다.

lifecycle 기록

status가 없으면 stable이다. stale_after는 선택 키이며 절대 시각이다. concept은 now >= stale_after일 때 stale이다. 상대적 TTL이 아니라 절대 시각으로 두는 이유는 신선도 판정을 "언제 읽었는가"와 무관한 단순 비교로 끝내기 위해서다. TTL이었다면 소비자가 문서를 읽은 시각과 생성 시각을 함께 알아야 하지만, 절대 시각이면 현재 시각과 한 번 비교하면 된다.

링크와 경로

concept 사이 링크는 표준 markdown 링크 두 형태를 지원한다.

A에서 B로 가는 링크는 관계가 있다는 사실만 주장한다. 관계의 종류(부모와 자식, 참조, 조인, 의존)는 링크가 아니라 주변 산문이 전달한다. 그래서 그래프 뷰를 만드는 소비자는 보통 모든 링크를 타입 없는 관계의 방향 엣지로 다룬다. 소비자는 끊긴 링크를 견뎌야 한다(MUST). 대상이 bundle에 없는 링크는 잘못된 것이 아니라 아직 쓰이지 않은 지식일 수 있다.

경로나 URI를 값으로 갖는 필드는 다섯 개다.

각 필드는 절대 URL, /로 시작하는 bundle 상대 경로, 상대 경로(예: ../computations/revenue.md)를 받는다. references/ 하위 디렉토리는 외부 자료, 실행 지침, 코드를 bundle 안의 1급 concept으로 미러링하는 관용 위치다. source, executor, attester가 흔히 여기를 가리키며 예시는 references/attesters/revenue.py다. 명명 규약이지 요구 사항은 아니다.

actor 규약

정체를 기록하는 필드(generated.by, verified[].by)는 하나의 actor 규약을 쓴다.

trust를 분류하는 소비자는 human: 접두사로 판별한다. 따라서 생산자는 손으로 쓰거나 사람이 확인한 내용에 이 접두사를 반드시 써야 한다(MUST). 접두사를 빠뜨리면 사람의 승인이 machine-confirmed로 강등되는 결과가 된다.

index.md와 log.md

index.md가 하위 디렉토리 항목(* [Subdirectory](subdir/) - ...)을 포함할 수 있으므로 소비자는 루트 index에서 시작해 한 단계씩 내려갈 수 있다. log.md의 예시는 # Directory Update Log 아래 ## 2026-05-22와 ## 2026-05-15 두 날짜 헤딩을 두고 각 항목이 관련 concept을 링크하는 형태다.

명세의 두 예시는 다음과 같다.

# Section / Group Heading

* [Title 1](relative-url-1) - short description of item 1
* [Title 2](relative-url-2) - short description of item 2

# Another Section

* [Subdirectory](subdir/) - short description of the subdirectory

# Directory Update Log

## 2026-05-22
* **Update**: Added a BigQuery 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.

index 항목의 설명 문구는 링크된 concept의 description에서 가져오므로, 생산자가 description을 충실히 쓰면 index는 자동으로 유용해진다. log는 사람이 읽는 산문이라 항목의 종류(Update, Creation, Initialization)를 굵은 단어로 앞세우는 관례만 있고 기계가 파싱할 구조는 정하지 않는다.

Attested Computation

Attested Computation concept은 값이 무엇을 뜻하는지만이 아니라 그 값을 계산하는 승인된 방법을 담는다. 이 타입이 필요한 이유는 provenance만으로는 답할 수 없는 질문이 있기 때문이다. provenance는 "이 주장은 어디서 왔는가"에 답하고, attestation은 "이 수치는 우리가 정한 방식대로 만들어졌는가"에 답한다. 매출 정의의 출처가 재무 규정 문서라는 사실과 이번에 표시된 매출 수치가 그 정의대로 계산됐다는 사실은 별개다. OKF는 계산과 그것을 검사할 수단을 기록할 뿐 스스로 아무것도 실행하지 않는다.

독립 concept으로 두는 근거

승인된 계산은 type: Attested Computation인 독립 concept이다. 값이 필요한 concept(Metric, BigQuery Table)은 보통의 markdown 링크로 그 concept을 가리킨다. 명세는 계산을 지표 문서 안에 넣지 않고 따로 두는 근거를 셋 든다.

계약 필드

계약은 concept의 최상위 frontmatter다. provenance, trust, lifecycle 세 계열에 더해 다음 키를 갖는다.

resource 뒤에 무엇이 있는지는 패키징 선택이다. 스킬, 스크립트, 컨테이너 어느 것이든 될 수 있고 OKF는 인터페이스를 고정하고 패키징은 규정하지 않는다. 명세 10.2절의 예시는 다음과 같다.

type: Attested Computation
title: Revenue for fiscal year
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가 있고, 그 아래 산문이 [^rev-policy] 각주로 매출 인식 규정 문서에 귀속된다. @year가 선언된 파라미터 year에 대응하는 BigQuery 바인드 변수이며, runtime: bigquery가 이 대응 규칙을 정한다.

계산 제공 방식

에이전트의 권한 경계

에이전트는 선언된 parameters의 값만 줄 수 있고(MAY) 계산을 쓰거나 고쳐서는 안 된다(MUST NOT). computation에 파라미터 값을 바인딩해 실행 가능한 산출물을 만드는 일은 소비자 몫이고, attester는 같은 바인딩을 독립적으로 다시 유도해 실제 실행된 것과 비교한다.

이 비교가 성립하는 이유는 비교 대상이 receipt에 담긴 전개되고 컴파일된 산출물(executed_sql, compiled_sql)이기 때문이다. 다시 쓴 질의, 바꿔치기한 계산 파일, 변조된 의존성은 모두 실제 실행된 SQL을 바꾸므로 검사에 실패한다. 에이전트에게 열린 표면이 타입 있는 파라미터뿐이라서 "승인된 것이 실행됐는가"는 판단이 아니라 기계적 비교가 된다.

문서 하나가 계산 하나인 경우는 드물다. 매출, 이익, 마진을 논하는 손익계산서 개요는 읽을 수 있는 concept 하나로 남고 수치마다 Attested Computation 하나씩을 링크한다. 명세 예시는 type: Metric인 Revenue concept이 # Definition에서 [the revenue computation](../computations/revenue.md)를 가리키는 형태다. 계산마다 concept이 따로 있으므로 매출은 신선한데 이익은 stale_after를 넘긴 상태가 가능하고, 각각 자기 실행에 대해 attest한다. 같은 폴더에 모으는 것(computations/ 폴더와 index.md)은 디렉토리 선택이지 frontmatter 선택이 아니다.

소비자 흐름

명세 10.5절은 소비자가 Attested Computation을 쓰는 흐름을 6단계로 적되 informative(규범이 아닌 안내)로 표시한다. 아래의 런타임 산출물은 bundle에 저장되지 않는다.

5단계의 fidelity 검사가 중요하다. attester는 계산이 승인된 것인지만 보는 것이 아니라, 화면에 표시된 값이 에이전트의 텍스트가 아니라 job id로 다시 읽은 실제 결과와 일치하는지도 본다. 즉 승인된 SQL을 실행한 뒤 결과 숫자를 잘못 옮겨 적는 경우도 잡는다.

verified와 attestation의 구분

둘은 서로를 대체하지 않는다. 정의가 낡은 concept도 깨끗하게 attest될 수 있고, 방금 verify된 정의도 실행마다 attestation이 필요하다. 그래서 명세는 둘 다 필요하다고 적는다.

적합성 조건과 소비자 의무

bundle이 OKF v0.2에 적합하려면 세 조건을 만족한다.

trust, lifecycle, provenance, computation 계열이 있으면 생산자는 5절부터 10절을 따라야 하고(SHOULD) 소비자에게는 다음 의무가 있다.

나머지 제약은 소비자가 느슨한 권고로 취급해야 한다(SHOULD). 특히 다음 다섯 가지를 이유로 bundle을 거부해서는 안 된다(MUST NOT).

• optional frontmatter 필드 누락
• 모르는 type 값
• 모르는 추가 frontmatter 키
• 끊긴 cross-link
• index.md 부재

이 관대한 적합성 원칙은 포맷의 확장성과 짝을 이룬다. 생산자가 임의 키와 임의 타입을 쓸 수 있으려면 소비자가 그것을 이유로 거부하지 않아야 한다.

버전 규칙과 v0.1 변경

버전은 <major>.<minor>로 매긴다.

bundle은 루트 index.md의 frontmatter 블록에 okf_version: "0.2"로 목표 버전을 선언할 수 있으며(MAY) 이곳이 index.md에 frontmatter가 허용되는 유일한 자리다. 선언된 버전을 모르는 소비자는 거부 대신 최선 소비를 시도해야 한다(SHOULD).

v0.2는 v0.1을 대체하며 12절 기준으로 minor 상승이지만, v0.1 필드의 이름을 바꾸거나 퇴역시키는 의도적 breaking change 둘을 따로 밝힌다. v0.1 bundle은 아래 폴백으로 v0.2 소비자가 소비할 수 있다.

bundle 구조, 예약 파일명, 필수 type, 권장 title, description, resource, tags, cross-linking, index 파일, log 파일, 관대한 적합성은 변경 없이 그대로 넘어왔다.

reference agent

README에 따르면 reference agent는 두 pass로 실행된다.

web pass에서 가져온 페이지마다 에이전트는 세 가지 중 하나를 고른다.

--web-max-pages 상한과 동일 도메인 허용 호스트 필터는 도구 안쪽에서 강제된다. LLM의 판단이 아니라 도구가 한도를 지키므로 에이전트가 한도를 초과해 실행할 수 없다. --no-web은 web pass 전체를 건너뛴다.

설치와 자격 증명은 README의 Install과 Credentials 절이 정한다.

최소 실행은 BigQuery 데이터셋과 bundle 출력 디렉토리를 가리키는 것이다.

.venv/bin/python -m reference_agent enrich \
    --source bq \
    --dataset <project>.<dataset> \
    --web-seed-file <path/to/seeds.txt> \
    --out ./bundles/<name>

visualizer

visualize 서브커맨드는 임의의 OKF bundle을 자기완결 인터랙티브 HTML 파일 하나로 렌더한다. 파일 하나이고 백엔드가 없으며 보는 쪽에 설치가 필요 없다. 최신 브라우저에서 열거나, 산출물로 공유하거나, 정적 파일 서버에 올리거나, 이 저장소처럼 bundle 옆에 커밋할 수 있다. README는 이 뷰어를 OKF의 PoC 소비자로, reference agent를 PoC 생산자로 대응시키면서, OKF bundle은 markdown을 읽는 무엇으로든 소비될 수 있고 이 뷰어는 그 한 형태일 뿐이라고 덧붙인다.

생성 명령은 .venv/bin/python -m reference_agent visualize --bundle ./bundles/<name>이며 기본적으로 bundles/<name>/viz.html을 쓴다.

README의 예시는 --bundle ./bundles/crypto_bitcoin --out /tmp/btc.html --name "Bitcoin OKF"로 출력 위치와 헤더를 바꾸는 경우다. HTML은 bundle을 JSON blob으로 내장하고, 그래프에는 Cytoscape.js를, 브라우저 내 markdown 렌더링에는 marked를 쓰며 둘 다 CDN에서 로드한다. bundle은 생성 시점에 한 번 파싱되어 파일에 직렬화되므로 데이터는 페이지 밖으로 나가지 않는다.

결과

동봉 bundle과 recipe

정량 벤치마크는 없다. 명세와 PoC 저장소이므로 결과는 재현 가능한 bundle로 제시된다. 각 sample은 seed URL과 정확한 enrich 명령을 담은 recipe(samples/<name>/)와 그 recipe가 생성한 bundle(bundles/<name>/)의 짝이다. recipe를 열면 재현할 수 있고 bundle을 열면 결과를 바로 볼 수 있다.

네 bundle 모두 viz.html이 함께 체크인되어 있다. Stack Overflow는 횡단 문서 페이지 하나에서 여러 concept을 함께 보강하는 경우를, Bitcoin은 blocks와 transactions처럼 테이블 사이의 foreign key 관계를 산문에 담는 경우를 시험한다.

부록 A 손익계산서 예제

명세 쪽 실증은 부록 A의 손익계산서 예제다. 매출과 매출총이익 두 수치를 담은 v0.1 단일 문서를 서술 concept 하나와 Attested Computation 둘로 나누는 v0.1에서 v0.2로의 마이그레이션이다.

v0.1 형태는 두 수치를 한 type: Metric concept에 두었다. SQL은 에이전트가 읽거나 무시하거나 다시 쓸 수 있는 산문 속 코드였고, 인용은 # Citations 아래 평면 목록(핸드북, 매출 인식 규정, 원가 배분 기준의 세 URL)이었으며, 시각은 timestamp: '2026-05-28T22:53:05+00:00' 하나뿐이었다. 즉 누가 썼는지, 누가 확인했는지, 언제 낡는지, 어떤 SQL이 승인된 것인지를 어디에서도 읽을 수 없었다.

v0.2 형태는 다섯 종류의 파일로 나뉜다.

metrics/income-statement.md는 status: stable, generated(reference_agent/gemini-2.5-pro, 2026-06-20), verified(human:ahormati, 2026-06-25), stale_after: 2026-12-31, sources에 FP&A 보고 핸드북(fpa-handbook)을 가지며, 본문은 두 계산을 링크하고 각주로 핸드북에 귀속한다. 명세는 이 문서에 대해 "trust는 이 문서가 아니라 링크한 대상에 산다"고 적는다. 서술 문서는 어느 수치도 직접 계산하지 않기 때문이다.

두 계산의 frontmatter는 다음과 같이 다르다.

두 계산은 일부러 다른 상태에 놓여 있어 같은 소비자가 한 bundle 안에서 두 가지 다른 판정에 도달한다. 매출은 사람이 verify했고 신선하며, 한 달에 5,000회 조회된 살아 있는 대시보드 source가 뒷받침한다. 매출총이익은 프로세스가 verify했고 stale_after를 넘겼으므로 6단계 흐름의 Gate 단계에서 경고나 거부 대상이 된다. receipt 필드도 runtime에 따라 다르다. BigQuery는 job_id와 executed_sql을, dbt는 run_id와 compiled_sql을 돌려주므로 attester도 각각 SQL 동일성과 dbt 바인딩을 검사하는 별개 코드다.

두 예시 모두 generated.at이 verified.at보다 늦다. 매출은 6월 25일에 사람이 확인한 뒤 6월 28일에 내용이 다시 바뀌었고, 매출총이익은 6월 12일 야간 점검 뒤 6월 14일에 바뀌었다. 이는 5.2절이 말하는 "내용은 재확인 없이 바뀔 수 있다"의 사례이며, generated와 verified를 분리해 둔 이유를 예제 안에서 보여 준다.

소비자 흐름의 적용

10.5절의 6단계를 부록 A의 두 계산에 적용하면 같은 소비자가 어디에서 다른 판정에 이르는지 드러난다. 아래 표의 값은 모두 부록 A의 frontmatter에서 가져온 것이다.

두 계산의 attester 파일명이 다른 이유는 12절의 유보 항목과 이어진다. BigQuery 쪽은 실행된 SQL과 승인된 SQL의 동일성을 보면 되지만, dbt 쪽은 {{ ref() }}와 {{ var() }}가 컴파일된 결과를 봐야 하므로 비교 기준이 모델과 바인딩의 동일성으로 옮겨간다. 명세는 이런 semantic layer 템플릿을 아직 표준화하지 않았다고 밝힌다.

한계

명세가 미룬 항목

명세 12절의 "Considered and deferred" 절이 의도적으로 후속 개정으로 미뤘다고 밝힌 항목은 다음과 같다.

• 전체 런타임 프로토콜. receipt와 판정의 wire format, 실행을 둘러싼 attestation 수명주기가 비어 있어 attestation은 현재 인터페이스 선언까지만 표준이다.
• attester의 ABI, 이식성, 샌드박싱. 서빙과 스킬 관련 후속 작업과 함께 다뤄질 가능성이 크다고 적혀 있다. attester가 소비자 쪽에서 실행되는 것을 전제하면서 격리 규약은 아직 없다.
• attestation 캐싱.
• semantic layer 템플릿(Looker, dbt). attester의 비교 기준이 SQL 동일성에서 모델과 바인딩 동일성으로 옮겨가는 경우다.

명세 본문이 범위 밖이라고 적은 항목도 있다. lineage는 링크로만 표현하며 명시적 derived_from이나 데이터 lineage는 v0.2 범위 밖이다(5.1절). usage_count는 거친 신호라서 종류가 다른 source 사이의 정밀한 순위로는 쓸 수 없다(5.1절).

자료 내부의 서술 불일치

• README 상단은 "three ready-to-browse bundles"라고 적으면서 바로 아래에 bundle 4개(ga4, stackoverflow, crypto_bitcoin, acme_retail)를 나열한다. Samples 절의 recipe는 3개뿐이고 acme_retail의 recipe와 설명은 README에 없다.
• 명세 1절은 소비자의 질문을 다섯 개(provenance, trust, freshness, lifecycle, attestation)로 들면서, 바로 이어지는 문장에서 v0.2가 1급으로 만든 항목은 provenance, trust, lifecycle, attestation 넷이라고 적는다. freshness는 별도 계열 이름 없이 5.5절의 stale_after가 담당한다.
• 명세 13절은 v0.2가 12절 기준으로 minor 상승이라고 적으면서 동시에 의도적 breaking change 둘을 밝힌다. 12절의 정의상 breaking change는 major 상승이 포함할 수 있는 것이다. 명세는 이 예외를 v0.1 필드의 이름을 바꾸거나 퇴역시키기 때문에 따로 밝힌다고 설명한다.

현재 자료로 확인할 수 없는 항목

• 라이선스. README 본문에 라이선스 조항이 없고 raw에 LICENSE.md가 없다. frontmatter의 Apache-2.0은 유지하되 저장소의 LICENSE 파일을 직접 확인해야 한다.
• 소스 코드 구조, 테스트 개수, enrich의 내부 프롬프트와 파싱 방식. raw는 README와 SPEC 두 파일뿐이다.
• BigQuery 외 --source 값의 지원 여부. README는 --source bq만 보여 준다.
• 저장소의 이전 위치나 v0.1 저장소와의 관계. README와 SPEC 어디에도 기술이 없다.
• 무결성 검사(끊긴 링크, 모르는 타입) 절차. 명세는 소비자가 이를 견뎌야 한다고만 적고 검사 방법은 규정하지 않는다.

핵심 용어

관련 페이지

• Ontology Atlas: markdown 폴더의 frontmatter를 그래프로 컴파일하고 backlink를 파생시키는 점이 OKF의 visualizer와 같다. 다만 Atlas는 종류와 관계 타입을 작은 고정 집합으로 두는 반면, OKF는 type 값을 중앙에 등록하지 않고 링크에 관계 종류를 두지 않는다.
• AKB, llmwiki, GBrain 비교 및 AKB 발전 방향: 에이전트 메모리를 knowledge base로 다루는 세 시스템을 비교하면서 lifecycle 상태값, provenance 필드, stale 탐지를 운영 기능으로 제안한다. OKF의 status, stale_after, sources가 같은 문제를 파일 포맷 수준에서 다룬다.
• Karpathy LLM Wiki 패턴: 한국어 종합 정리 (kmyu99 Notion): LLM이 markdown과 frontmatter로 지식 베이스를 계속 갱신하는 LLM Wiki 패턴을 정리한다. OKF 명세가 전제하는 "에이전트가 지속적으로 유지하는 코퍼스"와 같은 대상을 다루지만, 두 자료가 서로를 언급하지는 않는다. 같은 계보로 보는 것은 이 wiki의 해석이다.
• 용어집: Agents (Terminology Glossary): progressive disclosure, 스킬, 컨텍스트 등 이 페이지가 쓴 agents 도메인 용어의 표기 기준.