our-claude-skills/custom-skills/97-ourdigital-okf/code/references/okf-spec-v0.1.md

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.