Open Knowledge Format (OKF) v0.2: A Human- and Agent-Friendly Guide

As AI agents increasingly author, maintain, and consume knowledge corpora across organizations, traditional documentation conventions fall short. Plain markdown files with frontmatter lack first-class support for answering critical enterprise questions: Where did this data come from? How much should we trust it? Is it still fresh? Was this number computed according to official policy?

Enter the Open Knowledge Format (OKF) v0.2, developed to provide a minimal, open, human- and agent-friendly standard for representing knowledge, metadata, context, and curated insights.

---

What is the Open Knowledge Format (OKF)?

OKF is intentionally minimal: a directory of markdown files with YAML frontmatter. There is 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.

Core Design Goals

1. Readable by humans without specialized tooling.
2. Parseable by AI agents without bespoke SDKs.
3. Diffable cleanly in version control (Git).
4. Portable across tools, organizations, and time.

OKF v0.2 standardizes only the small set of structural conventions needed to make a knowledge corpus self-describing, leaving domain-specific schemas and runtimes entirely to the producer.

---

Bundle Structure

A knowledge bundle is structured as a hierarchical directory tree of markdown files:

path/to/bundle/
  index.md                      # Directory listing for progressive disclosure
  log.md                        # Chronological history of updates
  <concept>.md                  # A concept at the bundle root
  <subdirectory>/               # Grouped concepts
    index.md
    <concept>.md

Reserved Filenames

• index.md: Directory listing supporting progressive disclosure.
• log.md: Chronological update history.

All other .md files represent individual concepts (tangible assets like tables/APIs, or abstract ideas like metrics and playbooks).

---

Concept Documents & Frontmatter

Every concept file consists of a YAML frontmatter block followed by markdown body prose.

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-05-28T14:30:00Z }
---

• type: The only mandatory field. Identifies the concept kind (e.g., BigQuery Table, API Endpoint, Metric, Playbook, Attested Computation). Unknown types are tolerated gracefully by consumers.
• title, description, resource, tags: Standard optional metadata fields for display, search, and categorization.

---

Provenance, Trust, and Lifecycle

OKF v0.2 introduces first-class metadata families to ensure agent-maintained corpora remain trustable.

1. Provenance (sources)

sources records external or internal materials a concept derives from, complete with optional credibility signals:

• author: Who/what produced the source (using the actor convention like team:ga4-docs).
• usage_count: How often the resource was exercised over a usage_window.
• last_modified: When the source last changed.

Per-claim attribution is achieved cleanly via markdown footnotes keyed to source IDs:

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

[^ga4-schema]: GA4 BigQuery Export schema

2. Trust (generated and verified)

• generated: Records who authored the content (by) and when (at).
• verified: A list of confirmation events by actors, allowing consumers to derive trust tiers:
  • Unverified: No verified key.
  • Machine-confirmed: Verified only by non-human actors.
  • Human-reviewed: Verified by a human:<id> actor.

3. Lifecycle (status and stale_after)

• status: draft, stable, or deprecated.
• stale_after: An absolute date (YYYY-MM-DD) indicating when content becomes stale (today >= stale_after).

---

Actor Conventions

Identities are standardized across producers and verifiers:

• <producer>/<version> for agents/tools (e.g., reference_agent/gemini-2.5-pro).
• human:<id> for people (e.g., human:ahormati).
• process:<id> for automated batch processes (e.g., process:finance-nightly).

---

Conclusion

OKF v0.2 bridges the gap between human readability and agent automation. By standardizing provenance, trust tiers, lifecycle states, and actor attributions in lightweight Markdown and YAML, organizations can build robust, transparent, and version-controlled knowledge graphs that agents can safely query and maintain.