DEV Community: Vivek Maskara

Why Google’s Open Knowledge Format Matters for Developers and Content Creators?

Vivek Maskara — Wed, 17 Jun 2026 02:24:11 +0000

Most teams don’t suffer from a lack of data. They suffer from a lack of shared context. Definitions, caveats, ownership, and “how to use this safely” guidance end up scattered across wikis, tickets, dashboards, and people’s heads. Google’s Open Knowledge Format (OKF) tackles that sprawl by packaging curated context as a portable, versionable bundle of “just files” that both humans and AI agents can consume reliably (Google Cloud Blog, Jun 12 2026, OKF SPEC.md).

This article covers the problem OKF targets, what the format is (and isn’t), and the building blocks that make it work. It then explains why OKF fits developer workflows and content operations, plus adoption patterns, tradeoffs, and practical next steps.

The real problem OKF is trying to solve: “context sprawl”

OKF exists because the most important knowledge in an organization often isn’t the data itself. It’s the context around the data, and that context is scattered. Google describes this as “metadata, context, and curated knowledge” spread across too many surfaces to share or reuse cleanly (Google Cloud Blog, Jun 12 2026).

This fragmentation hurts humans. It hurts AI agents and cross-team work even more. People compensate with experience. They know which wiki is “more correct,” who to ask, and which dashboard is legacy. Agents don’t have that intuition. When context is missing or split across systems, an agent has to infer and guess. That leads to confident wrong answers and brittle automations.

It also helps to separate data from context:

Data: table schemas, API contracts, dbt models.
Context: metric definitions, caveats, ownership, join guidance, deprecations, and runbooks.

Without context, two teams can query the same table and still disagree on what “revenue” means.

Before OKF, a developer debugging a revenue discrepancy might find SQL in a dashboard, a definition in a wiki page, and a deprecation note buried in a ticket. Then they repeat the same archaeology next week. OKF is positioned as a portable corpus that tools (and agents) can consume, not as “another portal.”

What OKF is (and what it is not)

The simplest way to understand OKF is as a file-based packaging standard for curated knowledge. It’s small enough to live in git, structured enough to index, and neutral enough to move across tools.

OKF in one sentence: a directory of Markdown + YAML frontmatter

Per Google’s announcement and the specification, OKF is a vendor-neutral way to package curated organizational knowledge as a directory of Markdown files. Each file includes YAML frontmatter for structured metadata (Google Cloud Blog, Jun 12 2026, OKF SPEC.md). The key idea is that it’s “just files.” There’s no required SDK, runtime, schema registry, or central service.

Markdown plus YAML is a deliberate trade. Humans can review it in pull requests, and diffs stay readable. Tools can parse the frontmatter to index and retrieve concepts consistently.

---
type: metric
title: "Revenue (Net)"
description: "Net revenue excluding refunds and chargebacks."
resource: bigquery://analytics.metrics/revenue_net
tags: [finance, gaap, executive-dashboard]
timestamp: 2026-06-12T00:00:00Z
---
Metric notes, caveats, and links go here in Markdown.

What OKF is not: not a replacement for domain schemas or APIs

The spec is explicit that OKF doesn’t replace domain-specific schemas or interface definitions such as Avro, Protobuf, OpenAPI, or dbt models (OKF SPEC.md). Instead, it acts as a curation and metadata wrapper. It points at sources of truth and adds context they don’t capture well, like usage guidance and operational notes. This reduces schema duplication and helps avoid “two sources of truth.”

---
type: api-endpoint
title: POST /v1/orders
resource: https://api.example.com/openapi.yaml#/paths/~1v1~1orders/post
tags: [orders, public-api]
timestamp: 2026-06-12T00:00:00Z
---
Use `Idempotency-Key` for retries. Deprecated fields: `promoCode` (use `discounts[]`).

Common confusion: OKF vs Google Knowledge Graph / schema.org markup

OKF is for internal, file-based knowledge bundles meant to be shared and used by tools and agents. The Google Knowledge Graph Search API is different. It’s a hosted service that returns entity results as JSON-LD using schema.org types (Knowledge Graph Search API docs). A quick check helps: OKF lives in repos and filesystems. Knowledge Graph is an online entity search API.

How OKF works: the building blocks developers can reason about

Once you accept “it’s just files,” the next question is how those files become something tools can index, link, and retrieve. OKF’s answer is a small set of filesystem-friendly rules.

Knowledge Bundles, Concepts, and Concept IDs

The spec defines a filesystem-native mental model (OKF SPEC.md):

A Knowledge Bundle is a distributable directory tree.
Each Concept is exactly one Markdown document.
The Concept ID is derived from the file path (minus .md).

Path-based IDs stay stable under version control. They also make it easy for tools to reference concepts without inventing a separate identifier scheme.

knowledge-bundle/
  datasets/
    ga4_ecommerce.md            # conceptId: datasets/ga4_ecommerce
  tables/
    ga4/events.md               # conceptId: tables/ga4/events
  metrics/
    revenue_net.md              # conceptId: metrics/revenue_net
  runbooks/
    revenue_discrepancy.md      # conceptId: runbooks/revenue_discrepancy

YAML frontmatter as the “queryable surface area”

OKF keeps structure intentionally small. Google highlights a compact set of frontmatter fields, type, title, description, resource, tags, timestamp, that tools can index for filtering and routing (Google Cloud Blog, Jun 12 2026). The spec defines the normative rules (OKF SPEC.md).

This is what makes “retrieve all runbooks tagged incident-response” a metadata query instead of a full-text guessing game.

---
type: metric
title: Revenue (Net)
description: Net revenue excluding refunds and chargebacks.
resource: bigquery://analytics.metrics/revenue_net
tags: [revenue, finance]
timestamp: 2026-06-12T00:00:00Z
---

Markdown body as the “human-first, agent-usable” narrative layer

OKF uses plain Markdown for the body. That keeps content readable in GitHub or internal doc sites. It also stays easy for agents to chunk, quote, and follow links. Links express relationships beyond folders. For example, a metric can point to its source table and the runbook for incidents.

See source table: ../tables/ga4/events.md
Incident response: ../runbooks/revenue_discrepancy.md

Why OKF matters for developers: interoperability, workflows, and agent grounding

With the mechanics in place, the developer value becomes clearer. OKF is a low-friction interchange format that fits engineering workflows while making agent grounding more dependable.

Interoperability without glue code: “format, not service”

OKF matters to developers because it’s a format you can move around, not a platform you must integrate with. Bundles are “just files,” so producers and consumers only need filesystem access plus a Markdown/YAML parser (Google Cloud Blog, Jun 12 2026, OKF SPEC.md). You can keep a bundle in git, publish a pinned tarball for reproducible runs, or mount it into an environment where tools and agents can read it.

A concrete payoff is cross-stack reuse. A data platform team can publish a bundle once. Then a Python agent pipeline, a TypeScript IDE helper, and a catalog ingestion job can all consume the same directory tree.

“Knowledge as code” practices applied to context

Because OKF is diffable text, it fits normal engineering discipline. Metric definitions and runbooks can be updated via PRs, reviewed by owners, and rolled back when needed. That turns “why did this number change?” into a git blame instead of a Slack archaeology expedition. The spec’s version-control friendliness is the enabling detail (OKF SPEC.md).

In practice, teams add CI gates that keep the bundle coherent:

# Example CI gate: fail if any concept link points to a missing file
python scripts/check_links.py knowledge-bundle

Better agent grounding: fewer hallucinations, more reliable automation

Google frames OKF as a way to ground agents with the right context. That includes definitions, caveats, deprecations, and operational procedures (Google Cloud Blog, Jun 12 2026). Stable concept IDs plus queryable frontmatter let retrieval start narrow (by type and tags). Tools can then traverse links to assemble the “full story” for a task.

---
type: runbook
title: Revenue discrepancy triage
tags: [incident-response, revenue]
timestamp: 2026-06-12T00:00:00Z
---

An incident bot can pull the runbook and route to the right owner. An analytics agent can retrieve the metric concept to avoid using the wrong definition.

Why OKF matters for content creators: an “LLM-wiki” you can ship

Developers care about interoperability and workflow fit. Content creators care about portability, editorial control, and reuse across audiences and tools. OKF is designed to meet those needs without forcing a single publishing platform.

OKF as a standardized, portable “LLM-wiki” pattern

OKF turns the “LLM-wiki” idea into something teams can adopt without committing to one wiki product. Google frames the format as a way to standardize that pattern: write human-readable Markdown, add a small amount of structured metadata, and ship the result as a bundle of files (Google Cloud Blog, Jun 12 2026).

That portability is the unlock. A docs team can curate a product-concepts/ bundle for feature behavior and deprecations. A data team can curate an analytics-concepts/ bundle for metrics, tables, and runbooks. You can publish both internally, open-source a subset, or share across org boundaries.

Metadata that makes content discoverable and reusable

YAML frontmatter is what makes OKF feel less like “a folder of docs” and more like a queryable knowledge base. Tags let you slice content by audience or lifecycle (deprecated, oncall, exec). resource anchors a concept to the system of record. timestamp provides a freshness signal that search and agents can respect.

Over time, editors can standardize templates per type, so readers recognize the shape quickly.

---
type: runbook
title: Payments latency spike
description: Triage and mitigation steps for elevated p95 latency.
resource: https://monitoring.example.com/dashboards/payments
tags: [incident-response, payments, oncall]
timestamp: 2026-06-12T00:00:00Z
---

## Symptoms
## Diagnosis
## Mitigation
## Escalation

Publishing and maintenance workflows that don’t fight your tools

Because OKF uses Markdown, it renders cleanly on GitHub/GitLab. It can also sync into an internal docs portal without rewriting content. Google highlights shipping bundles as artifacts, which maps well to editorial release trains (Google Cloud Blog, Jun 12 2026). For example, you can run a monthly “data platform bundle” release with changelogs, review rotations, and a style guide.

Practical adoption patterns

OKF is simple in theory. Adoption succeeds when you use that simplicity to enforce clarity, not to create near-duplicate docs.

Pattern: concept-per-file bundles organized by domain

The spec’s “concept-per-file” rule is easiest to run when you organize by domain folders. Express relationships as links rather than mega-pages (OKF SPEC.md). A simple starting tree keeps concepts small enough to reuse.

knowledge-bundle/
  metrics/revenue_net.md
  tables/orders.md
  policies/refunds.md
  runbooks/revenue_discrepancy.md

Inside metrics/revenue_net.md, keep the YAML frontmatter queryable. Use Markdown links to connect the graph:

---
type: metric
title: Revenue (Net)
resource: bigquery://analytics.marts/revenue_net
tags: [revenue, finance]
timestamp: 2026-06-12T00:00:00Z
---

Derived from [Orders table](../tables/orders.md). Refund handling: [Refund policy](../policies/refunds.md).

Pattern: distribute OKF as an artifact (repo, release, filesystem)

Because bundles are “just files,” distribution is a packaging decision. Use a git repo for collaboration and review. Publish tarball releases for pinned, reproducible consumption. Optionally sync to a shared mount for runtime access (Google Cloud Blog, Jun 12 2026).

For agents, pin explicitly, for example: “use bundle v2026.06 for this workflow run.” That prevents retrieval from drifting mid-incident.

tar -czf knowledge-bundle.tgz knowledge-bundle/
# attach knowledge-bundle.tgz to a release like v2026.06

Pattern: pair OKF with catalog ingestion (Google Cloud Knowledge Catalog example)

Google says Google Cloud Knowledge Catalog can ingest OKF and serve it to agents (Google Cloud Blog, Jun 12 2026). This split is useful. OKF stays the interchange layer. Catalogs become optional UX and indexing layers, not the only home for context.

For more background on the product direction, see Google’s Knowledge Catalog introduction (Knowledge Catalog blog, Apr 22 2026).

Tradeoffs and pitfalls: where teams stumble and how to avoid it

OKF is intentionally minimal, which makes it portable. The work doesn’t disappear. It shifts into conventions and maintenance.

Inconsistent conventions reduce interoperability

Minimal structure is also a sharp edge. If every team invents its own type values, tag styles, and linking habits, cross-bundle queryability drops. That undermines the standardization OKF is meant to enable (OKF SPEC.md).

Treat conventions as part of the product:

Define a shared type taxonomy.
Use a controlled tag vocabulary (including casing).
Require consistent Markdown sections per type.
Standardize link patterns (relative links, concept-per-file).

A common failure mode is tag casing drift. One team writes incident-response, another writes IncidentResponse, and filters miss half the runbooks. Fix it with templates, review checklists, and CI that rejects nonconforming metadata.

# scripts/normalize_tags.py
import sys, pathlib, re, yaml

def load_frontmatter(text: str):
  m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
  return (yaml.safe_load(m.group(1)) or {}) if m else {}

root = pathlib.Path(sys.argv[1])
bad = []
for md in root.rglob("*.md"):
  fm = load_frontmatter(md.read_text(encoding="utf-8"))
  tags = fm.get("tags") or []
  if any(t != t.lower() for t in tags):
    bad.append(str(md))
if bad:
  raise SystemExit("Non-lowercase tags in:\n" + "\n".join(bad))

Treating OKF as the system of record for schemas

OKF does not replace domain schemas like Avro, Protobuf, or OpenAPI (OKF SPEC.md). Use it to explain and operationalize them. Keep it focused on rationale, caveats, examples, deprecations, and safe usage guidance. A simple rule helps: resource must point to the canonical source-of-truth location.

---
type: api-endpoint
title: CreateOrder
resource: https://repo.example.com/apis/orders/openapi.yaml#/paths/~1v1~1orders/post
tags: [orders, public-api]
timestamp: 2026-06-12T00:00:00Z
---
Retries require `Idempotency-Key`. `promoCode` is deprecated; use `discounts[]`.

Stale knowledge and missing freshness signals

Bundles rot unless you operationalize freshness. Google calls out timestamp as part of the structured fields (Google Cloud Blog, Jun 12 2026). Use it to power staleness dashboards and enforcement, especially for runbooks.

Add ownership conventions, review SLAs, and automated reminders. For high-risk concepts, add a “Last verified” line in Markdown.

# Fail CI if any incident runbook is older than 90 days
python scripts/check_staleness.py knowledge-bundle --type runbook --tag incident-response --max-age-days 90

How to get started: next steps for developers and content teams

Treat OKF like any shared interface. Start with a small, high-value surface area. Lock down conventions early. Add enough automation to keep the bundle trustworthy.

1. Start small: pick one high-value domain and define conventions

Start where missing context repeatedly burns time. Good candidates include your top executive metrics, the most-queried tables, or on-call runbooks. Keep the first bundle small. Prove the workflow (author → review → publish → consume) before scaling.

Define conventions up front:

A minimal type list you will actually use (for example metric, table, runbook, dataset)
A tag vocabulary with consistent casing
One Markdown template per type

Google points to sample bundles (GA4 e-commerce, Stack Overflow, Bitcoin) in its announcement. Keep the spec open while you implement so you follow the normative rules (Google Cloud Blog, Jun 12 2026, OKF SPEC.md).

2. Add quality gates: validation, link checks, and publishing

Because OKF requires no tooling, you can add lightweight CI checks that match your conventions. Common gates include required frontmatter fields, forbidden tags, and broken relative links. If you want stricter guarantees, add JSON Schema validation.

A simple first gate is ensuring Concept IDs (path minus .md) are unique and indexable:

# scripts/index_concepts.py
import sys, pathlib

root = pathlib.Path(sys.argv[1])
ids, dupes = set(), []
for md in root.rglob("*.md"):
    cid = md.relative_to(root).with_suffix("").as_posix()
    if cid in ids:
        dupes.append(cid)
    ids.add(cid)

if dupes:
    raise SystemExit("Duplicate concept IDs:\n" + "\n".join(dupes))
print(f"Indexed {len(ids)} concepts")

Publish in two forms: rendered docs (GitHub Pages or an internal portal) and a pinned bundle artifact (release tarball) for agents.

3. Decide how agents will consume it

Plan for multiple consumption modes without changing content. Options include direct filesystem reads, an indexing pipeline for RAG, or catalog ingestion. Google notes that Knowledge Catalog can ingest OKF and serve it to agents (Google Cloud Blog, Jun 12 2026).

A practical retrieval strategy is “filter, then traverse”:

Filter by type and tags (for example, type: dataset plus a domain tag).
Follow links dataset → tables → metrics → runbooks.

OKF’s core promise is durability. Once your context lives in a knowledge bundle with consistent metadata and links, you can switch catalogs, search layers, and agent frameworks without rewriting the knowledge itself.

You’re Already Using Git Worktrees. You Should Understand Them.

Vivek Maskara — Mon, 18 May 2026 12:18:41 +0000

If you’ve ever run git clone and then started editing files in the resulting folder, you’ve been using a Git worktree all along. Git just doesn’t call it that in day-to-day conversation.

git worktree is the feature that lets you add more checkouts (more folders with files on disk) that all share the same underlying repository history. Done well, it replaces the “stash/switch/stash-back” dance with something simpler: keep your in-progress work open in one directory, and do the urgent/clean/experimental thing in another.

This is a mental-model article: what a worktree is, why Git enforces “one branch per worktree,” and the few lifecycle commands that keep worktrees from turning into confusing “already checked out” / stale-metadata problems.

The Mental Model: Shared History, Separate Working State

Git’s own git worktree docs describe the feature as managing “multiple working trees attached to the same repository.” The twist is that you always start with one: the directory you land in after a normal (non-bare) clone is the main worktree.

Linked worktrees are additional working directories attached to the same repo. They share the object database (commits/trees/blobs), but each worktree has its own working state: checked-out files, its own HEAD, and its own index (staging area).

That’s the whole trick:

Shared: history and objects (you don’t redownload Git data like a second clone).
Per worktree: files-on-disk + HEAD + index (you don’t stomp on your other checkout).

One nuance that matters: a worktree isn’t its own independent “repo.” Most refs and remote configuration are shared. When you git fetch, you’re updating the shared repository data that all worktrees see. That’s what makes worktrees lighter than multiple clones—but it’s also why Git has to be careful about how a branch name maps to a checkout.

If you want a deeper explanation of why “objects live once” makes this efficient, the Git book’s “Git Objects” chapter is a good reference: Git Internals: Git Objects.

What Actually Changes on Disk when You Add a Worktree

Git keeps the shared repository database in one place, then tracks per-worktree state separately. That’s why it can add a second checkout without cloning.

If you’ve ever noticed that .git sometimes looks like a file (not a folder), that’s often Git pointing your working tree at the real “gitdir.” Worktrees lean on this idea heavily: each worktree has its own admin area, but the objects are shared.

The Rule that Surprises People: One Branch per Worktree

If you try to attach the same branch to two worktrees, Git will usually refuse with “branch is already checked out.” That refusal is protection.

The core reason is that a branch name is just a movable pointer. If two working directories could both “be” feature, the branch pointer could move in one directory while the other directory still has older files on disk. Now you have a branch name that no longer uniquely identifies a single working state.

Said differently: Git is fine with multiple worktrees having different HEADs (each checkout is independent), but a branch ref like refs/heads/feature is shared at the repository level. Letting two worktrees both “own” the same branch would create a footgun where “what commit is feature?” depends on which folder last advanced it.

When you want “two directories, same starting point,” Git’s safer options are:

Create a new branch name for the second worktree:

git worktree add ../wt-fix -b fix-branch

Use a detached HEAD when you don’t intend to keep the work long-term:

git worktree add -d ../wt-scratch

Detached HEAD is the “I want another directory at this commit, but I’m not claiming a branch name” mode. That’s why it’s safe: you can still make commits, but you’re not advancing a shared branch ref unless you later create one.

--force exists for edge cases, but it’s opting out of a guardrail. If you don’t already know why you need it, you probably don’t.

Where Worktrees Shine (in Practice)

Worktrees are a productivity primitive whenever parallelism beats context switching. Three common patterns:

1) Hotfix without Touching Your In-Progress Directory

When a production issue lands mid-feature, create a new worktree on a hotfix branch:

git worktree add ../wt-hotfix -b hotfix

You get a clean checkout in a new folder, and your original directory stays exactly as it was. When you’re done, remove it cleanly:

git worktree remove ../wt-hotfix

Tower’s Git worktree FAQ describes this as one of the “default” worktree use cases, and it’s the one most people feel immediately.

2) PR Reviews and Repros in a Clean Sandbox

You can attach a worktree directly to a remote-tracking branch and keep it around for as long as the review takes:

git worktree add ../wt-review origin/some-pr-branch

3) Scratch Experiments You Don’t Want to Keep

Detached worktrees are great for “let me try something” work without committing to a branch name yet:

git worktree add -d ../wt-scratch

If you end up making commits you want to keep, create a branch before you delete the folder so you don’t lose track of them.

A Quick Note on “Why Not Just Clone Twice?”

Separate clones can absolutely solve the same “two directories” problem. The difference is mainly cost and coupling:

Clones duplicate setup (another fetch/clone, another .git object store).
Worktrees share Git objects, but still behave like separate checkouts.

If you need complete isolation (different remotes, radically different Git config, or you want to move one copy around freely), a second clone can still be the simplest answer.

Keeping Your Directories Sane

The simplest convention (and the one that avoids the “oops, I edited the wrong checkout” mistake) is: keep linked worktrees outside the main project folder.

repo/            # main worktree
repo-hotfix/     # linked worktree
repo-review/     # linked worktree

If you do this often, encode intent in the directory name so it’s searchable later (wt-hotfix-1234, wt-pr-998, wt-bisect-crash) instead of generic tmp/.

If you want all worktrees contained under one parent folder, a popular layout is “bare repo + many worktrees” (see Nick Nisi and Ahmed El Gabri). For background on bare repositories themselves, the Git book chapter is a good reference: Git Basics: Getting a Git Repository.

If you try the “bare repo + worktrees” approach, keep the tradeoff in mind: you’re saving Git object duplication, not environment duplication. Two worktrees can still mean two node_modules/ folders, two build outputs, and two IDE indexes. If setup dominates your workflow, keep only the worktrees you’re actively using.

The Lifecycle Gotchas (and the 5 Commands that Prevent Them)

Removing vs Deleting (Stale Metadata)

Deleting a worktree folder in Finder isn’t the same as telling Git it’s gone. Prefer:

git worktree remove ../wt-review

If you already deleted the folder, clean up the leftover admin state:

git worktree prune

Git can also garbage-collect stale worktree metadata automatically over time (controlled by gc.worktreePruneExpire). That’s helpful, but it’s not a substitute for removing worktrees intentionally when you’re done.

“This Branch Is Already Checked Out”

This is Git enforcing “one branch per worktree.” Your usual fixes are:

make a new branch name (-b)
use detached HEAD (-d)

If you’re debugging “why won’t Git let me…”, list the current attachments:

git worktree list

Moving Worktrees (and Repairing when Paths Change)

If you need to reorganize, prefer Git’s commands over dragging folders around in your file manager.

git worktree move <worktree> <new-path> relocates a linked worktree (you can’t move the main worktree).
If you moved things manually and links broke, git worktree repair can reestablish the connection in supported cases.

Intermittent Drives: Lock Before Git Prunes

If a worktree lives on an external drive or network mount, Git may treat it as “missing” when the volume isn’t mounted. Use git worktree lock to prevent surprises:

git worktree lock --reason "On external drive" /Volumes/SSD/wt-release

Cheat Sheet

git worktree add ../wt-name -b my-branch   # new worktree + new branch
git worktree add ../wt-name origin/branch  # worktree from remote-tracking branch
git worktree add -d ../wt-scratch          # detached-HEAD scratch worktree
git worktree list                          # see what's attached
git worktree remove ../wt-name             # remove cleanly
git worktree prune                         # cleanup after manual deletion

The Takeaway

Worktrees aren’t a niche add-on. They’re the name for the checkout you already use, plus a way to add more checkouts without cloning again. Keep the mental model in your head—shared history, separate working state—and Git’s guardrails (like one branch per worktree) stop feeling arbitrary and start feeling helpful.

If you learned something from this post, give me a follow and checkout the AI powered markdown editor that i am building on the side.