# 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.