# Open Knowledge Format | Corvair Knowledge Substrate

Open Knowledge Format (OKF), the open record kept for every document: its standard fields, the Corvair extensions, and search tables rebuilt with no model call.

Canonical: <https://corvair.ai/cks/okf.html>

## Open Knowledge Format

The Open Knowledge Format (OKF) is an open, vendor-neutral standard from Google Cloud for keeping knowledge as plain Markdown files, each with a short block of YAML front matter that describes it. The specification is published under the Apache 2.0 licence at [github.com/GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format).

Corvair Knowledge Substrate uses OKF as its own core format, not only for export. Every document it reads is kept as one OKF bundle, and that bundle is the record of truth. The index database is built from the bundles and can be rebuilt from them at any time, with no model call. Any tool that reads OKF can open a bundle, and a base can be exported as standard OKF and taken elsewhere intact.

### What the standard provides

The Knowledge Substrate writes OKF 0.2, the current version. These standard fields carry most of what a reader needs.

| Field | What it records |
| --- | --- |
| `type`, `title`, `description` | What the entry is, and a short summary of it. |
| `generated` | How and when the content was produced: the reading pipeline and its version, or the service that generated it. |
| `sources` | Where the content came from: the file or page, its author and when it last changed. A footnote ties each passage and claim to its source. |
| `verified` | Each check made, by a machine or by a person. From these, OKF's trust level follows: unverified, machine-confirmed or human-reviewed. |
| `status`, `stale_after` | Draft, stable or deprecated, and the date after which the content is stale. |
| `log.md` | A dated history of changes to the bundle, newest first. |

A document's front matter, simplified

```
type: document
title: Halden supply agreement, version 3
description: Supply terms between Northcott and Halden, including notice and price review.
generated: { by: cks-ingest/2.4, at: 2026-11-08T10:14:00+08:00 }
sources:
  - { id: s1, resource: halden-supply-v3.pdf, author: Halden Ltd,
      last_modified: 2026-10-30T09:00:00+08:00 }
verified:
  - { by: cks-claim-check, at: 2026-11-08T22:05:00+08:00 }
status: stable
stale_after: 2027-11-08T00:00:00+08:00
x-cks:   # the Knowledge Substrate's extension block, below
```

Sample data. Every time carries its time-zone offset, as OKF 0.2 requires.

### What the Knowledge Substrate adds

OKF readers must accept keys they do not know. Everything the standard does not cover is kept in one extension block, `x-cks`, so any OKF reader can still open the bundle and simply skip what it does not use.

| Extension | What it holds | Why it is needed |
| --- | --- | --- |
| Source tier | Tier 1 to Tier 4: licensed expertise, your own content, outside sites, or generated. | OKF's trust level says who checked the content. The source tier says where it came from. Both are kept. |
| Claims and their checks | Each claim's exact text, the passage it came from, and the result of its check. | So the index can be rebuilt without reading the document again. |
| Topics and terms | The base's topics, keywords and named things, with their other names. | Search by other names and spellings. |
| Typed relationships | Supersedes, cites, supports and contradicts, between documents and claims. | OKF links carry no type. |
| Classification | Sensitivity, personal data found, and language. | Not yet in the standard. |
| Fingerprint and entitlement | A fingerprint of the source's bytes, how it was collected, and who may use it under which licence. | Integrity, and licensed content. |
| Validity | How fast this kind of content goes stale. | The standard keeps only the resulting `stale_after` date. |

### How it is kept current

- **Pinned to the standard.** The Knowledge Substrate pins an exact version of the specification from Google Cloud's repository, and checks that repository at each release.
- **The extension is versioned on its own.** A change to `x-cks` never breaks a reader of the standard fields.
- **Moving to the standard as it grows.** When OKF adds a field for something the extension already holds, bundles move to the standard field, and readers accept the old one for one release. OKF 0.2's `sources`, `generated` and `deprecated` status replaced three of the Knowledge Substrate's own fields this way.
- **Proposed upstream.** Extensions that would help others, such as fingerprints, sensitivity, licences and typed links, will be proposed to the standard.
- **Export is plain OKF.** An exported base is standard OKF bundles with the extension block alongside, so it can be read without Corvair.

## The record

The Knowledge Substrate writes the record as the document is read. Each load is a new version. Nothing is edited in place. One record holds these parts.

| Part | What it holds |
| --- | --- |
| Front matter | Where the document came from, its source tier and its source role. |
| Description | A summary, with the document's topics and tags. |
| Section entries | The passage text and where each passage sits in the document. |
| Entity entries | Named things in the document, with their other names. |
| Links | Links to other documents: which one it supersedes and which it cites. |
| Claim entries | The claims taken from the document. Present only when claims are on for the base. |

## The tables built from it

The Knowledge Substrate builds its search tables in the index database from the records. No model call is needed. The links between claims are the one thing kept outside the records, because a scheduled link run produces them.

| Table | What it holds | Built from |
| --- | --- | --- |
| Documents | One row per document: tier, type, source role, dates, summary and keywords. | The record |
| Passages | Passage text, heading path and location, with the indexes that search uses. | The record |
| Topics | The base's topics, and which documents carry each. | The topic map and the tagging step |
| Terms and aliases | Keywords and named things, their other names, and where they appear. | The tagging step |
| Document links | Which document supersedes or cites another. | The record |
| Claims | One row per claim: its document, passage, text and the result of its checks. | The record |
| Mentioned together | Pairs of terms and how many documents share them. A stored query, refreshed after each load. | The tables above |
| Claim links | Links between claims, every pair judged, and the weight of each claim. | The link run, not the record |

Because the record is the source of truth, a table that is lost or changed is rebuilt from the records. Claim links are not in the records. To get them back, run the link run again or restore the database backup.

[![The state of a library's records: the record store compared with the search index, records written each day, trust tiers, and checks against the format](https://corvair.ai/assets/images/cks/screens/user-okf-state.webp)](https://corvair.ai/assets/images/cks/screens/user-okf-state@2x.webp)

## The catalog round trip

A catalog is where an organisation lists the knowledge it holds. Because the Knowledge Substrate already keeps its knowledge as OKF, it reads and writes what a catalog exchanges. The exchange runs both ways, and it is not tied to one catalog product.

| Direction | What happens |
| --- | --- |
| The Knowledge Substrate into the catalog | The Knowledge Substrate publishes its records to a place the catalog reads. The catalog then lists them and serves them to its own agents. |
| The catalog into the Knowledge Substrate | The Knowledge Substrate reads OKF from a catalog and loads it like any other source. It needs no custom extractor. |

### Into the catalog

The records the Knowledge Substrate already keeps are what it publishes. Extra Knowledge Substrate fields sit under their own key. A reader that does not know them ignores them, and the record stays valid OKF.

### Into the Knowledge Substrate

When the input is already OKF, the Knowledge Substrate skips parsing and extraction. It checks that the record is valid, loads it, and builds the same tables as for any other document. Where a catalog holds metadata in another shape, a small adapter turns it into OKF first, so the Knowledge Substrate sees one format whichever catalog it came from.

Agents that find knowledge in a catalog can call the Knowledge Substrate over MCP for the rest. See [API, MCP and the command line](https://corvair.ai/cks/api.html).
