Knowledge as Infrastructure: Google’s Open Knowledge Format (OKF), a Practical Guide

I strongly believe that a unified knowledge infrastructure is the foundational layer of the agentic enterprise, spanning product initiation, engineering, operations, and long-term maintenance.

The old stack of Jira, Confluence, shared drives, and scattered documentation is no longer enough. Those tools still matter as systems of record, but they are not systems of execution, reasoning, or operational intelligence for AI-native teams.

In an environment where assistants, copilots, and agents increasingly participate in delivery, fragmented knowledge becomes a bottleneck and a reliability risk.

Many teams have strong institutional knowledge, but that knowledge is scattered across wikis, shared drives, Slack threads, architecture decks, meeting notes, issue trackers, README files, product documents, and the heads of a few experienced people. The result is familiar: duplication, inconsistency, slow onboarding, weak discoverability, and AI systems that sound confident while operating on partial context.

Press enter or click to view image in full size

This is why Google’s Open Knowledge Format, or OKF, is so compelling: it points toward a more durable, structured, machine-readable foundation for how organisations capture, govern, and operationalize knowledge across the full software lifecycle.

At a high level, OKF is an open, vendor-neutral standard for structuring and storing organisational knowledge as a directory of Markdown files with YAML frontmatter. That description sounds simple, and it is. But the simplicity is part of the point.

OKF is not trying to be a heavyweight content platform. It is trying to give teams a durable, portable, Git-friendly way to represent knowledge so both humans and machines can work with it more effectively.

That makes it useful not only for documentation, but also for retrieval pipelines, internal AI assistants, knowledge graphs, governance workflows, software delivery context, and cross-team operational memory.

This article explains what OKF is, why it matters, where it is useful, what kinds of use cases it enables, and how to start using it in a practical way.

Press enter or click to view image in full size

The Core Idea Behind OKF

Most organisations already have knowledge in text form. The real problem is not that knowledge does not exist. The problem is that it is usually stored in formats and locations that are hard to govern, hard to diff, hard to compose, and hard for AI systems to consume reliably.

OKF addresses that by using a few very deliberate choices:

• Markdown for the body content
• YAML frontmatter for structured metadata
• directories and files as the organising model
• an open, vendor-neutral representation rather than a proprietary application database

That means a knowledge asset in OKF is just a file that can be read by a person, versioned in Git, reviewed in pull requests, indexed by search systems, parsed by scripts, embedded into vector pipelines, and transformed into other views when needed.

In other words, OKF treats knowledge more like a maintainable engineering asset and less like an isolated page trapped inside a tool.

Press enter or click to view image in full size

What an OKF Document Looks Like

An OKF document typically has two major parts.

• The first part is YAML frontmatter, which carries structured fields such as title, owner, tags, status, domain, source links, timestamps, sensitivity, or relationships to other knowledge objects.
• The second part is the Markdown body, which carries the narrative, explanation, decision history, procedure, architecture note, FAQ, policy explanation, or any other human-readable content.

Here is a simple example.

---
id: arch-llm-gateway
title: LLM Gateway Architecture
type: architecture-note
status: approved
owners:
  - platform-team
domain: ai-platform
tags:
  - llm
  - gateway
  - governance
last_reviewed: 2026-09-13
sensitivity: internal
related:
  - policy-model-routing
  - service-prompt-redaction
summary: >
  Describes the standard gateway pattern for routing, tracing,
  redaction, retries, and policy enforcement for LLM access.
---

# LLM Gateway Architecture## PurposeThis document explains why all application-facing LLM traffic should pass
through the shared gateway.## Key Responsibilities* provider routing
* request and response tracing
* prompt and response redaction
* retry and timeout handling
* policy enforcement
* usage metering## Design Notes...

There is nothing exotic here. That is a strength.

Humans can read it directly. Machines can parse it predictably. Git can version it cleanly. Tooling can index it without reverse engineering a proprietary export format.

Press enter or click to view image in full size

Why This Matters More in the Age of AI

Before AI, messy knowledge mainly slowed humans down. With AI, messy knowledge becomes a system quality problem.

If an internal assistant answers questions using stale wiki pages, undocumented assumptions, and fragmented architecture notes, the issue is not just inconvenience. It is that the system starts producing authoritative-sounding output without a governed substrate underneath it.

That creates several risks:

• inconsistent answers across teams
• hallucinated policies or procedures
• stale architecture guidance being treated as current truth
• weak traceability for high-impact answers
• poor grounding for automated workflows and agents
• duplicated context engineering work in every project

OKF helps because it creates a knowledge layer that is both human-editable and machine-usable.

That combination is especially important for AI systems that need:

• high-quality retrieval sources
• reliable metadata for filtering and ranking
• ownership and review signals
• content portability across tools
• version history and auditability
• manageable paths for governance and automation

In practical terms, OKF is not just about storing documents neatly. It is about improving the quality of the context supplied to AI-driven work.

What OKF Is Useful For

The most useful way to think about OKF is not as a single-purpose documentation format, but as a common substrate for organisational knowledge.

That substrate can support several classes of work.

Press enter or click to view image in full size

1. Knowledge Management

At the most basic level, OKF gives teams a structured, maintainable way to store internal knowledge.

Examples include:

• architecture notes
• ADRs
• runbooks
• operating procedures
• service catalogs
• domain glossaries
• onboarding guides
• support playbooks
• product capability maps
• compliance or control explanations

The value here is not only standardisation. It is the ability to make these artefacts easier to find, review, update, and reuse across systems.

Press enter or click to view image in full size

2. AI Retrieval and RAG Pipelines

This is one of the strongest use cases.

Most retrieval pipelines work better when source content has useful metadata. If every knowledge file contains fields such as type, owner, sensitivity, tags, product area, and review status, retrieval systems can do more than semantic similarity matching.

They can also:

• filter out sensitive or deprecated content
• prioritise reviewed and approved sources
• narrow retrieval to a domain or team
• boost canonical documents over drafts
• generate citations from stable IDs and file paths
• route queries to the right collection before embedding search even begins

This gives you a more controlled RAG architecture than simply scraping an entire wiki and hoping for the best.

3. Agentic Workflows and Internal Assistants

If you want to build internal AI assistants that can reason over architecture, process, product context, operational procedures, or policy, OKF becomes a useful operating format.

For example, an engineering assistant could use OKF-based knowledge stores to answer:

• Which gateway pattern should a new service use?
• What are the approved deployment controls for high-risk changes?
• Which team owns the customer profile domain?
• What is the runbook for rotating a leaked API key?
• Which policies apply to regulated data exports?

Because OKF content is file-based and structured, those assistants can also cite exact documents, show ownership, and reason over freshness rather than treating all text as equally trustworthy.

Press enter or click to view image in full size

4. Governance and Reviewability

A lot of organisational knowledge has compliance implications.

You may need to know:

• who owns a document
• when it was last reviewed
• whether it is draft, approved, deprecated, or superseded
• whether it contains confidential or regulated information
• which systems or policies it relates to

OKF makes those properties explicit in frontmatter rather than implicit in tool conventions or naming habits.

That makes it easier to create workflows such as:

• validation checks for missing ownership or review dates
• periodic stale-content detection
• policy coverage reporting
• approval requirements for certain document types
• access-aware indexing pipelines

5. GitOps-Style Knowledge Operations

Teams increasingly want documentation and knowledge to move with delivery.

If architecture notes, runbooks, service definitions, policy interpretations, and product context live in or near the repositories where change happens, then the organisation can treat knowledge updates as part of normal engineering flow.

That enables patterns such as:

• updating service docs in the same PR as code changes
• requiring architecture-note updates when interfaces change
• checking for missing runbook coverage before a service goes live
• linking feature changes to canonical product or domain knowledge

This is especially valuable in AI-enabled delivery systems where you want structured context to stay synchronised with actual implementation.

6. Interoperability Across Tools and Platforms

One of the biggest long-term advantages of an open format is that your knowledge does not become trapped inside one vendor’s application model.

With OKF, the same content can be:

• rendered into a docs site
• indexed into search
• embedded into a vector database
• transformed into JSON for an API
• imported into graph models
• validated in CI
• edited in any text editor

That flexibility matters if you expect your tooling landscape to evolve.

What Problems OKF Helps Solve

OKF is not magic, and it will not fix bad content on its own. But it is well-suited to address several recurring organisational problems.

Fragmented Knowledge

When documentation is spread across disconnected tools, teams waste time reconstructing context. OKF gives you a consistent representation that can be aggregated and indexed more easily.

Weak Ownership

A page without an owner tends to become a rumour. OKF makes ownership an explicit metadata field, which means workflows can enforce it.

Stale Documentation

Knowledge without review signals ages invisibly. OKF allows you to track review dates and statuses so stale-content checks become automatable.

Poor AI Grounding

AI systems perform poorly when source material lacks structure, scope, and trust markers. OKF improves source quality by attaching metadata that retrieval and ranking systems can actually use.

Lack of Portability

If your most important institutional knowledge only exists inside a proprietary SaaS application, your options are limited. OKF reduces that lock-in risk because the canonical form is text files in an open structure.

Concrete Use Cases for OKF

The best way to understand OKF is through practical examples.

1. Enterprise Architecture Knowledge Base

An enterprise architecture team stores system overviews, domain maps, integration standards, approved patterns, and ADRs as OKF documents.

Useful metadata might include:

• architecture domain
• owning team
• status
• related systems
• security classification
• supersedes or superseded-by relationships

This enables:

• better search by domain or pattern
• AI assistants that answer architecture questions with citations
• review workflows for outdated standards
• easier reuse of approved integration patterns

2. Internal Developer Portal Backing Store

A platform team uses OKF to represent service metadata, ownership, dependencies, runtime characteristics, support links, and operational procedures.

Each service has a directory containing:

• a service overview
• runbooks
• API references or pointers
• deployment notes
• on-call information
• incident learning summaries

This provides a durable, Git-managed backend for a developer portal and for internal support copilots.

3. Product and Domain Knowledge for AI Assistants

A product organisation needs a trustworthy internal assistant that can answer questions about terminology, feature behavior, roadmap concepts, customer segments, and business rules.

Instead of feeding the assistant raw slide decks and random notes, the team curates canonical OKF documents for:

• glossary terms
• business rules
• product capability definitions
• segment-specific constraints
• known exceptions and edge cases

Now retrieval is grounded in explicit, reviewable sources rather than loose conversational residue.

4. Security and Compliance Knowledge

Security teams can use OKF to maintain:

• control explanations
• secure coding patterns
• threat-model templates
• data handling procedures
• incident response playbooks
• exception records and guidance

Metadata such as sensitivity, applicable systems, regulatory scope, and review dates make this content easier to govern and safer to expose selectively.

5. SDLC Context for Agentic Delivery

This is especially relevant for organisations exploring AI-enabled software delivery.

Imagine a delivery system where agents help with planning, coding, review, testing, release, and operations. Those agents need structured organisational context.

OKF can store:

• engineering standards
• architecture constraints
• deployment policies
• test strategy guidance
• service ownership information
• rollout playbooks
• postmortem learnings

That gives agents a better substrate for suggesting changes, validating decisions, proposing test depth, or flagging policy mismatches.

6. Onboarding and Organisational Memory

New joiners often struggle because the information they need is present but not organised as durable knowledge.

OKF is a strong fit for onboarding packs that connect:

• team responsibilities
• system maps
• common procedures
• vocabulary
• escalation paths
• recent major decisions

Because these are plain files, teams can keep them close to actual work instead of letting them drift into forgotten portals.

Press enter or click to view image in full size

How to Organise an OKF Repository

There is no single mandatory directory shape, but good OKF adoption usually depends on being intentional about structure.

One practical pattern looks like this:

knowledge/
  architecture/
    llm-gateway.md
    event-routing-standard.md
  services/
    customer-profile/
      overview.md
      runbook.md
      dependencies.md
  product/
    glossary/
      tenant.md
      account-linking.md
    capabilities/
      enterprise-export.md
  policies/
    data-retention.md
    pii-handling.md
  operations/
    incident-response/
      api-key-leak.md
  people-and-teams/
    platform-team.md
    identity-team.md

The exact shape matters less than a few principles:

• organise by meaningful domain boundaries
• keep naming predictable
• distinguish canonical knowledge from drafts or notes
• define standard frontmatter fields
• make ownership and status explicit

If the structure is too loose, discoverability suffers. If it is too rigid, adoption suffers. The best pattern is usually one that reflects how your organisation actually reasons about its domains.

Press enter or click to view image in full size

Suggested Frontmatter Fields

The OKF concept is flexible, but most teams benefit from a core metadata schema.

Common fields might include:

• id: stable identifier
• title: human-readable title
• type: document kind such as runbook, policy, adr, service-overview, glossary-term
• status: draft, approved, deprecated, superseded
• owners: team or named owners
• tags: discovery labels
• domain: business or technical domain
• summary: short abstract for retrieval and preview
• last_reviewed: review timestamp
• sensitivity: public, internal, confidential, restricted
• related: links to related document IDs
• source_of_truth: whether the document is canonical or derivative
• audience: engineers, operators, support, leadership, all

You do not need to start with all of these.

A minimal schema with title, type, owners, status, and last_reviewed is already much better than unstructured documents with no lifecycle signals.

Press enter or click to view image in full size

How to Start Using OKF

The safest way to adopt OKF is to begin with a narrow, high-value slice of knowledge rather than trying to convert everything at once.

Here is a practical rollout path.

1. Choose a Focus Area

Pick a knowledge domain where pain is visible and the audience is clear.

Good starting points include:

• architecture standards
• service runbooks
• developer platform guidance
• product glossary and business rules
• security procedures

These categories usually have high reuse value and benefit strongly from structure.

2. Define a Small Metadata Standard

Do not start with an enormous schema.

Choose a small set of fields that clearly improve governance and retrieval. For example:

• title
• type
• owners
• status
• last_reviewed
• tags

You can evolve the schema later.

3. Create Templates

Adoption is much easier when teams do not have to invent document shape from scratch.

Provide a few templates for common document types such as:

• runbook
• architecture note
• service overview
• glossary term
• policy explanation

Templates improve consistency without requiring heavy process.

4. Put the Repository in Git

This is one of the strongest operational choices you can make.

Git gives you:

• version history
• pull request review
• change attribution
• branching workflows
• CI validation hooks

That makes OKF content easier to manage with engineering-grade discipline.

5. Add Validation

Once files are structured, you can validate them.

For example, CI can check:

• required frontmatter fields exist
• statuses are from an approved list
• last_reviewed is a valid date
• IDs are unique
• links and relationships resolve correctly

This is where OKF starts becoming a governed system rather than just a file convention.

6. Index It for Search or RAG

Once content is in OKF, you can ingest it into:

• full-text search
• vector retrieval pipelines
• internal assistants
• knowledge graphs
• developer portals

The ingestion step becomes simpler because the structure is explicit.

7. Build Maintenance Habits

A knowledge format is only useful if the content stays alive.

Put in lightweight operating habits such as:

• owners review critical docs quarterly
• architecture PRs update relevant OKF documents
• stale documents trigger reminders
• deprecated items point to their replacements

The format helps, but stewardship is what makes the system valuable.

A Sample OKF Workflow in Practice

Imagine a platform team introducing a new standard for outbound LLM usage.

A practical OKF-based workflow could look like this:

1. The architect creates architecture/llm-gateway.md with metadata describing ownership, status, scope, and review date.
2. The security team adds policies/prompt-redaction.md and relates it to the gateway architecture note.
3. The platform team creates services/llm-gateway/overview.md and services/llm-gateway/runbook.md.
4. CI validates that all required metadata is present and all related document IDs resolve.
5. The internal developer portal indexes these files.
6. An engineering assistant uses them to answer implementation questions and cite the canonical documents.
7. When the standard changes, the PR updates the architecture note, policy note, and runbook together.

This is a simple example, but it shows the power of a file-based, structured knowledge model. The documents are not isolated pages. They become part of an operational system.

Press enter or click to view image in full size

How OKF Compares to Traditional Wikis

This is not really an either-or situation. Many organisations will continue to use wikis for broad collaboration.

The more useful distinction is this:

• wikis are often good for low-friction contribution and broad publishing
• OKF is strong for canonical, structured, versioned, machine-usable knowledge

In many environments, the best model is hybrid.

For example:

• a wiki page may present a polished human-facing view
• the canonical source may live as OKF files in Git
• search, portals, and assistants may index the OKF source directly

That gives you flexibility without losing structure.

Press enter or click to view image in full size

Limitations and Things to Watch

OKF is useful, but it is not a silver bullet.

There are several realities to keep in mind.

It Does Not Create Good Knowledge Automatically

If the source content is vague, wrong, or stale, OKF will not rescue it.

It improves representation and governance, not truth by itself.

Metadata Can Become Bureaucratic

If you define too many required fields too early, people will work around the system.

Start with the smallest schema that adds real value.

File Sprawl Is Still Possible

A directory full of Markdown files can become messy if naming, ownership, and structure are neglected.

The format reduces chaos, but it does not eliminate the need for information architecture.

Some Content Should Not Be Broadly Indexed

Because OKF is easy to ingest into search and AI systems, you need to take sensitivity classification seriously.

Not every document should be available to every assistant or every user.

Operational Discipline Still Matters

Review cycles, ownership, deprecation practices, and update workflows remain important.

OKF makes these easier to encode, but teams still need to do the work.

Press enter or click to view image in full size

Why OKF Is Likely to Matter Going Forward

The more organisations rely on AI for internal productivity, engineering acceleration, and knowledge access, the more they will need durable, structured knowledge substrates.

That substrate needs to be:

• easy for humans to edit
• easy for machines to parse
• portable across tools
• governable over time
• reviewable like other important operational assets

OKF aligns well with all of those needs.

It is especially well suited to organisations that want to move away from knowledge trapped in proprietary silos and toward knowledge that can participate directly in engineering, retrieval, governance, and automation workflows.

In that sense, OKF is bigger than a documentation pattern. It is a practical way to treat organisational knowledge as infrastructure.

Final Take

Google’s Open Knowledge Format is useful because it takes something most organisations already have, internal knowledge in text form, and gives it a more durable operating model.

By representing knowledge as Markdown files with YAML frontmatter, OKF creates a structure that is simple enough for people and rich enough for machines. That makes it a strong fit for modern needs such as RAG pipelines, internal copilots, developer portals, governance workflows, architecture knowledge, runbooks, and AI-enabled software delivery.

If you are exploring OKF, the best place to start is not with an enterprise-wide migration. Start with one high-value domain, define a small metadata schema, keep the content in Git, and put it to work in search, review, or AI retrieval.

That is where the value becomes concrete.