Markdown Edit

Open Knowledge Format (OKF)

The Open Knowledge Format (OKF) is an open, vendor-neutral specification for structuring persistent knowledge bases, metadata, and context for humans and AI agents.

Overview

Originated by Google Cloud, OKF defines a minimal, file-based architecture where a Knowledge Bundle is represented as a directory hierarchy of standard CommonMark Markdown files with structured YAML frontmatter. It is designed to be authored by humans, maintained and synthesized by AI agents, and version-controlled via Git without requiring proprietary SDKs, databases, or runtime dependencies.

Identifier Conventions

OKF relies on standard filesystem paths and string conventions rather than centralized ID registries:

1. Concept IDs

Definition: The unique identifier of a concept within a bundle is its file path relative to the bundle root, with the .md extension removed (for example, people/vorburger.ch.md becomes people/vorburger.ch).
Dot (.) Support: Concept IDs can contain dots (.). Dots are valid characters in filenames and slugs across standard filesystems, allowing concept identifiers to represent domain names (such as people/vorburger.ch), software versions (such as standards/semver.2.0), or dotted taxonomies.
Slug Hygiene: Slugs should consist of lowercase alphanumeric characters, hyphens (-), and dots (.). Special path sequences like directory traversal (. or ..) and hidden files (leading dots like .hidden.md) must be avoided to ensure cross-platform portability and clean URL resolution.

2. Source IDs (`sources[].id`)

Definition: An optional key within a sources entry used for per-claim attribution and footnote citations in the document body.
Dot (.) Support: Source IDs can contain dots (for example, id: rfc.9110 or id: bq.schema.v1).

3. Actor IDs

Definition: Strings identifying entities that created, edited, or verified content in the generated or verified frontmatter blocks.
Conventions:
- Agents: <producer>/<version> (e.g., reference_agent/gemini-3.7-flash).
- Humans: human:<id> (e.g., human:/people/vorburger.ch).
- Processes: process:<id> (e.g., process:nightly-validator).
Dots are commonly used within actor identifiers and paths.

Document Structure & Frontmatter

Every concept document consists of YAML frontmatter delimited by --- and a Markdown body.

Frontmatter Schema

type: (Required) Short string identifying the kind of concept (e.g., Specification, Software, Playbook, schema:Person).
resource: Canonical URI identifying the underlying asset on the Web.
generated: Provenance object describing creation (by: <actor>, at: <iso8601-timestamp>).
verified: List of verification events (by: <actor>, at: <iso8601-timestamp>) establishing trust tiers.
tags: List of strings for cross-cutting categorization.
sources: List of materials the concept derives from, including credibility signals (author, usage_count, last_modified).

Reserved Files & Directory Layout

To support progressive disclosure and bundle management, the following filenames have special meaning:

File	Purpose	Frontmatter Required
`index.md`	Auto-generated or static directory listing for progressive disclosure.	No
`log.md`	Chronological ledger of bundle changes and agent updates.	No
`README.md`	Human-facing landing page rendered by Git hosts.	No