# OKF v0.1 — Condensed Authoritative Rules

This is the working reference for producing **conformant** Open Knowledge Format
v0.1 bundles. It distills the official specification. When in doubt, the rule
here is the rule to follow.

> Source: Open Knowledge Format v0.1 (Google Cloud / GoogleCloudPlatform
> `knowledge-catalog` repo, `okf/SPEC.md`).

## 1. What a bundle is
- A **Knowledge Bundle** is a directory tree of UTF-8 markdown files. It is the
  unit of distribution (git repo, tarball, or a subdirectory of a larger repo).
- A **Concept** is a single unit of knowledge = one markdown file.
- A **Concept ID** is the file path within the bundle minus the `.md` suffix.
  `tables/users.md` → concept id `tables/users`.
- The directory layout is **independent of the source domain** — organize
  concepts however best serves the consumer.

## 2. Reserved filenames
These have defined meaning at any level and MUST NOT be used for concepts:

| Filename   | Purpose                                            |
|------------|----------------------------------------------------|
| `index.md` | Directory listing for progressive disclosure (§6). |
| `log.md`   | Chronological change history (§7).                 |

Every other `.md` file is a concept document.

> **Producer convention (OKF Studio):** a bundle may also carry agent-instruction
> files at its root — `AGENTS.md`, `CLAUDE.md`, `README.md`, `GEMINI.md`,
> `copilot-instructions.md` — to make it self-describing for consuming agents.
> These are **not** OKF concepts and are **ignored by the OKF Studio validators**
> (not validated, indexed, linked, or visualized). This is a tooling convention,
> not part of the OKF spec's reserved-filename set.

## 3. Concept document = frontmatter + body

### Frontmatter (YAML, delimited by `---` on its own line, first line of file)
```yaml
---
type: <Type name>                 # REQUIRED — the only hard requirement
title: <display name>             # recommended
description: <one-sentence summary># recommended
resource: <canonical URI>         # recommended (omit for abstract concepts)
tags: [tag-a, tag-b]              # recommended
timestamp: 2026-05-28T14:30:00Z   # recommended, ISO 8601 last-modified
# any additional producer-defined keys are allowed
---
```

- **`type`** is the only required field and must be **non-empty**. It is a short,
  self-explanatory, free-form string (e.g. `BigQuery Table`, `Metric`,
  `Runbook`, `API Endpoint`, `Reference`, `Concept`, `Decision`). Types are NOT
  registered centrally; consumers must tolerate unknown types.
- Recommended fields, in priority order: `title`, `description`, `resource`,
  `tags`, `timestamp`.
- Extra keys are allowed and must be preserved by well-behaved consumers.

### Body (markdown)
- Standard markdown. **Favor structure** — headings, lists, tables, fenced code
  blocks — over freeform prose. Structure aids both human reading and agent
  retrieval.
- No required sections. These headings have **conventional** meaning; use them
  when applicable:

  | Heading       | Purpose                                          |
  |---------------|--------------------------------------------------|
  | `# Schema`    | Structured columns/fields of an asset.           |
  | `# Examples`  | Concrete usage examples, often fenced code.      |
  | `# Citations` | External sources backing claims (§8).            |

## 4. Cross-linking
Concepts relate to each other via standard markdown links.

- **Absolute (bundle-relative) — RECOMMENDED.** Begins with `/`, interpreted
  from the bundle root. Stable across file moves within a subdirectory:
  `See the [customers table](/tables/customers.md).`
- **Relative.** Standard relative paths: `[neighbor](./other.md)`.
- A link from A→B asserts an **untyped relationship**; the *kind* of
  relationship is conveyed by surrounding prose, not the link.
- **Broken links are tolerated** — a link to a not-yet-written concept is not a
  conformance error. (Producers should still minimize them.)

## 5. `index.md` (optional, progressive disclosure)
- MAY appear in any directory, including the root. Enumerates that directory's
  contents so a human/agent can see what exists before opening files.
- **Contains no frontmatter** — EXCEPT the **bundle-root** `index.md`, which MAY
  declare the targeted version: `okf_version: "0.1"`.
- Body is one or more sections, each grouping entries under a heading:
```markdown
# Section heading
* [Title 1](relative-url-1) - short description of item 1
* [Subdirectory](subdir/) - short description of the subdirectory
```
- Entries SHOULD reuse the linked concept's `description`. May be generated.

## 6. `log.md` (optional)
- MAY appear at any level to record changes to that scope. Flat list of
  date-grouped entries, **newest first**:
```markdown
# Update Log
## 2026-05-22
* **Update**: Added [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).
```
- Date headings MUST be ISO 8601 `YYYY-MM-DD`. The leading bold word
  (`**Update**`, `**Creation**`, `**Deprecation**`) is convention, not required.

## 7. Citations
- When the body makes externally-sourced claims, list sources under a
  `# Citations` heading at the bottom, numbered:
```markdown
# Citations
[1] [Source title](https://example.com/doc)
[2] [Internal runbook](/references/quality-runbook.md)
```
- Citation links MAY be external URLs, bundle-relative paths, or paths into a
  `references/` subdirectory that mirrors external material as concepts.

## 8. Conformance (the checklist that matters)
A bundle is **conformant** with OKF v0.1 if:
1. Every non-reserved `.md` file has a **parseable YAML frontmatter block**.
2. Every such frontmatter block has a **non-empty `type`** field.
3. Reserved files (`index.md`, `log.md`) follow the §5 / §6 shape when present.

Consumers treat everything else as soft guidance and MUST NOT reject a bundle
for: missing optional fields, unknown `type` values, unknown extra keys, broken
links, or missing `index.md` files. Run `scripts/validate_okf.py` to check.

## 9. Versioning
- This is version **0.1**. Bundles MAY declare it via `okf_version: "0.1"` in
  the bundle-root `index.md` frontmatter (the only place frontmatter is allowed
  in an index file).
- Minor bumps = backward-compatible additions; major bumps may break.

## 10. Minimal conformant example
```
my_bundle/
├── index.md                 # may carry okf_version: "0.1"
├── datasets/
│   ├── index.md
│   └── sales.md
└── tables/
    ├── index.md
    ├── orders.md
    └── customers.md
```
`tables/orders.md`:
```markdown
---
type: Table
title: Orders
description: One row per completed customer order.
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique order identifier. |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |

Part of the [sales dataset](/datasets/sales.md).
```
