OQA is a thin, vendor-neutral overlay for agentic knowledge bundles. It builds on Google Cloud's Open Knowledge Format (OKF): OKF defines the markdown/frontmatter container, while OQA adds conventions that help autonomous query agents navigate, retrieve, and reason over that knowledge.
The public website is oqa.ai. This repository is the public developer-facing home for the draft specification, examples, and contribution workflow.
OQA v0.1 is an early draft. The vocabulary, relationship predicates, and profile keys will evolve as the format is tested against real agents and real quality workflows.
The hard rule is inherited from OKF: an OQA bundle is still an OKF bundle. OQA conventions are additive and SHOULD-level unless the base OKF spec says otherwise.
docs/
overview.md What OQA is and how it relates to OKF
quickstart.md Build a minimal bundle in minutes
okf.md Base OKF reference used by OQA
oqa-layer.md OQA overlay conventions
qa-testing-profile.md QA/testing domain profile
examples.md Guide to the included bundles
examples/
product-knowledge/ API endpoint + policy bundle
metrics/ Metric + dataset bundle
qa/ QA traceability bundle
scripts/
validate-bundle.mjs Tiny example-bundle validator
An OQA bundle is just a directory of markdown files. Every concept is a markdown file with YAML frontmatter. The only required field for a concept is type.
---
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.
relations:
- predicate: governed_by
target: /refund-policy.md
---
# Checkout API
Creates an order and charges the customer's saved payment method.Validate the included examples:
npm install
npm run validate:examples- OKF-compatible: OQA never forks OKF. A valid OQA bundle is a valid OKF bundle.
- Markdown-native: humans can read it in any editor; agents can traverse it deterministically.
- Soft conventions: unknown types, unknown keys, and broken links are tolerated by consumers.
- Typed relationships: optional
relationsfrontmatter lets agents see graph edges without parsing prose. - Retrieval hints: optional
summary,keywords, andaliasesimprove retrieval without changing conformance.
See CONTRIBUTING.md. The most useful contributions at this stage are:
- real-world example bundles,
- corrections to ambiguous wording,
- relationship predicate proposals,
- feedback from agent/indexer implementations,
- QA/testing profile refinements.
MIT. See LICENSE.