# OKF v0.1 — Authoring Rules & Conformance Checklist

Distilled, actionable reference for producing and validating Open Knowledge Format
bundles. Authority: the full spec at
`~/Documents/reference-library/open-knowledge-format/okf/SPEC.md`. **Read this file
before producing a bundle.**

## Core model

- **Bundle** — a directory tree of markdown files. The unit of distribution.
- **Concept** — one markdown file = one unit of knowledge (a table, dataset, metric,
  playbook, API, reference…).
- **Concept ID** — the bundle-relative file path with `.md` removed
  (`tables/users.md` → `tables/users`). The path *is* the identity.
- Concepts form a **graph**, linked by ordinary markdown links — richer than the
  parent/child implied by the directory tree.

## Reserved filenames (not concepts)

| File | Purpose |
|------|---------|
| `index.md` | Directory listing for **progressive disclosure** (§6). No frontmatter — except an optional bundle-root `index.md` may carry `okf_version: "0.1"`. |
| `log.md` | Update history: date-grouped (`YYYY-MM-DD`, newest first), entries lead with a bold verb (`**Update**`, `**Creation**`…). |

All other `.md` files are concept documents.

## Frontmatter

YAML block delimited by `---` at the very top of the file.

| Field | Status | Notes |
|-------|--------|-------|
| `type` | **REQUIRED** | Short string, e.g. `BigQuery Table`, `BigQuery Dataset`, `Metric`, `Playbook`, `Reference`, `API Endpoint`. Not centrally registered; consumers tolerate unknown types. |
| `title` | Recommended | Display name; else derived from filename. |
| `description` | Recommended | One sentence; used in index snippets/previews. |
| `resource` | Recommended | Canonical URI of the underlying asset; omit for abstract concepts. |
| `tags` | Optional | List of short strings (inline `[a, b]` or block `- a`). |
| `timestamp` | Optional | ISO 8601 last-modified time. |
| *(extensions)* | Optional | Any extra producer keys; preserve, never reject. |

## Body

Standard markdown. Prefer structural markdown (headings, tables, lists, fenced code)
over prose. Conventional section headings (use when applicable):

| Heading | Purpose |
|---------|---------|
| `# Schema` | Columns/fields of an asset. |
| `# Examples` | Concrete usage, usually fenced code. |
| `# Citations` | Numbered external sources backing body claims. |

## Cross-linking

- **Bundle-relative (recommended):** leading `/`, from the bundle root —
  `[customers](/tables/customers.md)`. Stable when files move within a subdirectory.
- **Relative:** `[other](./other.md)`.
- A link asserts an *untyped* relationship; the kind is conveyed by surrounding prose.
- **Broken links are tolerated** — they may represent not-yet-written knowledge. Never
  an error.

## Conformance (§9) — what the validator enforces

A bundle is conformant if:
1. Every non-reserved `.md` has a parseable YAML frontmatter block.
2. Every frontmatter block has a non-empty `type`.
3. `index.md` / `log.md` follow their structure when present.

Consumers MUST NOT reject for: missing optional fields · unknown `type` values ·
unknown extra keys · broken cross-links · missing `index.md`.

Run: `python3 ../scripts/okf_validate.py <bundle>` (exit 0 = conformant; broken links
are warnings).

## Producer authoring rules

1. **One concept per file.** Choose a directory layout that fits the domain
   (`datasets/`, `tables/`, `metrics/`, `references/`, `playbooks/`…).
2. **Always set `type`** — descriptive and self-explanatory.
3. Add `title` + a one-sentence `description` to every concept (drives indexes).
4. Set `resource` for concepts bound to a real asset; omit for abstract ones.
5. **Cross-link** related concepts with bundle-relative links; reference FKs/joins in
   prose.
6. Add a `# Citations` section (numbered) whenever the body makes externally-sourced
   claims; cite as URLs, bundle paths, or `references/<slug>` concepts.
7. Generate an `index.md` per directory (and the root) listing children with their
   descriptions, for progressive disclosure.
8. **Self-validate** before declaring done; fix every conformance error.

## Versioning

`<major>.<minor>`. Minor = backward-compatible additions; major = breaking changes.
Bundles may declare `okf_version: "0.1"` in the root `index.md` frontmatter.