55 lines
2.6 KiB
Markdown
55 lines
2.6 KiB
Markdown
# 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.
|