Google Open Knowledge Format for documentation teams
Learn how Google's Open Knowledge Format structures documentation for AI agents, with metadata, a worked example, review rules, and an adoption checklist.
Team Docuwiz
Documentation Experts
Sign Up for Docuwiz
Experience the magic of collaborative documentation with Docs-As-Code Workflow
Quick answer: What is the Open Knowledge Format?
The Open Knowledge Format (OKF) is an open specification for packaging connected knowledge as Markdown files with YAML metadata. It helps documentation teams preserve structure, provenance, version context, and lifecycle signals when content moves between repositories and AI systems.
For documentation teams, an OKF bundle has five practical features:
Concept files: Each Markdown file represents a useful unit of knowledge, such as a procedure, policy, definition, or troubleshooting guide.
Structured metadata: YAML frontmatter identifies the concept type and can include titles and descriptions; teams can add custom fields for workflow-specific needs.
Explicit relationships: The directory structure groups related concepts, and Markdown links connect them, so teams can link to shared guidance rather than repeating it.
Trust context: Source, generation, and verification records can help consumers judge where knowledge came from and whether it was reviewed.
Lifecycle signals: The optional
statusandstale_afterfields indicate whether content is draft, stable, deprecated, or past its freshness date.
Below, we explain how OKF is currently structured, compare it with llms.txt and traditional knowledge bases, and build a small documentation bundle from reviewed source material.
Why did Google introduce OKF for AI agents?
Google introduced OKF to make the knowledge and context AI agents depend on portable across tools, repositories, and organizations. Its June 2026 announcement describes knowledge scattered across catalogs, wikis, shared drives, code, and people's heads. Without a shared format, each agent builder must assemble that context through a different set of interfaces.
Documentation teams encounter a similar problem. A help article explains the supported procedure, a release note changes one prerequisite, and a support investigation records an exception. An assistant that retrieves only the help article may miss the exception yet still produce a confident answer.
A shared bundle can bring the procedure, version context, and exception together through explicit links. Writers still decide which sources are authoritative and what the instructions mean. The format makes those decisions easier to preserve when knowledge moves into a repository, retrieval service, or another agent's context.
Google's examples emphasize data knowledge. The documentation application is broader: onboarding procedures, installation instructions, troubleshooting guides, operating policies, and product concepts all need traceable context.
How is an OKF knowledge bundle structured?
An OKF knowledge bundle is a self-contained directory tree of Markdown files. Each concept is represented by one Markdown document, and its path within the bundle, without the .md extension, becomes its concept ID. Producers can organize those concepts into directories that make sense for their subject matter.
Google's original OKF announcement introduced this basic structure in v0.1: Markdown files, YAML frontmatter, and a small set of conventions. The current v0.2 specification keeps that structure and adds optional fields for provenance, trust, freshness, and lifecycle, plus a new Attested Computation concept type. It also makes two breaking changes: generated.at replaces the v0.1 timestamp field, and sources replaces the body # Citations list.
Consider a fictional project-management product with a bundle for workspace-administration knowledge. The comments below describe the purpose of each file:
workspace-administration/
├── index.md # Bundle index
├── log.md # Update history
├── guides/
│ ├── index.md # Guide index
│ └── export-project.md # Export procedure
├── policies/
│ └── export-retention.md # Retention rules
└── troubleshooting/
└── missing-export.md # Recovery guidance
Within an OKF bundle, index.md and log.md are optional reserved filenames with defined meanings at the bundle root or within its directories. An index.md file lists the contents of its directory so a person or agent can see what is available before opening individual documents. A log.md file records the history of changes within that part of the bundle.
These reserved filenames must not be used for ordinary concept documents.
Every other Markdown file is a concept document. It contains a YAML frontmatter block followed by a Markdown body. The frontmatter provides structured information about the concept, while the body contains the knowledge itself.
The directory hierarchy groups related concepts, but Markdown links express relationships that go beyond that hierarchy. In this example, export-project.md can link to the retention policy and the missing-export troubleshooting guide. The surrounding text explains whether the relationship is a prerequisite, a policy dependency, a reference, or a recovery path, because OKF does not impose a fixed set of relationship types.
The specification recommends bundle-relative links that begin with /, such as /policies/export-retention.md. Keep concept paths stable where possible. Because the file path forms the concept ID, moving or renaming a file changes its identity and may require updating links elsewhere in the bundle.
An OKF bundle can be distributed as a Git repository, a compressed archive, or a subdirectory within a larger repository. The specification recommends Git when teams want built-in history, attribution, and readable diffs. For a documentation team, a practical starting point is to focus on one task area, with related procedures, policies, and troubleshooting guidance, rather than copying the entire help center.
Which OKF metadata is required, and which is optional?
In the current v0.2 specification, each concept needs parseable YAML frontmatter with a non-empty string type. Other metadata is optional, though recommended fields improve discovery.
Field | Requirement | Purpose |
|---|---|---|
| Required | Concept kind |
| Recommended | Display name and summary |
| Recommended where applicable | Underlying asset and categorization |
| Optional | Provenance |
| Optional | Production and confirmation records |
| Optional | Lifecycle and freshness |
Some optional fields have their own requirements. Each sources entry needs a resource, generated needs a by value, and timestamps need an explicit UTC offset.
Teams can add custom fields such as owner and product_version, but these are not part of the OKF standard. Document them for internal use without treating them as requirements for OKF conformance.
How does OKF compare with llms.txt?
OKF packages the knowledge itself; llms.txt provides a guided route into a website's content. They can support the same documentation program at different points.
The llms.txt proposal defines a plain-text file written in Markdown, with brief context and links to more detailed resources. The only required section is an H1 naming the project or site. It also recommends clean Markdown versions of linked pages.
For a documentation-focused implementation, see this guide to llms.txt for API documentation.
Dimension | OKF |
|
|---|---|---|
Primary purpose | Package knowledge in a portable, structured collection | Guide agents to useful content on a website |
Basic unit | A bundle: a directory tree of Markdown concept documents | A concise plain-text file written in Markdown at a site root or subpath |
Where details live | Inside the bundle's concept documents | On the pages or resources linked from the file, preferably in an LLM-friendly form such as clean Markdown |
How content is organized | Directories, concept metadata, and links between concepts | An H1, optional context, and sections containing selected links |
Provenance and lifecycle | Optional fields can record sources, verification, status, and freshness | The proposal does not define equivalent trust or lifecycle fields |
Best fit | Knowledge that needs to move between tools or organizations with its context intact | Helping agents discover the most useful pages on a documentation site |
For a public help center, choose based on the retrieval problem. If an assistant cannot find an authoritative installation guide, llms.txt can provide a clearer route to it. If the assistant finds the guide but cannot distinguish draft instructions from reviewed guidance or follow relationships between documents, an OKF bundle can carry those additional signals and connections.
Neither approach guarantees that every agent will discover, read, or correctly apply the content. Test the result with the agents and retrieval systems your audience actually uses.
How does OKF compare with a traditional knowledge base?
OKF defines a portable content representation. A knowledge-base product provides the working environment for content, including editing, navigation, search, permissions, and publishing.
The official project README separates the format from a particular framework or serving system. An OKF bundle can become an input to a documentation site or retrieval system, but adopting it does not supply those systems.
Requirement | What the team still needs to decide |
|---|---|
Authoring | Where writers edit, and reviewers give feedback |
Publication | Which changes reach readers and when |
Access | Which people and agents can retrieve each document |
Retrieval | How the consumer selects relevant concepts |
Maintenance | Who responds when evidence or product behavior changes |
Keep a useful help center in place. Pilot OKF as an exchange layer for one knowledge set and check whether it reduces repeated content preparation. If a separate bundle becomes another neglected copy, the team has added maintenance work without solving the original problem.
How can documentation teams build an OKF bundle?
OKF defines how knowledge is packaged, but it does not prescribe how a documentation team must divide its help content or manage its editorial workflow. The following steps illustrate one possible implementation for a fictional project-export use case. The procedure, policy, troubleshooting documents, and metadata choices belong to this example rather than the OKF specification.
1. Start with a bounded user task
This example begins with one question: “How does a workspace administrator export a project?”
Before creating the bundle, gather the information needed to answer that question:
The tested export procedure
The roles allowed to perform it
The product versions to which the instructions apply
The rule defining how long completed exports remain available
The documented reasons an export may not be available to download
Next, decide whether the OKF files will be the primary documentation or a generated copy of another source. If the files are generated, record which source revision was used and how the bundle will be rebuilt.
2. Define the concepts needed for this use case
For the export example, the team could create three concept documents:
An export procedure describing how to create and download an export
A retention policy explaining how long the completed export remains available
A troubleshooting guide covering situations in which the expected export is missing
These documents are useful here because the procedure, policy, and recovery guidance answer different questions and may change at different times.
Link the concepts instead of copying the same rule into several files. A technical documentation template can help the team give each document a structure suited to its purpose.
3. Add the metadata this example needs
The OKF specification requires only a non-empty type field for an ordinary concept document. The example below also uses recommended and optional OKF fields because the use case needs source, review, status, and freshness information. owner and product_version are custom fields defined by the fictional documentation team.
```markdown
---
type: How-to Guide
title: Export a project
description: Export project records from a workspace.
owner: team:workspace-docs
product_version: "4.2"
generated:
by: human:writer-01
at: 2026-10-20T10:00:00Z
verified:
- by: human:reviewer-02
at: 2026-10-21T11:00:00Z
status: stable
stale_after: 2026-12-01T00:00:00Z
sources:
- id: retention
resource: /policies/export-retention.md
---
## Before you begin
Use a workspace administrator account in version 4.2.
## Export the project
1. Open the project settings.
2. Select Export and confirm the project.
3. Download the completed export.
Download availability follows the retention policy.[^retention]
[^retention]: Export retention policy
```
The sources entry and matching footnote connect the availability statement to the retention-policy concept. The fictional verified event indicates that a reviewer checked the guide. In a real bundle, add that record only after the review has occurred.
4. Connect the task to its supporting concepts
An optional root index.md can give people and agents a concise route through the three documents:
```markdown
---
okf_version: "0.2"
---
# Workspace administration
- [Export a project](/guides/export-project.md) - Create and download a project export.
- [Export retention policy](/policies/export-retention.md) - Check how long a completed export remains available.
- [Resolve a missing export](/troubleshooting/missing-export.md) - Diagnose an export that is not available to download.
```
The root index also declares the target OKF version with the optional okf_version field.
5. Test the bundle against the task
Ask a reviewer and the intended agent consumer to answer questions drawn from the export use case:
Who can export a project?
Which product version do the instructions cover?
How long does a completed export remain available?
Why might an expected export be missing?
Which source supports each answer?
Inspect the retrieved concepts and sources, not only the final response. If the consumer uses an obsolete guide, overlooks the retention rule, or misses the troubleshooting path, correct the content or relationships before expanding the bundle.
How do provenance, trust, freshness, and lifecycle work?
Google's v0.2 announcement introduced optional frontmatter fields that help consumers understand where a concept came from, how it was produced, whether it was checked, and whether it is still current.
Each field answers a different question:
Field | What it records | What it does not establish |
|---|---|---|
| The materials from which the concept was derived | A universal credibility score |
| Who or what produced the current content, and when it last changed meaningfully | Whether the content was independently reviewed |
| One or more confirmations against the sources or underlying resources | A guarantee that the content is correct |
| Whether the concept is | What a publishing or retrieval system must do with it |
| The point in time at which the concept should be treated as stale | Whether an earlier product or policy change has already invalidated it |
Each verified event identifies an actor and a timestamp. Consumers can use those events to classify a concept as unverified, machine-confirmed, or human-reviewed. These trust tiers are advisory signals, not access controls or guarantees of accuracy.
These fields make provenance, review state, and lifecycle information portable. OKF records the signals but does not perform reviews, detect product changes, or update content.
What are OKF's limitations and adoption considerations?
OKF standardizes how knowledge is represented and exchanged. It does not select authoritative sources, resolve conflicting instructions, enforce access controls, retrieve the correct concept, or keep content up to date. The documentation team and its supporting systems still own those responsibilities.
Before adopting OKF, check four practical constraints:
Consumer support: Confirm that the tools or agents using the bundle can read its frontmatter, follow concept links, and recognize lifecycle signals.
Source ownership: Decide whether contributors will edit the bundle directly or generate it from another documentation source. Avoid maintaining two independent copies.
Content conversion: Provide readable alternatives for tabs, diagrams, interactive examples, and other elements that do not translate cleanly into Markdown.
Security: Review content, metadata, source references, and repository history before sharing the bundle. OKF does not provide permissions or redaction.
Treat provenance and verification metadata as trust signals, and lifecycle metadata as freshness signals. Neither proves that a concept is correct or still current. The v0.2 Attested Computation concept type applies when a consumer must confirm that a value came from a sanctioned calculation. Ordinary documentation bundles do not need it.
Pilot one bounded knowledge set with a named consumer before expanding. Declare the target version with okf_version: "0.2" in the root index.md frontmatter, and pin the corresponding specification revision in your validator or export process. Continue only if the bundle improves retrieval or preserves context without creating another neglected copy.
How does Docuwiz support an OKF documentation workflow?
An OKF bundle can make approved knowledge portable, but it cannot replace the documentation behind that knowledge. It does not give writers and developers a shared place to create content, manage reviews, compare revisions, publish a branded documentation site, or help readers find and use guides and API references. Think of OKF as an additional delivery layer, not the complete documentation experience.
Docuwiz provides the working environment that an OKF initiative still needs. Its published capabilities include OpenAPI and Markdown import, a visual (WYSIWYG) editor, pre-built templates, change tracking, version history, and publishing controls. This gives developers, technical writers, reviewers, and product teams a single place to turn source material into accurate, ready-to-use documentation.
An OKF workflow can then build on that foundation:
Create structured documentation: Maintain the full procedure, API reference, policy, or troubleshooting guidance in Docuwiz, where contributors can write for the people who need to use it.
Review before adding trust signals: Complete the technical and editorial review first. Add OKF verification metadata only when the corresponding check has actually occurred.
Package selected knowledge: Convert the approved content needed for a specific agent task into Markdown concept files, preserving headings, examples, links, sources, and version context.
Release both layers together: When the documentation changes, update the published pages and regenerate or review the related OKF bundle as part of the same release process.
Docuwiz does not need to be replaced for a team to adopt OKF. It remains the place where documentation is created, reviewed, governed, and delivered to readers. The OKF bundle gives selected knowledge another way to travel into repositories, retrieval systems, and agent workflows.
The practical value is straightforward: OKF makes documentation portable, while Docuwiz helps teams produce and maintain documentation they can trust. Teams still need to implement or select the OKF conversion and validation step, but they can do so without building a separate authoring and publishing workflow around the format.
What belongs in an OKF implementation checklist?
Use this checklist before expanding an OKF pilot:
Define one use case and the people, tools, or agents that will consume the bundle.
Confirm the authoritative sources and resolve conflicting instructions.
Choose the primary editing location and bundle-generation process.
Define the concept boundaries and stable file paths.
Validate the frontmatter against the chosen OKF specification revision.
Separate custom metadata from standard OKF fields.
Check source references, verification records, and sensitive content.
Test realistic questions with the intended consumers.
Assign responsibility for content changes and freshness reviews.
Expand only when the team can reliably maintain this cycle.
FAQs
Is Google's Open Knowledge Format a documentation platform?
No. OKF defines a portable way to represent knowledge; it does not provide an editing, review, access-control, search, hosting, or publishing environment. Teams still need documentation and retrieval tools around the bundle.
Does an OKF bundle require Google Cloud?
No. An OKF bundle consists of Markdown files with YAML frontmatter and can be distributed via Git, as an archive, or as a directory within a larger repository. The tools that produce or consume it may have their own infrastructure requirements, but the format itself does not require Google Cloud.
Should every help-center article become an OKF concept?
No. Start with the concepts needed for a defined task or retrieval problem. A focused bundle lets the team test its value and maintenance cost before converting a larger documentation set.
Does a human-reviewed trust tier prove a concept is accurate?
No. The human-reviewed trust tier means that at least one verified entry identifies a human actor. It records a verification event, not the rigor of the review or a permanent guarantee of accuracy.
Can OKF keep documentation fresh automatically?
No. The status and stale_after fields expose lifecycle and freshness signals, but they do not monitor product changes or update content. Teams still need owners, review triggers, and a process for acting on those signals.
Sources
Written by
Team Docuwiz
Documentation Experts
The Docuwiz team helps developer-focused companies build documentation their users actually love — from API references to onboarding guides and everything in between.
