Google Open Knowledge Format Commentary: Why AI agent data sharing requires designing context file contracts before vector DB

Publication date: 2026-06-14 | Category: How to use AI

Google Open Knowledge Format Commentary: Why AI agent data sharing should design context file contracts before vector DB

1) One-line problem definition

Key takeaway: The reason AI agents are not good at using data is not only because their models are weak, but also because organizational knowledge is scattered across different tools and people's heads.

Google Cloud released the Open Knowledge Format, or OKF for short, on June 13, 2026. OKF is a draft standard that expresses knowledge such as datasets, tables, indicators, APIs, and runbooks in Markdown files and YAML frontmatter. Simply put, it is Common document folder rules for data knowledge that can be read by AI agents and humans together.

The target readers of this article are developers and planners who are creating in-house data Q&A, RAG, BI automation, SQL generation agent, and business automation agent. The scope is not a summary of Google's announcement, but under what circumstances it is worth introducing OKF, what roles it should share with Vector DB, data catalog, and in-house wiki, and what files should be created to start small.

On the contrary, I will not say that OKF is the answer to all knowledge management problems. v0.1 is still a draft, and permissions, verification, automatic synchronization, and operational responsibilities must be designed separately by each team.

2) Conclusion first

Key summary: OKF is not a new database, but a format that manages AI-readable context like git.

Teams worth watching right now: A team whose AI answers are often shaky due to data catalogs, in-house wikis, dbt documents, Looker/BI definitions, runbooks, and code comments being used separately
Team that is still too much: A team where the number of tables is small, the person in charge can answer right away, and the AI agent is not used to make actual business judgments
My judgment: The point of OKF is not “It’s easy because it’s Markdown.” What it really means is that takes the context out of the model/cloud/catalog product and makes it a portable contract

I would not immediately push OKF as a company-wide standard. First, we will select the 20 most frequently asked questions and create a small OKF bundle containing only the tables, indicators, joins, terms, and runbooks needed for those questions. We will then measure whether the answer accuracy, attribution rate, and false join reduction rate improve when a SQL generation or data Q&A agent reads this bundle.

3) Core structure decomposition

Key takeaways: OKF moves in five pieces: file folder, YAML frontmatter, Markdown body, internal links, and index/log file.

3-1. Knowledge Bundle: Deployment Unit

OKF, a bundle is a directory containing knowledge documents. It could be a git repository, a zip file, or a subfolder within a larger repository. The important point is that it is not “knowledge that can be read only by accessing the service,” but “knowledge that can be copied into a file and version controlled.”

3-2. Concept Document: One file per knowledge

Leave one table, one indicator, one API, and one business rule each as a Markdown file. The file path becomes your concept ID. For example, tables/orders.md refers to the order table concept, metrics/weekly_active_users.md refers to the Weekly Active Users metric, and

3-3. YAML frontmatter: minimal structured field

The YAML frontmatter is placed at the top of the file. In OKF v0.1, there is one required field: type. In addition, title, description, resource, tags, timestamp are recommended fields. This design is intentionally loose. This is to allow each team to create the type they need without a central registry.

3-4. Markdown body: human-readable description

The body contains tables, lists, code blocks, example SQL, and operating procedures. From AI's perspective, this is the actual basis for the answer. If frontmatter helps with searching and filtering, the text explains things like “Why do we need to join this table like this?”

3-5. Markdown links: A device that turns folders into graphs

Documents are connected using regular Markdown links. If the orders table is joined with the customers table, there is a link in the text. When these links are stacked, it becomes a graph of relationships between concepts rather than a simple folder structure. Agents can move to the required document by looking at the index without having to read the entire document at once.

4) Explanation of design intent

Key summary: OKF prioritizes “knowledge files that can be read by anyone” over “a smarter search service”.

Many teams first think of vector DB, catalog, and RAG pipeline when AI cannot handle data. But the real cause of failure lies before the search infrastructure. The same indicator name is different for each department, join rules are known only to the person in charge, old tables have been deprecated but remain in the document, and SQL examples are buried somewhere in Slack.

The Google Cloud blog sees this issue as “scattered context.” OKF is an attempt to get this context out in a file format, rather than locking it back into one service. Markdown is easy for humans to read, YAML is easy for machines to filter, and git is easy to leave change history and reviews.

There is an important trade-off here. OKF does not have a strong schema fixation. So, it is easy to implement, but the name or body section of type may be different for each team. In other words, OKF is not a “complete catalog product” but “the minimum format that catalogs, wikis, and agents can exchange.” Understanding this difference can help you avoid excessive expectations.

5) Evidence and comparison

Key takeaway: OKF's competition is not just VectorDB, but the entire chunk repository for in-house wikis, data catalogs, dbt documents, and RAGs.

Approach	What you're good at	What is lacking	Relationship with OKF
In-house Wiki/Notion	Humans can write and read descriptions	The schema, resource URI, type, and link rules are loose, making it difficult for agents to read them consistently	Only core knowledge can be exported or synchronized with OKF
Data Catalog	Strong in permission, owner, schema, and lineage management	Bound to the API and model for each product, and may lack natural language context for the agent to read directly	You can create file bundles by becoming an OKF producer
Vector DB/RAG storage	Strong in search and similarity matching	Weak review, diff, ownership, and file-level distribution of original knowledge	A structure that uses OKF as the source and puts the index result into a vector DB is suitable
dbt/OpenAPI/Avro/Protobuf	Strong domain-specific structure and verification	The purpose is different to include business context, exceptions, operation history, and join judgment	Becomes the source material referenced in the OKF text and resource field

The official SPEC clearly draws the line that OKF does not replace domain-specific schema. This is important. OKF is not a format that eliminates OpenAPI or dbt schema, but a format that connects such data in a knowledge document that can be read by AI and humans.

When viewed in conjunction with Google Cloud's Knowledge Catalog announcement, the direction becomes clearer. Google is extending the catalog as a context engine for AI agents, and OKF is responsible for lowering that context into a form that can be exchanged with the outside world. In other words, it is a division of labor called Knowledge Catalog as a product strategy and OKF as an exchange format.

6) Actual operation flow / step-by-step execution method

Key takeaway: Instead of creating an enterprise knowledge graph from scratch, start with “Data questions that AI often gets wrong” and fix them in an OKF bundle.

Step 1. Select 20 failure questions

For example, “How do you calculate weekly active users?”, “Should refund orders be deducted from sales?”, “What key do you use to join the customer table and order table?” Same question. If there is already a log with an error in AI, that log is used first.

Step 2. Create a minimal folder structure

okf-sales/
├── index.md
├── log.md
├── datasets/
│   └── sales.md
├── tables/
│   ├── orders.md
│   └── customers.md
├── metrics/
│   └── weekly_active_users.md
└── playbooks/
    └── revenue-quality-check.md

Step 3. Create a table document

---
type: BigQuery Table
title: Orders
description: A table that stores payment completion or refund order events.
resource: bigquery://acme/sales/orders
tags: [sales, revenue, orders]
timestamp: 2026-06-14T00:00:00Z
---

# Schema
| Column | Type | Description |
|---|---|---|
| `order_id` | STRING | Order Unique ID |
| `customer_id` | STRING | Keys to join [customers](/tables/customers.md) |
| `status` | STRING | One of paid, refunded, canceled |

# Examples
```sql
select count(*) from sales.orders where status = 'paid';
```

# Citations
[1] BigQuery table schema: see the internal catalog resource bound above.

Step 4. Write calculation rules in the indicator document

The most dangerous thing in AI SQL creation is “plausible index name”. Therefore, the indicator document must include definitions, exclusion conditions, time zone, deduplication criteria, and SQL for validation. OKF does not enforce this section, but in practice it is better to enforce it as a team rule.

Step 5. Determine the agent input path

When starting small, don't put the entire OKF bundle into your model every time. First, search and insert only index.md and 3 to 7 candidate documents related to the question. The fixed file bundle is the source, and the search index is the consumption cache.

7) Mistakes/Pitfalls

Key summary: OKF looks easy because it is a file, but without operating standards, it becomes just another old document folder.

Mistake 1: Trying to convert all documents to OKF at once
Prevention: AI only creates 20 to 50 documents starting from those linked to the question that is actually incorrect.
Recovery: Change the conversion range. Reduce and re-prioritize based on question log.
Mistake 2: Filling in only the frontmatter and leaving the body description blank
Prevention: Include at least one example SQL, join rule, and exclusion condition in the table document.
Recovery: AI Return incorrect answers to the main text section and document “why they are incorrect.”
Mistake 3: Leaving the permission model to the file format
Prevention: When creating the OKF bundle, apply the same public scope as the original system permission separately.
Recovery: Sensitive tables, customer information, and internal URLs are corrupted. Immediately separate mixed bundles and check access log.
Mistake 4: Distributing auto-generated documents without review
Prevention: Documents created by producer agents are received as pull requests and passed data owner review
Recovery: Prompt for creating incorrect documents, seed Reproduce by keeping the URL and original metadata snapshot together.
Mistake 5: Confusing VectorDB and OKF roles
Prevention: Separate OKF into original contract and VectorDB into search cache.
Recovery: When search results are wrong, do not fix the cache directly. OKF Original document is modified and re-indexed.

8) Strengths and limitations

Key takeaways: OKF's strengths are portability and reviewability, its limitations are that the standards are still thin.

Strengths

Low read barrier. Markdown and YAML so developers, data analysts, and AI agents can see the same files.
Versioning is natural You can also apply git diff, PR review, blame, and release tags to knowledge documents.
Weak platform dependency. Can be read and moved without specific cloud, model, framework, or catalog products.
Suitable for AI agent navigation. By using index files and internal links, you can open only the documents you need step by step.

Limit

v0.1 draft. Type system, section conventions, verification tool ecosystem still need to mature.
Permissions and security are separate issues. File format does not automatically resolve access controls.
Synchronization responsibility remains. If the original schema has changed but the OKF document changes late, the AI may trust the old context.
Large-scale searches require separate infrastructure. File format alone does not solve relevance ranking, ACL-aware search, and evaluation.

Counterexample: If the data catalog is already operating well, the AI agent also reads the catalog API reliably, and indicator definitions and permissions are well managed centrally, there may be little need to create a separate OKF. On the other hand, if you are a team that has many tools but the AI always gets the same joins and indicators wrong, OKF is good for checking the effectiveness even with a small experiment.

9) Points to study more deeply

Key summary: To properly view OKF, you need to look at context operation, metadata as code, and search evaluation rather than Markdown syntax.

OKF SPEC: You should read why there is only one required field: type and how consumers should deal with broken links and unknown types.
Google knowledge-catalog repository: You can create OKF bundles from BigQuery metadata, enrich documents with web pass, and check the flow with HTML visualizer.
LLM wiki pattern: Helps you understand why there is a resurgence in the idea of agents directly reading and updating work documents.
Knowledge Catalog: If OKF is a file format, the catalog is the operational layer responsible for authorization, search, evaluation, and connection.
Context evaluation: Don't just look at answer accuracy; measure whether you found the documents you needed, avoided outdated documents, and whether the evidence actually supports the answer statement.

10) Execution Checklist + Author’s Perspective

Key summary: I think it is more practical to view OKF as a “minimum contract that treats team knowledge like code” rather than a “document format for AI”.

Are there 20 data questions that AI frequently gets wrong?
Are the tables, indicators, joins, terms, and runbooks required for each question traceable to files?
Do all concept documents have type and human-readable title, description?
Does the indicator document include calculation SQL, exclusion criteria, time zone, and owner?
Have the access rights of the OKF bundle containing sensitive data and internal URLs matched with the original system?
Are automatically generated documents reviewed by the data owner with PR?
OKF Are the re-indexing flows of the original and vector DB/search index separated?
Are you looking at “whether the answer is correct” and “whether the supporting document was hit” separately when evaluating AI answers?

Definition of Done: If an agent using the OKF bundle finds more than 80% of the required concept documents in 20 representative questions and reproducibly generates answers including indicator definitions, joins, and sources, the first introduction is considered successful.

My recommendation: OKF does not need to be viewed as a big platform migration project right now. The best start is to create an OKF of “10 data terms that AI keeps getting wrong at our company.” If this small bundle is effective, you can expand it to include producer agent, visualizer, search index, and catalog integration. The bottleneck in data sharing is often not the repository, but the absence of a contract in context. OKF proposes to make the contract into a small, long-lasting file.