Skip to content

Open Knowledge Format (OKF): findings

This is an investigation

A longer investigation, recorded as findings rather than conclusions. A survey is a claim about what existed when it was written.

Findings from reading the OKF v0.2 specification (GoogleCloudPlatform/open-knowledge-format). Factual notes only; any decision about adopting it is tracked separately.

What OKF is

An open format for representing knowledge (the metadata, context and curated insight around data/systems), designed to be authored by people, generated by agents, exchanged across organisations, and consumed by both. Deliberately minimal: a directory of markdown files with YAML frontmatter - "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." Version 0.2 at time of reading.

Design goals (from §1)

Knowledge should be: readable by humans without tooling, parseable by agents without bespoke SDKs, diffable in version control, and portable across tools, organisations and time. It standardises only the small structural conventions needed to make a corpus self-describing; everything else is left to the producer. Non-goals: no fixed taxonomy of concept types, no prescribed storage/serving/query infrastructure.

Structure (§3–§4)

  • A bundle is a directory tree of markdown files; a concept is one markdown document. Concept ID = file path minus .md.
  • Reserved filenames: index.md (directory listing / progressive disclosure) and log.md (chronological history) - same two special files awiki and the Karpathy pattern use.
  • Frontmatter: only type is required; title, description, resource, tags recommended. Consumers MUST tolerate unknown types and MUST NOT reject documents with unrecognised fields.

OKF links between concepts are standard markdown links, in two forms:

  • absolute (bundle-relative), beginning with /, e.g. [customers table](/tables/customers.md) - the recommended form (stable when documents move within a subdirectory);
  • relative, e.g. [neighbouring concept](./other.md).

Wikilinks do not appear anywhere in the spec. Links are untyped (the relationship kind lives in surrounding prose), and consumers MUST tolerate broken links - a missing target "may simply represent not-yet-written knowledge" (the same orphan-tolerant stance, built on markdown links).

Trust / provenance / lifecycle (§5) - beyond plain markdown

OKF's substantive addition over "markdown + frontmatter" is making these first-class, all optional, all in frontmatter:

  • Provenance - sources with objective credibility signals (author, usage_count, last_modified); records signals, not a subjective score. Per-claim attribution via markdown footnotes keyed to a sources[].id.
  • Trust - generated (who produced it) vs verified (who confirmed it), kept distinct; trust tiers (unverified / machine-confirmed / human-reviewed) are derived from verified, not stored.
  • Lifecycle - status (draft/stable/deprecated) and stale_after (an absolute instant).
  • Actor convention - <producer>/<version>, human:<id>, process:<id>.

There is also an Attested Computation concept type (§10) carrying a sanctioned way to compute a value plus deterministic attestation - out of scope for most PKB use but notable.

Relationship to awiki

awiki tracks backlinks via wikilinks only, not Markdown links: awiki claims ~80% OKF conformance, yet its headline Obsidian-style wikilink cross-references (double square brackets around a page title) are precisely a point where it diverges from OKF, whose links are standard markdown. So OKF-standard linking and awiki's wikilink graph are, on this axis, opposed.

Why this is relevant here

OKF's stated goals map closely onto this vault's values Prefer plain-text, tool-agnostic formats and, arguably, Prefer FOSS software wherever possible - human-readable, tool-agnostic, diffable, portable, open. Notably OKF's link convention is the standard-markdown form, so adopting OKF and preferring markdown links point the same way rather than conflicting. Whether to adopt OKF for this vault is a separate, still-open decision.

The following pages link to this page: