Knowledge Catalog Bundle Structure: A Complete Guide to the Open Knowledge Format

A Knowledge Catalog bundle is a self‑contained directory of markdown documents that follows the Open Knowledge Format (OKF) specification, combining YAML front‑matter for structured metadata with flexible markdown content to create a human‑readable and machine‑parseable knowledge graph.

The GoogleCloudPlatform/knowledge-catalog repository defines this format to enable organizations to build hierarchical, portable knowledge bases without proprietary tooling. A bundle requires nothing more than a standard filesystem and markdown files, making it compatible with any version control system or static site generator.

Directory-Tree Layout

A Knowledge Catalog bundle uses a plain‑folder hierarchy where the directory structure itself conveys semantic meaning. Each markdown file (*.md) represents a concept, while subfolders group related concepts into logical domains. This layout is intentionally flexible and can mirror any organizational structure, from data warehouse schemas to API documentation.

According to the specification in okf/SPEC.md (lines 71‑88), the canonical structure resembles a standard documentation site:

my_bundle/
├── index.md
├── datasets/
│   ├── index.md
│   └── sales.md
└── tables/
    ├── index.md
    ├── orders.md
    └── customers.md

The root folder acts as the bundle entry point, with nested directories creating taxonomic depth. Unlike rigid database schemas, this filesystem‑based approach allows knowledge to evolve organically by simply moving or renaming files.

Reserved Filenames and Special Files

Certain filenames carry special semantic meaning regardless of their location in the hierarchy. As defined in okf/SPEC.md (lines 95‑104), these reserved names must not be used for ordinary concept documents.

index.md

An optional directory‑listing file that enables progressive disclosure. When present, it provides a curated overview of sibling and child concepts, acting as a navigation hub for that directory level. The repository includes a real‑world example at okf/bundles/stackoverflow/index.md demonstrating how root indices organize large collections.

log.md

An optional chronological log of updates, changes, or maintenance notes for the bundle or specific subdirectories. This creates an audit trail without polluting the concept documents themselves.

Concept Documents

Every other .md file in the bundle is treated as a concept document consisting of two mandatory parts: a YAML front‑matter block and a markdown body.

The specification (lines 24‑34 and 124‑134) requires the front‑matter to include at minimum a type field, with optional keys for title, description, resource, tags, and timestamp. The body follows standard markdown conventions, often using conventional headings like # Schema, # Examples, or # Citations to structure content.

A concrete example from okf/bundles/crypto_bitcoin/tables/transactions.md illustrates this structure:

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

# Schema

| Column        | Type      | Description                  |
|---------------|-----------|------------------------------|
| `order_id`   | STRING    | Unique order identifier.     |
| `customer_id`| STRING    | FK to [customers](/tables/customers.md). |
| `total_usd`  | NUMERIC   | Order total in USD.          |

This format ensures that automated agents can extract structured metadata while humans read natural language documentation.

Cross-Linking Between Concepts

Knowledge Catalog bundles support two styles of markdown links to create relationships between concepts without imposing a fixed schema. The specification (lines 38‑53) defines both absolute and relative linking strategies.

Absolute (bundle‑relative) links start with / and resolve from the bundle root, making them resilient to file moves within a directory:

The sales dataset contains the [orders table](/tables/orders.md) and the [customers table](/tables/customers.md).

Relative links use standard filesystem paths (e.g., ../customers.md) and resolve against the current file's location. Absolute links are recommended for maintaining stable relationships across deep hierarchies.

Distribution Formats

As specified in okf/SPEC.md (lines 89‑94), bundles are designed for portability and can be distributed through multiple channels:

• Git repositories – enabling version control and collaborative editing
• Tarball or ZIP archives – for offline distribution or secure environments
• Subdirectories – allowing multiple bundles to coexist within a larger monorepo

This flexibility ensures that knowledge assets can move between development, staging, and production environments without format conversion.

Summary

• A Knowledge Catalog bundle follows the Open Knowledge Format (OKF) defined in the GoogleCloudPlatform/knowledge-catalog repository.
• The structure is a plain directory tree of markdown files, where folders represent domains and files represent concepts.
• index.md and log.md are reserved filenames that provide directory navigation and change logging.
• Each concept document requires YAML front‑matter with a type field and supports a free‑form markdown body.
• Cross‑links use bundle‑relative absolute paths (/path/to/file.md) or relative paths to build knowledge graphs.
• Bundles can be distributed as Git repos, compressed archives, or embedded subdirectories.

Frequently Asked Questions

What is the minimum required structure for a valid Knowledge Catalog bundle?

A valid bundle requires only a root directory containing markdown files with the .md extension. While the specification supports optional files like index.md and log.md, the only strict requirement is that concept documents include YAML front‑matter with a type field. A single file named concept.md with valid front‑matter constitutes a functional bundle.

Can I use subdirectories to organize concepts hierarchically?

Yes. The directory tree is the primary organizational mechanism in the Open Knowledge Format. You can nest concepts arbitrarily deep using subfolders, and each directory may optionally contain an index.md file to provide context for that branch of the hierarchy. This design mirrors filesystem conventions and requires no additional configuration files.

How do I reference one concept from another without breaking links?

Use absolute bundle‑relative links that start with a forward slash (/). These links resolve from the bundle root regardless of the source file's depth in the directory tree. For example, /tables/customers.md correctly references the customers concept whether the link appears in a root‑level file or a nested documentation page, making your knowledge graph resilient to restructuring.

Is the Knowledge Catalog bundle format tied to specific tools or platforms?

No. The format is intentionally tool‑agnostic. Because bundles are plain text files (markdown with YAML front‑matter) organized in standard directories, they can be edited with any text editor, versioned with Git, served by static site generators, or parsed by custom automation scripts. The specification requires only a filesystem and a YAML parser, ensuring compatibility across operating systems and cloud platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}