our-claude-skills/custom-skills/97-ourdigital-okf/code/references/frontmatter-fields.md

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.