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-08-28	2026-01-15

Note: Google Cloud published OKF v0.2 at GoogleCloudPlatform/open-knowledge-format with additional frontmatter families for provenance, trust, and attestation. This document covers the v0.1 format used by this knowledge bundle.

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                        # Optional update history
├── 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

---

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.