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

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

> **Note:** Google Cloud published OKF v0.2 at
> [GoogleCloudPlatform/open-knowledge-format](https://github.com/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); the bundle-local `verified:` date stamp and `tags`
> discipline are producer extensions compatible with both versions.

# 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

```yaml
---
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:

```markdown
# 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

```markdown
# 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:**

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

**Relative links:**

```markdown
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](okf-maintenance.md) — How to keep your bundle from rotting.
- [Root Index](/index.md) — This bundle's structure and navigation.