Open Knowledge Format (base)

The Open Knowledge Format (OKF) is an open, human- and agent-friendly format for representing knowledge — the metadata, context, and curated insight that surrounds data and systems. It is designed to be authored by people, generated by agents, exchanged across organizations, and consumed by both.

OKF v0.1 is published by Google Cloud in the GoogleCloudPlatform/knowledge-catalog repository. This page is a faithful reference of that base format. OQA adopts OKF verbatim and adds only conventions on top — see the OQA layer for the query-agent conventions, and the Quickstart for a worked example.

Purpose, bundles & concepts

OKF is intentionally minimal: a directory of markdown files with YAML frontmatter. There is no schema registry, no central authority, and no required tooling.

Two terms anchor the format:

• Knowledge Bundle — a self-contained, hierarchical collection of knowledge documents. The unit of distribution.
• Concept — a single unit of knowledge within a bundle, represented as one markdown document. A concept may describe a tangible asset (a table, an API), an abstract idea (a metric, a business process), or anything in between.

Supporting terms:

• Concept ID — the path of the concept's file within the bundle, with the .md suffix removed. For example, tables/users.md has concept ID tables/users.
• Frontmatter — a YAML metadata block delimited by --- at the top of a markdown file.
• Body — everything in the file after the frontmatter.
• Link — a standard markdown link from one concept to another, used to express relationships beyond the implicit parent/child hierarchy.
• Citation — a link from a concept to an external source that supports a claim in the body.

OKF defines no fixed taxonomy of concept types, prescribes no storage, serving, or query infrastructure, and does not replace domain schemas such as Avro, Protobuf, or OpenAPI — OKF references them; it does not subsume them.

The required type field

A concept's frontmatter has exactly one required field: type. It is a short string identifying the kind of concept. Consumers use it for routing, filtering, and presentation. Example values: BigQuery Table, BigQuery Dataset, API Endpoint, Metric, Playbook, Reference.

Type values are not registered centrally. Producers SHOULD pick values that are descriptive and self-explanatory; consumers MUST tolerate unknown types gracefully, typically by treating them as generic concepts.

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---

Optional fields

Beyond type, all frontmatter fields are optional. The spec recommends the following, in priority order:

A concept that describes an abstract idea — say a Playbook — simply omits resource. Tags are a first-class concept via the tags field; OKF specifies no separate tag-aggregation file. A tag-browsing view is synthesized at consumption time by scanning frontmatter.

Custom keys & the round-trip rule

Producers MAY include any additional frontmatter keys. Consumers SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject documents with unrecognized fields.

Bundle structure & reserved files

A bundle is a directory tree of markdown files. The directory structure is independent of the domain.

path/to/bundle/
├── index.md            # Optional. Directory listing for progressive disclosure.
├── log.md              # Optional. Chronological history of updates.
├── <concept>.md        # A concept at the bundle root.
└── <subdirectory>/     # Subdirectories organize concepts into groups.
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/ …

A bundle MAY be distributed as a git repository (recommended), a tarball or zip, or a subdirectory within a larger repo.

Two filenames are reserved — they have defined meaning at any level of the hierarchy and MUST NOT be used for concept documents. All other .md files are concept documents.

index.md

An index.md MAY appear in any directory, including the root. It enumerates the directory's contents to support progressive disclosure — letting a human or agent see what is available before opening individual documents. Its body is sections of bulleted links of the form * [Title](url) - description, and entries SHOULD include the linked concept's description. Producers MAY generate it; consumers MAY synthesize one when none is present.

log.md

A log.md MAY appear at any level to record the history of changes to that scope. It is a flat list of date-grouped entries, newest first. Date headings MUST use the ISO 8601 YYYY-MM-DD form. A leading bold word such as **Update**, **Creation**, or **Deprecation** is a convention, not a requirement.

The okf_version exception

Index files otherwise contain no frontmatter. The single exception: bundles MAY declare the OKF version they target by including okf_version: "0.1" in a bundle-root index.md frontmatter block — the only place frontmatter is permitted in an index.md.

---
okf_version: "0.1"
---

# My Knowledge

* [Customer Orders](/tables/orders.md) - One row per completed order.

Links & the knowledge graph

Concepts relate to each other through standard markdown links, which come in two forms:

• Absolute (bundle-relative) — begins with /, interpreted relative to the bundle root, e.g. [customers table](/tables/customers.md). This is the recommended form because it is stable when documents are moved within their subdirectory.
• Relative — standard markdown relative paths, e.g. [neighboring concept](./other.md).

A link from concept A to concept B asserts a relationship. The specific kind of relationship — parent/child, references, joins-with, depends-on, and so on — is conveyed by the surrounding prose, not by the link itself. Links are untyped: consumers that build a graph view typically treat all links as directed edges of an untyped relationship.

When a concept body makes externally-sourced claims, sources SHOULD be listed under a # Citations heading at the bottom, numbered [1] [text](url). Citation links MAY be absolute URLs, bundle-relative paths, or paths into a references/ subdirectory.

Versioning

This format is OKF version 0.1. Future revisions are versioned as <major>.<minor>:

• A minor version bump introduces backward-compatible additions (new optional fields, new conventional section headings).
• A major version bump may make breaking changes (renaming required fields, changing reserved filenames).

Consumers that do not understand the declared version SHOULD attempt best-effort consumption rather than refusing the bundle.

Conformance

A bundle is conformant with OKF v0.1 if it meets three hard requirements:

• Every non-reserved .md file in the tree contains a parseable YAML frontmatter block.
• Every frontmatter block contains a non-empty type field.
• Every reserved filename (index.md, log.md) follows its defined structure when present.

Consumers SHOULD treat all other constraints as soft guidance. In particular, consumers MUST NOT reject a bundle because of:

• Missing optional frontmatter fields.
• Unknown type values.
• Unknown additional frontmatter keys.
• Broken cross-links.
• Missing index.md files.

For the conventions OQA adds on top of this base — without changing any of it — continue to the OQA layer.