Open Knowledge Format (OKF)

🗒️ Description

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 the open spec (okf/SPEC.md, v0.1 draft) shipped inside the Google Cloud Knowledge Catalog GitHub repo.

The format is intentionally minimal: a directory of markdown files with YAML frontmatter. No schema registry, no central authority, no required tooling. “If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.”

It is designed to be authored by people, generated by agents, exchanged across organisations, and consumed by both — which is almost exactly the architecture this very vault (Brain) already runs on.

☘️ Motivation

The space of knowledge representation for AI agents is fragmenting into incompatible conventions. OKF’s bet: knowledge is best represented in established, commonly accessible formats that are

• Readable by humans without tooling,
• Parseable by agents without bespoke SDKs,
• Diffable in version control,
• Portable across tools, organisations, and time.

It standardises only the small set of 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 infra; not a replacement for domain schemas (Avro, Protobuf, OpenAPI) — OKF references them, it doesn’t subsume them.

🧩 Core concepts

• Knowledge Bundle — a self-contained, hierarchical collection of knowledge documents; the unit of distribution (a git repo, a tarball/zip, or a subdirectory of a larger repo).
• Concept — a single unit of knowledge = one markdown document. May describe a tangible asset (a table, an API), an abstract idea (a metric, a business process), or anything in between.
• Concept ID — the file’s path within the bundle minus the .md suffix (tables/users.md → tables/users).
• Frontmatter — YAML metadata block delimited by ---.
• Body — everything after the frontmatter; standard markdown.
• Link — a standard markdown link from one concept to another (relationships beyond the implicit parent/child hierarchy).
• Citation — a link from a concept to an external source backing a claim.

🧩 Document structure

A concept is a UTF-8 markdown file with two parts: a YAML frontmatter block and a markdown body.

Frontmatter — the one required field is type:

Field	Status	Purpose
type	REQUIRED	Short string identifying the kind of concept (e.g. BigQuery Table, API Endpoint, Metric, Playbook, Reference). Not registered centrally; consumers MUST tolerate unknown types.
title	recommended	Human-readable display name; derivable from filename if omitted.
description	recommended	One-sentence summary for index generators, search snippets, previews.
resource	recommended	Canonical URI of the underlying asset (absent for abstract concepts).
tags	optional	YAML list of short strings for cross-cutting categorisation.
timestamp	optional	ISO 8601 datetime of last meaningful change.

Producers MAY add any other keys; consumers SHOULD preserve unknown keys and MUST NOT reject documents over unrecognised fields.

Body favours structural markdown (headings, lists, tables, fenced code) over prose, since structure aids both human reading and agent retrieval. Conventional (not required) section headings: # Schema, # Examples, # Citations.

🧩 Reserved files & progressive disclosure

Two filenames are reserved at any level and MUST NOT be used for concepts:

• index.md — a directory listing for progressive disclosure: lets a human or agent see what’s available before opening individual documents. No frontmatter (except the optional bundle-root version declaration); body is sections of * [Title](url) - description entries. Producers MAY generate it; consumers MAY synthesise one on the fly.
• log.md — optional chronological change history, newest first, grouped under ISO YYYY-MM-DD date headings with convention-only bold leads (**Update**, **Creation**, **Deprecation**).

This is the same index-first pattern as Progressive Disclosure — and structurally identical to this vault’s _indexes/vault-map.md → catalog.md → note traversal.

🧩 Cross-linking

• Absolute (bundle-relative) links begin with / and are interpreted from the bundle root — the recommended form (stable when documents move within a subdirectory): [customers table](/tables/customers.md).
• Relative links use standard markdown paths: [neighbour](./other.md).
• A link A→B asserts an untyped relationship; the kind (references, joins-with, depends-on…) lives in the surrounding prose, not the link. Graph builders treat all links as directed edges.
• Consumers MUST tolerate broken links — a missing target isn’t malformed, it may be not-yet-written knowledge.

🧩 Conformance (the permissive consumption model)

A bundle is conformant with OKF v0.1 if:

1. Every non-reserved .md file has a parseable YAML frontmatter block,
2. Every frontmatter block has a non-empty type,
3. Reserved files (index.md, log.md) follow their structure when present.

Everything else is soft guidance. Consumers MUST NOT reject a bundle for missing optional fields, unknown type values, unknown extra keys, broken cross-links, or missing index.md. This permissiveness is intentional — OKF must stay useful as bundles grow, get refactored, and are partially agent-generated.

Versioning: <major>.<minor> — minor = backward-compatible additions, major = breaking changes. A bundle MAY declare its target via okf_version: "0.1" in the bundle-root index.md frontmatter.

🎨 Why it matters for me

• It is a spec for what Brain already does. This vault is a markdown + YAML-frontmatter knowledge base with index.md-style progressive disclosure, wikilink edges, and agent-driven authoring/maintenance. OKF formalises that pattern — a useful external reference point and sanity check for my own conventions.
• Directly adjacent to LLM Knowledge Bases and Progressive Disclosure: OKF is the “metadata as code” / agent-readable-wiki idea pinned down into rules without dictating tooling.
• Relevant to Context Engineering and AI Chatbots Architecture — a portable substrate that enrichment agents write and consumption agents traverse, the same producer/consumer split as RAG context layers (CocoIndex, LightRAG, Graphify).
• The “specified, not tooled” stance is the key differentiator from Obsidian/Notion (Obsidian) and from managed catalogs: interoperability rules only, infrastructure left open.

⚠️ Caveats

• v0.1 draft — early, may change; only type is load-bearing.
• It’s a format, not a product or library — value comes from producers/consumers that adopt the conventions.
• Deliberately under-specifies relationships (all links untyped), so richer graph semantics must be inferred from prose.

📖 Further reading

• Google Cloud Knowledge Catalog — the product and repo this spec ships inside
• Progressive Disclosure — the index-first pattern OKF’s index.md implements
• LLM Knowledge Bases — methodology for AI-maintained markdown knowledge bases
• Brain — this vault, a working instance of the same architecture
• Context Engineering
• CocoIndex · LightRAG · Graphify — turning data into agent-usable context

Source: GoogleCloudPlatform/knowledge-catalog — okf/SPEC.md (Open Knowledge Format v0.1 draft).

---

Template: knowledge_note_info