Google Cloud Releases Open Knowledge Format to Standardize AI Agent Context

Google Cloud has released version 0.1 of the Open Knowledge Format, an open, vendor-neutral specification designed to standardize how AI agents and humans share organizational context. Published on June 12, 2026, the specification represents curated knowledge as a directory of standard Markdown files with YAML metadata. The format aims to streamline AI knowledge retrieval, allowing agents to natively navigate and update documentation without relying on proprietary databases or platform-specific software development kits.

Core Structural Components: Bundles, Concepts, and IDs

Under the Open Knowledge Format (OKF) specification, organizational knowledge is represented through three fundamental concepts:

• Knowledge Bundle: A self-contained, hierarchical collection of knowledge documents. Bundles are the primary unit of distribution and can be packaged as directory trees, tarballs, zip archives, or versioned in a Git repository.
• Concept: A single unit of knowledge within a bundle, represented as exactly one UTF-8 Markdown file. A concept can describe physical assets like a database table or an API, or abstract ideas such as business metrics, playbooks, and runbooks.
• Concept ID: The unique identifier of a concept, which is represented by its file path, with the .md suffix removed, serving as its unique identifier (known as the Concept ID). For example, a document located at tables/users.md has the Concept ID tables/users.

By mapping the unique identity of a concept directly to its filesystem path, OKF eliminates the need for separate metadata registries or unique ID generation schemes. It allows standard directory layouts to serve as structural indices that are easily understood by both humans and machines.

To help agents navigate these filesystems efficiently, the specification reserves two special filenames that cannot be used for standard concept documents:

1. index.md: Serves as a directory listing or table of contents to enable progressive disclosure. An agent can read an index file to discover what files exist within a directory before deciding to parse individual concept files, preventing context window saturation. The bundle-root index.md file can also declare the specification version using the okf_version property.
2. log.md: Serves as a dated change history, tracking mutations and updates to the bundle over time.

Standardized Metadata and Frontmatter Schema

Each concept document consists of two distinct sections: a structured YAML frontmatter block and a free-form Markdown body. The frontmatter block must be placed at the very top of the file, delimited by three dashes (---).

Under the OKF v0.1 specification, the only strictly required metadata field is type. This field holds a non-empty string identifying what the concept represents. Common types include:

• BigQuery Table
• API Endpoint
• Metric
• Playbook
• Reference

Because these type values are not registered with a central authority, producers can define custom types that match their domain. OKF consumers are required to tolerate unknown types gracefully, treating them as generic concepts.

In addition to type, the specification outlines several optional but highly recommended metadata fields:

• title: A human-readable name for the concept.
• description: A brief, one-sentence summary of the concept’s purpose.
• resource: The canonical URI pointing to the underlying asset or external system.
• tags: A YAML list of keywords used for grouping or domain categorization.
• timestamp: An ISO 8601-formatted timestamp indicating when the metadata was last updated.

The following snippet demonstrates a conformant OKF concept file mapping a dataset:

---
type: Dataset
title: Monthly Active Users
description: A representation of the database table tracking active user profiles.
resource: https://analytics.example.com/datasets/active_users
tags:
  - analytics
  - user-metrics
timestamp: 2026-06-12T10:00:00Z
---
# Monthly Active Users

This table tracks monthly active users. Refer to [User Registrations](/tables/user_registrations.md) to join user records.

Following the frontmatter block, the body contains free-form Markdown. OKF encourages authors and automated producers to favor structural Markdown elements—such as headings, bulleted lists, tables, and fenced code blocks—over loose prose, making it easier for AI models to extract precise details.

Navigating the Link Graph and Handling External Material

Traditional Retrieval-Augmented Generation (RAG) systems typically slice raw documents into arbitrary chunks, convert them into vector embeddings, and store them in vector databases. This extraction process can lose parent-child relationships, technical schemas, and structural hierarchy.

OKF resolves this by using structured, cross-linked text. Concepts connect to one another using standard Markdown links, transforming a flat file system into an interconnected knowledge graph. Authors can use relative links or bundle-absolute links (such as /tables/customers.md). The specification prefers bundle-absolute links because they remain stable even if files are reorganized or moved within the bundle directory.

A link between two concept files asserts a directed relationship. The exact semantic meaning of that relationship is described in the surrounding prose of the Markdown body rather than the link syntax itself. This means AI models can traverse pre-curated relationships directly within their context window, skipping the need for middleware to reconstruct broken context.

External references, such as public web pages or documentation sites, are integrated into the bundle as standard concepts. To catalog an external resource, authors create a file under the references/ directory (e.g., references/api-docs.md), apply the type: Reference metadata, and insert the external URL into the resource field of the frontmatter.

Reference Tools and Conformance Validation

Google Cloud tech leads Sam McVeety and Amir Hormati published the OKF v0.1 specification under the public GoogleCloudPlatform/knowledge-catalog repository on GitHub. Alongside the specification document (SPEC.md), the repository includes functional reference tools and three complete sample bundles covering Google Analytics 4 (GA4) e-commerce, Stack Overflow, and Bitcoin transactions.

To assist developers in producing and consuming bundles, the repository provides three key reference utilities:

1. Enrichment Agent: A two-pass producer agent. The first pass queries BigQuery metadata to write individual concept files for each database table. The second pass acts as an LLM-driven crawler, fetching seed URLs to append schema descriptions, table join paths, and citations directly into the Markdown bodies.
2. HTML Visualizer: A client-side visualizer that renders any local OKF bundle into a single, self-contained interactive file (viz.html). The visualizer maps cross-links as directed edges in a force-directed graph and displays a details panel for selected concepts. It supports a search box, type-based filtering, and alternative layouts, including cose, concentric, breadth-first, circle, and grid.
3. Conformance Checker (okf-validate.mjs): A zero-dependency script that validates bundle compliance. The checker is executed from the command line:

   node okf-validate.mjs path/to/bundle

   The validation tool fails and returns an exit code of 1 if it encounters hard errors, such as a concept missing its frontmatter block or an empty type field. It issues warnings for soft guidance violations, such as broken links or non-ISO dates in log.md, without failing the bundle, reflecting the requirement that consumers must tolerate minor irregularities.

Commercial Integration with Google Cloud Services

The Open Knowledge Format is fully decoupled from proprietary platforms, cloud ecosystems, or runtime engines. Any development team can create, read, and version OKF bundles locally using standard Git workflows and basic text editors.

However, Google Cloud has aligned the open specification with its commercial platform. On the day of the release, the company updated its paid Knowledge Catalog service—formerly Dataplex Universal Catalog—to natively ingest OKF bundles. Once ingested, the platform indexes the bundles and exposes them to Google-supported AI agents, utilizing metadata permissions to enforce access controls and routing queries with sub-second latency.