The OQA layer

OQA is a thin overlay on the Open Knowledge Format (OKF) for one specific consumer: the autonomous query agent. Where OKF defines the container — a directory of markdown files with YAML frontmatter — OQA adds a small set of conventions that make a bundle easier for a retrieval-augmented agent to navigate, rank, and reason over.

OQA adds conventions only: recommended type values, a handful of optional custom frontmatter keys, and link conventions. It introduces no new required structure, and nothing in it may contradict OKF. An OQA bundle is an OKF bundle.

1 · Principles

Four principles govern everything OQA does. When in doubt, they decide.

• Overlay. OQA is a profile of OKF for query agents, not a competing format. It rides on top of the same files; it does not fork them.
• OKF-conformant. An OQA bundle is, first and always, a conformant OKF bundle. The only hard requirements are OKF's: parseable frontmatter and a non-empty type on every concept. If anything here ever appears to conflict with OKF, OKF wins.
• Soft. Like OKF, OQA is permissive. Every convention is SHOULD-level. Consumers tolerate absence: missing keys, unknown type values, untyped links, and broken cross-links must never cause a bundle to be rejected.
• Additive. OQA only adds recommended values and optional custom keys — the kind OKF already permits under its extensions rule. It never adds new required fields and never redefines a reserved file.

2 · Concept type vocabulary

OKF requires a type on every concept but deliberately does not register type values centrally — producers pick descriptive strings, and consumers must tolerate unknown ones. OQA offers a recommended starting vocabulary for query-agent knowledge so that common kinds of concept get described consistently across bundles. These values are a suggestion, not an enumeration.

For software-quality knowledge specifically — test cases, user stories, bug reports, automated web & mobile tests, performance, accessibility, and security tests, and exploratory sessions — see the QA & Testing profile, a domain vocabulary built on these same conventions.

3 · Relationships

OKF expresses relationships with ordinary markdown links: a link from concept A to concept B asserts a relationship, and the kind of relationship lives in the surrounding prose, not in the link. Consumers building a graph treat all links as edges of a single untyped relation. This is enough for a human reader, but a query agent often benefits from knowing which relationship an edge represents.

OQA's convention is layered, so the prose form always remains the source of truth:

• Prose-labeled links (primary). Keep writing ordinary OKF links and let the surrounding sentence name the relationship — depends on, derived from, joins with, and so on. This requires nothing new and works for every consumer.
• An optional relations key (machine-readable). A concept MAY additionally declare typed edges in frontmatter under a custom relations key: a YAML list of { predicate, target } objects, where predicate is a short relationship verb and target is a bundle-absolute path to another concept's file.

Because relations is just an additional frontmatter key, it falls squarely under OKF's extensions rule — consumers that do not understand it preserve it on round-trip and ignore it.

---
type: Metric
title: Net Revenue
description: Recognized revenue after refunds and credits, by day.
relations:
  - predicate: derived_from
    target: /datasets/orders.md
  - predicate: excludes
    target: /policies/refunds.md
  - predicate: defined_in_terms_of
    target: /glossary/recognized-revenue.md
timestamp: 2026-06-24T00:00:00Z
---

# Net Revenue

Daily recognized revenue, net of refunds. Derived from the
[orders dataset](/datasets/orders.md); refunded lines are excluded
per the [refund policy](/policies/refunds.md).

The target of each relation SHOULD be a bundle-absolute path (beginning with /), the form OKF recommends because it stays stable as files move. As with any OKF link, a target that does not yet exist in the bundle is tolerated — it may simply be not-yet-written knowledge.

4 · Retrieval hints

Query agents typically embed and chunk concepts before retrieving them. OQA defines a few optional custom keys that give the producer a place to hand the agent better retrieval signal. All of them are optional OKF extension keys; omitting them changes nothing about conformance.

• summary — a dense, self-contained 1–2 sentence summary of the concept, written to be embedded directly. Distinct from OKF's description (a single human-facing sentence for snippets and index listings): summary exists to carry retrieval signal and may pack in more substance.
• keywords — a YAML list of salient terms a user might search for that may not appear verbatim in the body.
• aliases — a YAML list of alternate names the concept goes by, so a query agent can resolve synonyms to this concept.

---
type: Glossary Term
title: ARR
description: Annual recurring revenue.
summary: >
  ARR is the annualized value of active subscription contracts at a
  point in time, excluding one-time fees; it is the run-rate measure
  used in board reporting.
keywords: [recurring revenue, run rate, subscriptions, annualized]
aliases: [annual recurring revenue, annualized recurring revenue]
---

# ARR

Chunking guidance. OQA recommends authoring so that one concept is one retrievable unit: keep a concept focused enough that the whole file can be embedded and returned as a coherent answer fragment. When a topic grows too large for that, split it into multiple concepts linked by relations rather than letting a single file sprawl. This is guidance for producers, not a constraint on consumers.

5 · Identity & freshness

OQA leans on two fields OKF already defines rather than inventing identity or versioning of its own.

• Identity — resource. When a concept describes a real underlying asset, OQA uses OKF's resource URI as the concept's stable identifier: the thing that lets an agent recognize two concepts (across bundles or revisions) as describing the same asset, and deduplicate accordingly. Concepts that describe abstract ideas have no resource, exactly as in OKF; for those, the concept's path within the bundle remains the identifier.
• Freshness — timestamp. OQA uses OKF's timestamp (ISO 8601, last meaningful change) as a recency signal for ranking. When two concepts are equally relevant to a query, an agent MAY prefer the one with the more recent timestamp. Absence is tolerated; it simply means recency is unavailable for that concept.

OQA adds no new identity or version field. This is deliberate — reusing OKF's fields keeps an OQA bundle indistinguishable from a plain OKF bundle.

6 · Conformance

A bundle is OQA-conformant when it is OKF-conformant and follows the SHOULD-level conventions on this page where they apply. Concretely:

• It meets every OKF v0.1 hard requirement — parseable frontmatter on every non-reserved .md file, a non-empty type on each, and well-formed index.md / log.md when present. These are the only hard requirements an OQA bundle has.
• It SHOULD draw type values from the recommended vocabulary (§2) when one fits, while remaining free to coin others.
• It SHOULD label relationships in prose, and MAY additionally declare typed edges via relations (§3).
• It MAY supply retrieval hints — summary, keywords, aliases — and SHOULD favor one-concept-one-unit chunking (§4).
• It SHOULD use resource for identity and timestamp for freshness (§5).

Nothing beyond the OKF hard requirements is mandatory. A consumer MUST NOT reject a bundle for missing any OQA convention — no relations, no summary, an unrecognized type, or a broken target are all acceptable. OQA's conformance bar is exactly OKF's bar plus a set of recommendations; it never adds a way for a bundle to fail.