What is Open Knowledge Format?

What does OKF stand for?

OKF stands for Open Knowledge Format. In practice, it is a human- and agent-readable bundle of Markdown files with YAML frontmatter. People can author it, agents can generate it, and tools can exchange it without a central registry or proprietary SDK.

What problem does OKF solve?

AI agents often receive documents as isolated pages, chunks, or search results. OKF gives that context a stable structure: concepts have types, descriptions, canonical resources, links, citations, and file paths that can become concept IDs.

The goal is not to replace OpenAPI, Protobuf, Avro, data catalogs, or docs. OKF references those systems and adds the surrounding knowledge layer: what a resource means, where it belongs, and how it connects to other concepts.

What is inside a knowledge bundle?

A knowledge bundle is the unit you distribute. It can be a Git repository, a ZIP archive, a tarball, or a subdirectory in a larger repo. Inside it, reserved files such as index.md and log.md help people and agents scan the bundle before opening individual concepts.

okf-bundle/
|-- index.md
|-- log.md
|-- tables/subscriptions.md
|-- metrics/monthly-recurring-revenue.md
`-- playbooks/revenue-review.md

What is a concept file?

A concept is one unit of knowledge represented as a Markdown document. A concept can describe a tangible asset, such as a table or endpoint, or an abstract idea, such as a metric, business process, policy, or playbook.

Every non-reserved concept file needs parseable YAML frontmatter and a non-empty type. Its concept ID is the file path without the .md suffix. The other fields are recommended because they make bundles easier to search, preview, route, and render.

---
type: Metric
title: Monthly Recurring Revenue
description: Recurring subscription revenue normalized to a monthly period.
resource: dashboard://revenue/mrr
tags: [revenue, saas, finance]
timestamp: 2026-06-13T00:00:00Z
---

# Calculation

MRR is the predictable recurring revenue generated by active subscriptions in the [subscriptions table](/tables/subscriptions.md).

Include active subscriptions with recurring billing. Exclude one-time setup fees, refunds, and usage-only charges unless normalized into a recurring plan.

# Examples

```sql
select sum(monthly_amount_usd) as mrr
from analytics.subscriptions
where status = 'active';
```

# Citations

[1] [Revenue dashboard](dashboard://revenue/mrr)

What does v0.1 require?

A conformant OKF v0.1 bundle has three hard requirements: every concept file must have parseable YAML frontmatter, every concept file must include a non-empty type, and reserved files such as index.md and log.md must follow their reserved-file roles when present.

Everything else is intentionally permissive. Consumers should tolerate unknown types, unknown extension fields, missing optional metadata, missing indexes, and broken links so partially generated or evolving bundles can still be useful.

How do links and citations work?

OKF uses ordinary Markdown links. A link from one concept to another asserts a relationship, and the surrounding prose explains what kind of relationship it is. Bundle-relative links such as /tables/orders.md are the most stable form because they keep working when a document moves inside its folder.

When a body makes claims from an external source, add a # Citations section. Citations can point to external URLs, bundle-relative paths, or reference concepts stored inside the bundle.

How do you start using OKF?

1. Create an okf/ folder in a repo, export, or project directory.
2. Add a root index.md that lists the first concept groups.
3. Create one concept file per important asset or idea.
4. Add frontmatter with at least type, then add title, description, resource, tags, and timestamp when useful.
5. Link related concepts with Markdown links and add citations for sourced claims.
6. Commit the folder, ship it as an archive, or expose it to an agent or catalog.

What can you build with OKF?

What OKF is good for

OKF fits curated knowledge that should be read by both humans and agents: metrics, warehouse tables, APIs, systems, operational playbooks, business rules, product concepts, decision records, and documentation maps.

Can OKF describe a website?

The same OKF pattern can describe a website as a map of concepts instead of a flat mirror of pages. It works best when the bundle is maintained alongside the site and used by search, documentation, catalogs, or agent workflows that need durable context.

What OKF is not

OKF is not a platform, SaaS, database, proprietary agent framework, SEO shortcut, fixed taxonomy, or replacement for domain-specific schemas. It is a lightweight portable format for structured knowledge. If you publish a bundle beside a website or repo, you also accept the maintenance cost of keeping that machine-readable copy current.

Who should care

Developers, data teams, SaaS builders, AI-agent builders, documentation teams, Laravel developers, and WordPress developers can use OKF to make important context easier to review and reuse.

How OKF helps AI agents

Agents work better when they can inspect concise, structured, trusted context before acting. OKF bundles make that context explicit and portable, and they let agents traverse relationships instead of guessing them from navigation, prose, or HTML structure. Consumers should also be permissive: unknown types, unknown fields, missing optional fields, and broken links should not make a bundle unusable.

How it relates to Markdown, YAML, Git, and documentation

Markdown keeps the body readable before anything renders it. YAML frontmatter gives tools structured metadata. Git makes bundles reviewable and versioned. Documentation teams can use OKF as a practical layer over existing knowledge, especially where the missing piece is not another page but a clearer map of what connects to what.