diff --git a/custom-skills/97-ourdigital-okf/code/assets/concept.md b/custom-skills/97-ourdigital-okf/code/assets/concept.md new file mode 100644 index 0000000..845229c --- /dev/null +++ b/custom-skills/97-ourdigital-okf/code/assets/concept.md @@ -0,0 +1,18 @@ +--- +type: +title: +description: +resource: +tags: [, ] +timestamp: +--- + +# Schema + +| Column | Type | Description | +|--------|------|-------------| +| `col` | TYPE | What it is. FK to [other](/tables/other.md). | + +# Citations + +[1] [Source title](https://example.com) diff --git a/custom-skills/97-ourdigital-okf/code/assets/index.md b/custom-skills/97-ourdigital-okf/code/assets/index.md new file mode 100644 index 0000000..3dc57eb --- /dev/null +++ b/custom-skills/97-ourdigital-okf/code/assets/index.md @@ -0,0 +1,8 @@ +# Group Heading + +* [Title](relative-or-bundle-relative-path) - short description from the concept's frontmatter +* [Another concept](/tables/orders.md) - one row per completed order + +# Subdirectories + +* [datasets/](datasets/) - dataset-level concepts diff --git a/custom-skills/97-ourdigital-okf/code/assets/log.md b/custom-skills/97-ourdigital-okf/code/assets/log.md new file mode 100644 index 0000000..a05355b --- /dev/null +++ b/custom-skills/97-ourdigital-okf/code/assets/log.md @@ -0,0 +1,5 @@ +# Update Log + +## 2026-06-16 +* **Initialization**: Created the bundle structure. +* **Creation**: Added the [orders table](/tables/orders.md). diff --git a/custom-skills/97-ourdigital-okf/code/references/frontmatter-fields.md b/custom-skills/97-ourdigital-okf/code/references/frontmatter-fields.md new file mode 100644 index 0000000..5ef1ada --- /dev/null +++ b/custom-skills/97-ourdigital-okf/code/references/frontmatter-fields.md @@ -0,0 +1,54 @@ +# OKF Frontmatter Field Reference + +Per-field guidance for authoring OKF v0.1 concept frontmatter. Only `type` is required; +everything else is recommended or optional. Producers may add arbitrary extra keys — +consumers preserve them and never reject on unknown keys. + +| Field | Required | Format | Example | +|-------|----------|--------|---------| +| `type` | **Yes** | short string | `BigQuery Table` | +| `title` | Recommended | string | `Customer Orders` | +| `description` | Recommended | one sentence | `One row per completed customer order.` | +| `resource` | Recommended | URI | `https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders` | +| `tags` | Optional | list of strings | `[sales, revenue]` or block `- sales` | +| `timestamp` | Optional | ISO 8601 datetime | `2026-05-28T14:30:00Z` | + +## `type` — the only required field + +A short string identifying the kind of concept. Consumers route, filter, and present on +it. Type values are **not** registered centrally; pick descriptive, self-explanatory +values. Common examples: + +- `BigQuery Table`, `BigQuery Dataset` — data assets +- `Metric` — a derived/calculated measure +- `Reference` — a standalone external doc captured as a concept (often under `references/`) +- `Playbook`, `Runbook` — operational procedures +- `API Endpoint` — an API surface + +Consumers MUST tolerate unknown `type` values (treat as generic concepts). + +## Recommended fields (priority order) + +- **`title`** — human-readable display name. If omitted, consumers derive one from the + filename. +- **`description`** — a single summarizing sentence. Used by `index.md` generators, + search snippets, and previews — keep it crisp. +- **`resource`** — a URI uniquely identifying the underlying asset. Omit for concepts + that describe abstract ideas (a metric, a business process) rather than a physical + resource. +- **`tags`** — cross-cutting categorization. Accepts inline (`[a, b]`) or block list + (`- a` on following lines) form. +- **`timestamp`** — ISO 8601 datetime of the last meaningful change. + +## Extensions + +Add any additional keys your producer needs (e.g. `owner`, `sensitivity`, `okf_version`). +Round-tripping consumers SHOULD preserve unknown keys and SHOULD NOT reject documents +that carry them. + +## Notes for this skill's parser (`okf_common.py`) + +The bundled validator/visualizer parse a small YAML subset that covers real OKF bundles: +`key: value`, inline lists `[a, b]`, block lists (`key:` then `- item`), folded +multi-line scalars (a value continued on indented lines), `>`/`|` block scalars, and +quoted scalars. It is not a full YAML engine — keep frontmatter to these shapes. diff --git a/custom-skills/97-ourdigital-okf/code/references/okf-spec-v0.1.md b/custom-skills/97-ourdigital-okf/code/references/okf-spec-v0.1.md new file mode 100644 index 0000000..480a5f0 --- /dev/null +++ b/custom-skills/97-ourdigital-okf/code/references/okf-spec-v0.1.md @@ -0,0 +1,92 @@ +# 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 ` (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/` 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 + +`.`. Minor = backward-compatible additions; major = breaking changes. +Bundles may declare `okf_version: "0.1"` in the root `index.md` frontmatter.