command-center/omp-docs/references/okf-spec.md

type, title, description, resource, tags, verified, timestamp

type	title	description	resource	tags	verified	timestamp
reference	Open Knowledge Format (OKF) v0.1 Specification	Complete specification for OKF knowledge bundles — a directory of markdown files with YAML frontmatter.	https://github.com/GoogleCloudPlatform/open-knowledge-format	okf documentation knowledge-bundle specification	2026-10-19	2026-01-15

Note: Google Cloud published OKF v0.2 at GoogleCloudPlatform/open-knowledge-format (SPEC.md, verified 2026-10-19). v0.2 is a minor bump with two deliberate breaking changes: timestamp is superseded by generated: { by, at }, and the body # Citations list is superseded by a sources frontmatter family; it adds optional trust/lifecycle fields (verified: { by, at }, status, stale_after) and the Attested Computation type, and permits okf_version: frontmatter in a bundle-root index.md. This bundle stays on v0.1 semantics (kb-lint enforces them). What the optional fields mean HERE, measured 2026-10-21: description on every concept page; tags on 22 of 76 concept pages and no tool reads them; resource only where the page describes an external thing; verified: YYYY-MM-DD = "the facts on this page were re-checked against the fleet that day", and a page with no verified has never been re-checked. House link style is bundle-absolute (/tools/niri/tips.md) for anything crossing a directory. [[wikilinks]] are not OKF links — this bundle's 53 of them were converted to markdown links on 2026-10-21.

Open Knowledge Format (OKF) v0.1

OKF is the answer to "everyone has knowledge, but nobody speaks the same language." Every agent, catalog, wiki, and metadata store represents knowledge differently — and every agent builder is reinventing the context-assembly wheel.

OKF v0.1 formalizes the "LLM wiki" pattern into a portable, interoperable format. The entire specification is simple enough to fit on a single page:

A directory of markdown files with YAML frontmatter.

That's it. No schema registry. No central authority. No SDK. No runtime. If you can cat a file, you can read OKF. If you can git clone a repo, you can ship it.

---

What's in a Bundle?

An OKF knowledge bundle is a directory tree. Every concept is one file. The file path is the concept's identity.

my-bundle/
├── index.md                      # Optional directory listing
├── log.md                        # The bundle's ONE update history — root only
├── concept-one.md                # A concept at the root level
└── subdirectory/
    ├── index.md                  # Optional subdirectory listing
    ├── concept-two.md            # A concept in a subdirectory
    └── another-concept.md        # Another concept

Reserved filenames (MUST NOT use for concepts):

Filename	Purpose
index.md	Directory listing for progressive disclosure
log.md	Chronological update history — exactly one, at the bundle root

One work log per bundle. log.md is reserved, and it is reserved for a single file: the bundle root's. A subdirectory never keeps its own change log — a bundle that logs in fifty places has no log, because the entry is never where the next reader looks and every copy re-dates the same event. scripts/kb-lint.sh reports any log.md that is not the root's.

---

Anatomy of a Concept Document

---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI>
tags: [<tag>, <tag>, …]            # Optional
timestamp: <ISO 8601 datetime>     # Optional
---

Required Fields

Field	Required?	What it does
type	Yes	Identifies the kind of concept. Used for routing, filtering, presentation.
title	No	Human-readable display name.
description	No	Single-sentence summary. Used by index generators, search snippets, previews.
resource	No	URI identifying the underlying asset.
tags	No	YAML list for cross-cutting categorization.
timestamp	No	ISO 8601 datetime of last meaningful change.

---

Index Files — Progressive Disclosure

An index.md in any directory lets a human or agent see what's available:

# Sales Tables

* [Orders](tables/orders.md) - One row per completed customer order.
* [Customers](tables/customers.md) - Customer account information.

Rules: No frontmatter. Relative paths. One section per heading. Entries include description from linked concept's frontmatter.

---

Log Files — Change History

# Directory Update Log

## 2026-05-22
* **Update**: Added new reference for [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).

• Date headings MUST use YYYY-MM-DD
• Entries grouped newest-first
• Leading bold word is a convention, not a requirement

---

Cross-linking

Absolute (bundle-relative) links — RECOMMENDED:

See the [customers table](/tables/customers.md) for the join key.

Relative links:

See the [neighboring concept](./other.md).

Consumers MUST tolerate broken links.

---

Conformance Rules

A bundle is conformant with OKF v0.1 if and only if:

1. Every non-reserved .md file contains a parseable YAML frontmatter block.
2. Every frontmatter block contains a non-empty type field.
3. Every reserved filename follows the structure described here when present.

Everything else is soft guidance. Consumers MUST NOT reject a bundle because of missing optional fields, unknown types, or broken links.

---

Common Mistakes

• ❌ Forgetting the type field — this is the only strictly required field
• ❌ Using type: file or type: document — be specific: type: BigQuery Table, type: API Endpoint
• ❌ Putting frontmatter in index.md — index files are directory listings, not concepts
• ❌ Using relative links for concepts in different directories — use absolute paths
• ❌ Writing one giant index.md that lists everything — use index.md at multiple levels
• ❌ Skipping # Citations for factual claims — cite external sources under # Citations

---

See Also

• OKF Bundle Maintenance — How to keep your bundle from rotting.
• Root Index — This bundle's structure and navigation.

Citations

• GoogleCloudPlatform/open-knowledge-format — upstream repository: the v0.1 specification this page summarizes and SPEC.md for v0.2 (read 2026-10-19).