What's Changing in the OKF Spec

27 open PRs, one week. The OKF v0.1 spec is evolving fast — here's what's on the table and what it means for anyone building OKF bundles.

Since the OKF spec shipped in late June, 27 open pull requests have been submitted to the official GoogleCloudPlatform/knowledge-catalog repo. Some are bug fixes in the reference tooling, others are substantive proposals that change how bundles work.

If you're publishing or consuming OKF bundles — and with BundleDex now at 559+ bundles — these are the changes you need to track.

PRs That Change How You Write Bundles

#165

Relative cross-links over absolute

OPEN — Proposal to flip the spec's recommendation from absolute bundle-relative links (/entities/foo.md) to relative links (../entities/foo.md).

Why it matters: Absolute links only resolve in OKF-aware consumers. Relative links work everywhere — GitHub, editors, any markdown renderer. The PR argues that making OKF more widely compatible increases adoption.

What to do: Consider writing new cross-links as relative paths. Existing absolute links remain valid per the spec.

#192

`okf_version` on standalone concept files

OPEN — Clarifies that a single concept document distributed outside a bundle MAY declare okf_version in its own frontmatter.

Why it matters: Not every OKF concept lives inside a bundle directory. Standalone guides, reference cards, and one-off knowledge items should be able to self-identify as OKF-compatible. This closes a gap where the spec only permitted okf_version at bundle root.

What to do: If you distribute standalone OKF documents, add okf_version: "0.1" to their frontmatter.

#190

`.okfignore` — skip files in bundle walks

OPEN — Optional file convention letting producers mark files/directories that consumers and enrichment agents SHOULD skip.

Why it matters: Drafts, scratch notes, large binaries, and working files currently get picked up as "concepts" by naive consumers. .okfignore lets you keep your work-in-progress inside the bundle directory without it being indexed. Similar to .gitignore, .dockerignore, .npmignore.

What to do: Add .okfignore to bundle roots once this ships. Until then, keep drafts in separate folders.

#189

Agent-routing hints: `purpose`, `task`, `audience`

OPEN — Three optional frontmatter fields that let a consumption agent decide whether to use a concept before reading its body.

Why it matters: As the OKF ecosystem grows, agents need to quickly filter bundles and concepts without loading every file. These hints are the metadata equivalent of a table of contents — purpose says what the concept is for, task says what kind of work it supports, audience says who it's for.

What to do: Start adding these to your concept frontmatter as an optional convention — there's no schema conflict since the spec allows additional frontmatter keys.

#187

`timestamp` clarified as recommended + staleness signal

OPEN — Aligns the spec description with what was already in the frontmatter example: timestamp is Recommended, not Optional, and its purpose is explicitly stale-content detection.

Why it matters: Timestamps let consumers decide whether a bundle or concept is current enough for their use case. The PR adds language about how agents should treat documents without timestamps (less trusted).

What to do: Always include timestamp in bundle-level and concept-level frontmatter. Keep it updated when content changes.

#186

URL encoding for cross-link targets (SPEC §5.4)

OPEN — New subsection clarifying that percent-encoded filenames (weekly%20report.md) are valid OKF cross-link targets.

Why it matters: Many file systems produce files with spaces, which CommonMark expresses as percent-encoded URLs. This makes the encoding rules explicit rather than leaving them to tool-specific behavior.

What to do: Avoid spaces in filenames for best compatibility, but know that it's valid if you can't avoid them.

#188

`log.md` is append-only history

OPEN — Adds explicit language that log.md entries should be append-only: add new dated entries rather than editing or deleting past ones.

Why it matters: If log.md is mutable, it can't serve as an audit trail. This clarification makes it useful for version tracking and provenance.

What to do: Treat your bundle's log.md as append-only. Add timestamps, don't rewrite history.

Proposals Worth Watching

#195

Typed relationship edges: `supersedes`, `contested_by`

PROPOSAL — Two optional frontmatter keys for typed lifecycle relationships between whole concepts.

What it does: Lets a concept declare that it supersedes another (newer, more accurate version) or is contested by another (legitimate disagreement). This makes the spec more than a static file format — it becomes capable of expressing knowledge dynamics.

Why track this: If typed edges land, bundle authors can express versioning, debate, and evolution directly in the spec rather than in conventions. This is the direction we expect the spec to move in v0.2.

#191

Optional erasure conformance profile (SPEC §9.1)

PROPOSAL — Opt-in spec for bundles that must not leak removed knowledge.

What it does: Currently, deleting a file doesn't erase it from consumers that already saw it. This proposal adds a conformance profile requiring bundles to handle removal cleanly — no dangling references, no recoverable deleted content.

Why track this: Relevant for any bundle covering sensitive or versioned knowledge where removals must be explicit and non-leaky.

#159

Reliability frontmatter convention

PROPOSAL — Optional reliability key indicating how much a consumer should trust a claim.

What it does: Lets concept authors signal epistemic quality — from "well-established fact" to "speculative hypothesis". Consuming agents can weight responses accordingly.

Why track this: Maps to how we already use confidence scoring in structured knowledge capture.

Tooling Fixes (Nothing Changes in Your Bundles)

These PRs fix bugs in the OKF reference implementation tools — the visualizer, validation scripts, and the reference_agent code. They don't change the spec itself, but they make the ecosystem more reliable:

#206 — Fix the visualizer to handle absolute bundle-relative links (/tables/users.md), which it was incorrectly skipping
#203 — Percent-decode link targets so links with spaces render properly in the viewer
#184 — Fix edge detection for absolute and titled cross-links in the graph tool
#193 — Stop treating # comment lines inside code fences as section headings
#149 — Exclude log.md from concept enumeration (was showing as "Unknown" node)
#145 — Align frontmatter validation with spec: only type is REQUIRED (tool was rejecting minimal bundles)
#150 — Fix timestamp key name in a tool (was using timeStamp)

What the Ecosystem Is Building

The community is already building tools around the spec, and several PRs add them to the official repo:

#205 — An organizing-with-okf Agent Skill (for Claude Code) that teaches coding agents how to organize projects as OKF bundles
#178 — OmniOKF, a Python compiler that converts PDF, DOCX, XLSX, PPTX, HTML, and Markdown into structured OKF bundles
#167 — A Community & Ecosystem Tools section in the README indexing editors, validators, CLIs, publishers
#185 — A new official sample bundle: ML Experiment Trail, modeling ML knowledge with Experiment, Model, Submission, and Lesson concept types
#144 — A community-contributed Cricket Domain Knowledge bundle (OKF v0.4)

What This Signals

Looking at the shape of PRs across the last 10 days, a few patterns emerge:

The spec is still v0.1 and evolving rapidly. It hasn't bumped versions, meaning these are all additive proposals rather than a release. Expect a v0.2 consolidating the accepted ones.
The focus is on agent-readiness. Agent-routing hints (#189), reliability signals (#159), typed relationships (#195) — these all make bundles more usable by autonomous consumers, not just humans reading markdown.
Conformance is being formalized. The erasure profile (#191), .okfignore (#190), and append-only log (#188) turn what started as a loose directory convention into a proper specification with rules.
Relative linking is winning. If #165 merges as expected, the future recommendation will be relative cross-links. Bundle authors should adopt this now.

Keep Up With OKF Changes

BundleDex updates daily with new bundles from the ecosystem. The source of truth for spec changes is the official repo.

View all open PRs →