okf

Open Knowledge Format (OKF)

OKF v0.2 is a vendor-neutral format for representing knowledge — the metadata, context, and curated insight around data and systems — as plain markdown files with YAML frontmatter, organized in a directory tree called a bundle. No SDK, no registry, no required tooling: if you can read a file you can consume OKF, and if you can git clone you can ship it.

The full specification is in references/SPEC.md. Read it when you need exact rules (reserved filenames, conformance, attested-computation contracts, versioning). This file covers the 90% you need for day-to-day work.

This skill targets v0.2. v0.1 bundles are still valid input — see Reading v0.1 bundles at the end.

Core model

• Bundle — a directory tree of .md files. The unit of distribution.
• Concept — one markdown file describing one unit of knowledge (a table, a metric, an API, a playbook, an idea). Its concept ID is the file path without .md (e.g. tables/users.md → tables/users).
• Reserved filenames — index.md (directory listing) and log.md (change history) are never concept docs.
• Links — standard markdown links between concepts express relationships; the surrounding prose conveys the relationship's meaning. Broken links are legal (they mark not-yet-written knowledge).

Concept document format

Every concept file = YAML frontmatter + markdown body:

---
type: BigQuery Table            # REQUIRED — the only required field
title: Customer Orders          # recommended: display name
description: One row per completed customer order.   # recommended: one line
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-07-13T00:00:00Z }
verified: { by: human:ahormati, at: 2026-07-14T09:00:00Z }
status: stable                  # draft | stable | deprecated
stale_after: 2026-12-31T00:00:00Z   # absolute instant; stale when now >= this
sources:
  - id: bq-schema
    resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
    title: BigQuery table schema
    author: team:data-platform
    last_modified: 2026-07-01T00:00:00Z
# any extra producer-defined keys are allowed
---

One row per completed customer order across web, mobile, and marketplace
channels. The grain is the order, not the line item — per-line detail lives in
[order_lines](order_lines.md). Covers 2019-01-01 onward.[^bq-schema]

# Schema

| Column        | Type   | Description                                     |
|---------------|--------|-------------------------------------------------|
| `order_id`    | STRING | Unique order identifier.                        |
| `customer_id` | STRING | FK to [customers](customers.md).                |

# Common query patterns

```sql
SELECT COUNT(*) FROM `acme.sales.orders`;
```

[^bq-schema]: BigQuery table schema