Skip to content

Refactor frontmatter and update examples #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
olegshulyakov wants to merge 1 commit into
base: main
Choose a base branch
from
+35 −17
Open

Refactor frontmatter and update examples #147

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 35 additions & 17 deletions okf/SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,22 +123,23 @@ Every concept is a UTF-8 markdown file. It has two parts:

```yaml
---
type: <Type name> # REQUIRED
type: <kebab-case-type-name> # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, …] # Optional
timestamp: <ISO 8601 datetime> # Optional last-modified time
created: <ISO 8601 datetime> # Optional — when the concept was first written
updated: <ISO 8601 datetime> # Optional — when the concept was last meaningfully changed
# … other producer-defined key/value pairs
---
```

**Required:**

- `type` — A short string identifying the kind of concept. Consumers
use this for routing, filtering, and presentation. Example values:
`BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
`Playbook`, `Reference`.
- `type` — A short kebab-case string identifying the kind of concept.
Consumers use this for routing, filtering, and presentation. Example
values: `bigquery-table`, `bigquery-dataset`, `api-endpoint`,
`metric`, `playbook`, `reference`.

Type values are **not** registered centrally. Producers SHOULD pick
values that are descriptive and self-explanatory; consumers MUST
Expand All @@ -155,7 +156,12 @@ timestamp: <ISO 8601 datetime> # Optional last-modified time
concept describes. Absent for concepts that describe abstract ideas
rather than physical resources.
- `tags` — A YAML list of short strings for cross-cutting categorization.
- `timestamp` — ISO 8601 datetime of last meaningful change.
- `created` — ISO 8601 datetime when the concept document was first
written. Enrichment agents SHOULD set this on creation and MUST NOT
update it thereafter.
- `updated` — ISO 8601 datetime of the last meaningful change to the
concept's content. Enrichment agents SHOULD update this on every
substantive edit.

**Extensions:** Producers MAY include any additional keys. Consumers
SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject
Expand All @@ -180,12 +186,13 @@ There are no required body sections. The following section headings have

```markdown
---
type: BigQuery Table
type: bigquery-table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
created: 2026-05-01T10:00:00Z
updated: 2026-05-28T14:30:00Z
---

# Schema
Expand All @@ -210,11 +217,12 @@ Joined with [customers](/tables/customers.md) on `customer_id`.

```markdown
---
type: Playbook
type: playbook
title: Incident response — data freshness alert
description: Steps to triage a freshness alert on the orders pipeline.
tags: [oncall, incident]
timestamp: 2026-04-12T09:00:00Z
created: 2026-04-12T09:00:00Z
updated: 2026-04-12T09:00:00Z
---

# Trigger
Expand Down Expand Up @@ -272,8 +280,16 @@ not-yet-written knowledge.

An `index.md` file MAY appear in any directory, including the bundle
root. It enumerates the directory's contents to support **progressive
disclosure** — letting a human or agent see what is available before
opening individual documents.
disclosure** — letting a human or agent discover what is available
before opening individual documents.

`index.md` is **advisory**: it is a convenience for navigation, not an
authoritative record of the directory's contents. Consumers that need
a complete view of a directory MUST fall back to scanning the filesystem
when `index.md` is absent, and MAY do so even when it is present.
Producers that generate `index.md` automatically SHOULD keep it in sync
with the actual files, but consumers MUST NOT treat a missing or stale
entry as evidence that the corresponding concept does not exist.

Index files contain no frontmatter. The body uses one or more sections,
each grouping concepts under a heading:
Expand Down Expand Up @@ -415,12 +431,13 @@ my_bundle/

```markdown
---
type: BigQuery Dataset
type: bigquery-dataset
title: Sales
description: All sales-related tables for the retail business.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
tags: [sales]
timestamp: 2026-05-28T00:00:00Z
created: 2026-05-28T00:00:00Z
updated: 2026-05-28T00:00:00Z
---

The sales dataset contains transactional tables, including
Expand All @@ -431,12 +448,13 @@ The sales dataset contains transactional tables, including

```markdown
---
type: BigQuery Table
type: bigquery-table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
created: 2026-05-28T00:00:00Z
updated: 2026-05-28T00:00:00Z
---

# Schema
Expand Down