Examples
Three complete OQA bundles you can copy file-for-file. Each is a directory of markdown files: a bundle-root index.md that declares the spec version, plus a handful of concepts that link to one another. Every concept carries the one required OKF field — type — along with the recommended base fields and the OQA overlay keys described below. The third uses the QA & Testing profile.
OQA overlay conventions
OQA is a thin profile on top of the Open Knowledge Format. It does not change the base format: a conformant OQA bundle is a conformant OKF bundle. It only adds two custom frontmatter keys — permitted under OKF's extension rule, which lets producers add any keys and requires consumers to tolerate them — and a small set of suggested type values that query agents recognise.
| Key | Source | Meaning |
|---|---|---|
type | OKF (required) | What kind of concept this is. OQA suggests values like API Endpoint, Policy, Metric, and Dataset; unknown values are still valid. |
title, description, resource, tags, timestamp | OKF (recommended) | The standard base fields. resource is omitted for abstract concepts such as a policy or a metric definition. |
summary | OQA overlay | A short, retrieval-oriented gloss an agent can read without opening the body. Longer than description, shorter than the body. |
relations | OQA overlay | A YAML list of typed edges — { predicate, target } — that name the relationship a plain markdown link leaves implicit. target is a bundle-absolute path (beginning with /) to another concept's file. |
Both overlay keys are optional.
A consumer that has never heard of summary or relations still reads the bundle correctly — it sees ordinary concepts with ordinary markdown links. The overlay only makes the relationships explicit for agents that look for them.
Example 1 · Product knowledge
A small bundle describing one public API endpoint and the policy that governs it. The two concepts reference each other, in prose and through relations edges.
product-knowledge/
├── index.md # bundle root: declares okf_version
├── checkout-api.md # type: API Endpoint
└── refund-policy.md # type: Policy
index.md
The bundle-root index.md is the one place frontmatter is allowed in an index file, and the only place okf_version is declared. The body is a plain listing for progressive disclosure.
---
okf_version: "0.1"
---
# Product Knowledge
* [Checkout API](/checkout-api.md) - creates and confirms a customer order
* [Refund Policy](/refund-policy.md) - when and how refunds are issued
checkout-api.md
---
type: API Endpoint
title: Checkout API
description: Creates and confirms a customer order.
resource: https://api.example.com/v1/checkout
tags: [payments, public]
timestamp: 2026-06-24T00:00:00Z
summary: >
POST endpoint that creates an order and charges the saved payment
method, returning an order id and confirmation status. Refund
eligibility for any resulting transaction is set by the refund policy.
relations:
- predicate: governed_by
target: /refund-policy.md
---
# Checkout API
Creates an order and charges the customer's saved payment method. Returns
the order id and a confirmation status.
## Examples
```http
POST /v1/checkout
Content-Type: application/json
{ "cart_id": "c_8123", "payment_method": "pm_saved" }
```
Reversals are governed by the [Refund Policy](/refund-policy.md).
refund-policy.md
An abstract concept — there is no physical asset behind it — so resource is omitted, exactly as the base spec prescribes for non-resource concepts.
---
type: Policy
title: Refund Policy
description: When and how refunds are issued against a checkout transaction.
tags: [payments, policy]
timestamp: 2026-06-24T00:00:00Z
summary: >
Refunds may be issued within 90 days against the original Checkout API
transaction. Full refunds are automatic; partial refunds require an
agent override.
relations:
- predicate: applies_to
target: /checkout-api.md
---
# Refund Policy
Refunds are issued against the original [Checkout API](/checkout-api.md)
transaction within 90 days of the charge.
* Full refunds within 30 days are processed automatically.
* Partial refunds, or refunds after 30 days, require an agent override.
Example 2 · Metrics & datasets
A metric and the dataset it is computed from. The derived_from relation points the agent at the source table; the dataset's resource URI identifies the physical asset.
metrics/
├── index.md # bundle root: declares okf_version
├── metrics/
│ └── weekly-active-users.md # type: Metric
└── datasets/
└── user-events.md # type: Dataset
index.md
---
okf_version: "0.1"
---
# Metrics
## Metrics
* [Weekly Active Users](/metrics/weekly-active-users.md) - distinct users active in a 7-day window
## Datasets
* [User Events](/datasets/user-events.md) - raw client and server activity events
metrics/weekly-active-users.md
A metric definition is abstract, so it carries no resource. Its relations edge records that it derives from the events dataset; an agent answering "where does WAU come from?" follows that edge.
---
type: Metric
title: Weekly Active Users
description: Count of distinct users with at least one activity event in a 7-day window.
tags: [growth, engagement]
timestamp: 2026-06-24T00:00:00Z
summary: >
WAU is the count of distinct user_id values that produced at least one
activity event in a trailing 7-day window. Computed from the User Events
dataset; excludes internal and bot accounts.
relations:
- predicate: derived_from
target: /datasets/user-events.md
---
# Weekly Active Users
The count of distinct users with at least one activity event in a trailing
7-day window.
## Definition
Distinct `user_id` values in [User Events](/datasets/user-events.md) where
`event_type` is an activity event, over the last 7 days. Internal and bot
accounts are excluded.
datasets/user-events.md
The dataset is a physical asset, so it includes a resource URI and a # Schema section — the conventional heading for an asset's columns.
---
type: Dataset
title: User Events
description: One row per client or server activity event.
resource: https://console.cloud.google.com/bigquery?p=acme&d=product&t=user_events
tags: [events, raw]
timestamp: 2026-06-24T00:00:00Z
summary: >
Append-only event log, one row per activity event, keyed by user_id and
event_time. Source for engagement metrics such as Weekly Active Users.
relations:
- predicate: feeds
target: /metrics/weekly-active-users.md
---
# User Events
Append-only log of client and server activity events. One row per event.
## Schema
| Column | Type | Description |
| ----------- | --------- | ------------------------------------ |
| user_id | STRING | Stable identifier for the user. |
| event_type | STRING | Activity verb, e.g. `page_view`. |
| event_time | TIMESTAMP | When the event occurred (UTC). |
Feeds the [Weekly Active Users](/metrics/weekly-active-users.md) metric.
Example 3 · QA & testing
A software-quality bundle using the QA & Testing profile. One feature (password reset) traced end to end: the user story, a test case that verifies it, the automated check that runs it, a bug found against it, and the exploratory session that surfaced the bug. The relations edges turn these files into a traceability graph an agent can walk — "what verifies this story?", "where did this bug come from?".
qa/
├── index.md
├── stories/
│ └── password-reset.md # type: User Story
├── test-cases/
│ └── reset-link-expiry.md # type: Test Case
├── automated/
│ └── reset-link-expiry.e2e.md # type: Automated Test
├── bugs/
│ └── reset-link-expires-ios.md # type: Bug Report
└── sessions/
└── auth-mobile.md # type: Exploratory Session
stories/password-reset.md
---
type: User Story
title: Password reset
description: A signed-out user can reset a forgotten password by email.
acceptance_criteria:
- A reset email is sent within 60 seconds of request.
- The reset link remains valid for at least 30 minutes.
- Using the link lets the user set a new password and sign in.
status: active
tags: [auth, account-recovery]
relations:
- predicate: verified_by
target: /test-cases/reset-link-expiry.md
---
# Password reset
As a signed-out user, I can request a password-reset email and use the
link to set a new password.
test-cases/reset-link-expiry.md
---
type: Test Case
title: Reset link is honored within its validity window
test_type: functional
priority: high
status: active
preconditions: An account exists with a known, verified email address.
steps:
- action: Request a password reset for the account.
expected: A reset email arrives within 60 seconds.
- action: Open the reset link within 30 minutes.
expected: The set-new-password form loads (no "expired" error).
- action: Set a new password and sign in.
expected: Sign-in succeeds with the new password.
relations:
- predicate: verifies
target: /stories/password-reset.md
- predicate: automated_by
target: /automated/reset-link-expiry.e2e.md
---
# Reset link is honored within its validity window
Confirms the reset link works through its full validity window — the
guarantee the [password reset story](/stories/password-reset.md) makes.
bugs/reset-link-expires-ios.md
The bug carries candidate remedies and attaches a screenshot via the media key — and links back to the test case it relates to, the story it blocks, and the session that found it.
---
type: Bug Report
title: Reset link expires immediately on Safari iOS
severity: s2
status: confirmed
root_cause: environment
environment:
browser: Safari
os: iOS 18.2
url: https://app.example.com/reset
steps_to_reproduce:
- Request a password reset on Safari iOS.
- Open the emailed reset link within one minute.
- Observe the "link expired" error before any input.
remedies:
- Compare token expiry in UTC instead of device-local time.
- Workaround — open the reset link in Chrome until the fix ships.
media:
- resource: https://cdn.example.com/bugs/reset-expired-ios.png
caption: Expired-link error on first open (Safari iOS).
summary: >
On Safari iOS the reset link reports "expired" on first open because the
token expiry is compared in device-local time rather than UTC.
timestamp: 2026-06-24T00:00:00Z
relations:
- predicate: relates_to
target: /test-cases/reset-link-expiry.md
- predicate: blocks
target: /stories/password-reset.md
- predicate: found_in
target: /sessions/auth-mobile.md
---
# Reset link expires immediately on Safari iOS
Token expiry is compared in device-local time rather than UTC, so the link
looks expired on first open. Blocks the
[password reset story](/stories/password-reset.md); found during the
[mobile auth session](/sessions/auth-mobile.md).
Next
All three bundles are conformant: every concept has a parseable frontmatter block with a non-empty type, and each index.md is a plain listing. For the field reference see the Open Knowledge Format base spec; for the summary and relations conventions see the OQA layer. To build one from scratch, start with the Quickstart.