Okf Open Knowledge Format

Open Knowledge Format (OKF)

OKF is a vendor-neutral, open spec (v0.2, released by Google Cloud) for representing knowledge as a directory of markdown files with YAML frontmatter. No SDK required — if you can cat a file, you can read OKF.

It formalizes the "LLM Wiki" pattern (Karpathy's gist) into an interoperable format: wikis written by different producers can be consumed by different agents without translation.

v0.2 adds: provenance tracking (sources), trust signals (generated, verified), lifecycle management (status, stale_after), and Attested Computations — a new concept type for sanctioned, verifiable calculations.

For the full spec, see:

• references/spec-v02.md — Current version (v0.2)
• references/spec-v01.md — Legacy version (v0.1)

Design Principles

1. Minimally opinionated — Only type is required. The spec defines interoperability surface, not content model.
2. Producer/consumer independence — Who writes and who reads are decoupled. Human-authored bundles feed agents; LLM-generated bundles are browsed by humans.
3. Format, not platform — No cloud, SDK, or vendor dependency. Value comes from how many parties speak it.
4. Trust is first-class — v0.2 makes provenance, verification, and freshness queryable from frontmatter.

Key Terminology

Quick Reference — Frontmatter Fields

Core Fields (all concepts)

Trust & Lifecycle Fields (v0.2)

Provenance Fields (v0.2)

Each sources entry:

• resource (REQUIRED): URL, bundle-relative path, or scope descriptor
• id: Stable key for footnote attribution
• title: Human-readable label
• author: Actor who produced the source
• usage_count: How often exercised (liveness signal)
• last_modified: When the source last changed

Attested Computation Fields (v0.2)

For concepts with type: Attested Computation:

Reserved Filenames

*Exception: bundle-root index.md MAY have frontmatter with okf_version: "0.2".

Conventional Body Headings

Actor Convention

Fields that record identity (generated.by, verified[].by, sources[].author) use:

• <producer>/<version> for agents: reference_agent/gemini-2.5-pro
• human:<id> for people: human:ahormati
• process:<id> for automation: process:finance-nightly

Trust tiers are derived from the human: prefix — human-verified > machine-confirmed > unverified.

Trust Tiers

Consumers derive trust from the verified field:

Trust tiers are advisory signals, not access control.

Create a Bundle

When the user wants to create an OKF bundle from scratch:

1. Determine scope and structure

Ask: What knowledge are we capturing? (tables, metrics, APIs, playbooks, etc.) Organize into a directory tree that makes sense for the domain.

2. Create concept documents

Each concept = one .md file. Minimal conformant example:

---
type: Metric
---

# Monthly Recurring Revenue (MRR)

Sum of all active subscriptions normalized to a monthly amount.

Full v0.2 example with provenance and trust:

---
type: Metric
title: Monthly Recurring Revenue
description: Sum of all active subscription revenue normalized to monthly.
tags: [revenue, saas, kpi]
status: stable
generated: { by: human:ftelles, at: 2026-08-25T10:00:00Z }
verified: { by: human:finance-lead, at: 2026-08-25T14:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: stripe-docs
    resource: https://stripe.com/docs/billing/subscriptions
    title: Stripe Subscription Billing
    author: team:stripe-docs
    last_modified: 2026-06-01T00:00:00Z
---

# Monthly Recurring Revenue (MRR)

## Definition

Sum of all active subscriptions normalized to a monthly amount.[^stripe-docs]
Excludes one-time fees and overages.

## Formula

`MRR = Σ(active_subscription_monthly_value)`

## Related

- [Churn Rate](./churn.md) uses MRR as denominator
- [ARR](./arr.md) = MRR × 12

[^stripe-docs]: Stripe Subscription Billing

For more examples across domains, see references/examples.md.

3. Cross-link concepts

Use standard markdown links. Two forms:

• Absolute (bundle-relative, starts with /): [customers](/tables/customers.md) — preferred (stable when files move)
• Relative: [churn](./churn.md)

Links assert relationships. The kind of relationship is conveyed by surrounding prose, not by the link syntax. Broken links are explicitly permitted — they represent knowledge not yet written.

4. Add provenance with footnotes (v0.2)

When claims reference external sources, use sources in frontmatter and footnotes in body:

sources:
  - id: ga4-schema
    resource: https://developers.google.com/analytics/bigquery/export-schema
    title: GA4 BigQuery Export schema

The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]

[^ga4-schema]: GA4 BigQuery Export schema

5. Generate index.md

Place in any directory for progressive disclosure. No frontmatter. Format:

# Metrics

- [MRR](./mrr.md) - Monthly recurring revenue
- [Churn](./churn.md) - Monthly churn rate
- [NPS](./nps.md) - Net Promoter Score

Entries should include the description from the linked concept's frontmatter.

6. Generate log.md (optional)

Chronological change history, newest first, ISO 8601 date headings:

# Update Log

## 2026-08-25
- **Creation**: Added MRR, Churn, and NPS metrics.
- **Creation**: Established directory structure.

## 2026-08-20
- **Initialization**: Bundle created.

7. Declare version (optional)

Bundle-root index.md may include frontmatter declaring the spec version:

---
okf_version: "0.2"
---

# My Knowledge Bundle

- [Tables](./tables/) - Database tables
- [Metrics](./metrics/) - Business KPIs

8. Distribution

A bundle can be distributed as:

• A git repository (recommended — history, attribution, diffs)
• A tarball or zip archive
• A subdirectory within a larger repository

9. Verify conformance

Three rules — all must pass:

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

Create an Attested Computation (v0.2)

Attested Computations are concepts that carry not just what a value means but a sanctioned way to compute it. Use them when you need verifiable, reproducible calculations.

When to use

• Financial metrics where compliance requires audit trails
• KPIs that must be computed consistently across reports
• Any calculation where "did the sanctioned thing run" matters

Structure

---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/revenue.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-09-23T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

The computation binds only the declared `parameters`, per the recognition
policy.[^rev-policy]

[^rev-policy]: Revenue recognition policy

Key rules

1. Agent fills parameters only — The agent supplies values for declared parameters, never edits the computation itself
2. Computation can be inline or external — Use # Computation heading for inline, or computation: field for external file
3. Executor produces receipt — Evidence the attester inspects
4. Attester is deterministic — No LLM, just code that verifies the receipt

Linking to computations

Other concepts link to Attested Computations:

---
type: Metric
title: Revenue
---

# Definition

Recognized revenue for a fiscal year, computed by 
[the revenue computation](../computations/revenue.md).

Validate a Bundle

Preferred: okflint (when available)

okflint is a dedicated Python linter for OKF bundles with 18 rules across 3 tiers (OKF core, profile, hygiene). If installed, always prefer it over the built-in bash script.

Agent behavior: Before validating, check if okflint is installed (command -v okflint). If NOT installed, ask the user:

"okflint (linter dedicado para OKF com 18 regras, profiles via manifesto e suporte a wikilinks) não está instalado. Quer que eu instale? Opções:

1. uv tool install okflint (recomendado, isolado)
2. pip install okflint
3. Seguir sem ele (validação básica com o script bash embutido)"

If the user agrees to install:

# Option 1: uv (recommended — installs isolated, no venv needed)
uv tool install okflint

# Option 2: pip (installs in current environment)
pip install okflint

# Verify installation
okflint --version

After installation (or if already available):

# Full validation with manifest (if okf-base.yaml exists)
if [ -f okf-base.yaml ]; then
  okflint validate --manifest okf-base.yaml ./bundle/
else
  # Core OKF validation only (no manifest needed)
  okflint validate ./bundle/
fi

okflint advantages over the built-in script:

• Manifest-driven profiles (enforce custom required fields, status vocabularies, per-type constraints)
• Wikilink resolution against full Obsidian vault
• JSON output (--json) for CI pipeline parsing
• Detects broken markdown links and ambiguous wikilinks
• Exit codes: 0 = pass, 1 = conformance failure, 2 = bad manifest

Fallback: built-in bash script

When okflint is not installed, use scripts/validate.sh which checks the 3 core conformance rules plus v0.2 fields.

When asked to validate, check the 3 conformance rules. Report:

✅ PASS: 12/12 concept files have valid frontmatter with type field
✅ PASS: index.md follows list structure (no frontmatter)
✅ PASS: log.md uses ISO 8601 date headings, newest first

⚠  WARNING: 3 files missing 'description' field (recommended)
⚠  WARNING: 2 broken cross-links (permitted but worth noting)
ℹ  INFO: 5 files with trust fields (generated/verified)
ℹ  INFO: 2 Attested Computation concepts found

For a script-based check, see scripts/validate.sh.