Open Knowledge Format 0.3: What Changed, the Two Breaking Rules, and How an Agent Should Read Trust
Google's Open Knowledge Format (OKF) 0.3 moved to its own Apache-2.0 GitHub org. We read the spec and ran its trust, staleness and path rules: an agent rewrite now demotes a human review, a same-day date-only sign-off does not count, and relative paths resolve differently.
BY LUKAS HOFFMANN · FDEINTERVIEWS EDITORIAL · UPDATED NOVEMBER 19, 2026 · 7 MIN READ
PRACTICE THIS:The semantic layer for AI agents ·Ontology and semantic layer ·RAG and agent questions ·The must-know FDE questions
Open Knowledge Format 0.3 is out, and the change that matters most is a single trust rule: a review only counts if it happened after the last time the content changed. OKF, started at Google and now in its own Apache-2.0 GitHub organization, packages the context an agent needs (what a metric means, which table to join, which computation is approved) as plain Markdown files with YAML frontmatter. Version 0.3 makes that context safer to share between organizations and to edit with several agents at once. It has two breaking changes, both deliberate: relative paths resolve from the file's own folder, and an agent rewrite demotes a human review. We implemented three of the spec's rules in a few lines of Python and ran them on edge cases. One result surprised us: a person who signs off on the same day as an agent's change, and writes the date without a time, does not count as a reviewer.
The announcement this week framed 0.3 as preparation for real use: bundles that travel between organizations, several agents editing one corpus, and different tools that must read a bundle identically. Everything below is from the specification at commit 527e81a, read on 19 November 2026.
What OKF is, in one picture
A bundle is a folder. Each concept is one Markdown file whose frontmatter has a type (a table, a metric, a policy, a computation) plus optional families that answer three questions: where did this come from, how far can I trust it, and is it still current. The body is ordinary CommonMark with tables and footnotes. Concepts link to each other with normal Markdown links.
The design choice that makes OKF useful to an FDE is that none of this needs a server. A bundle can be diffed, reviewed in a pull request, and pushed to whatever serves knowledge to agents. Google ships a connector for its Knowledge Catalog, and two agent skills: okf-generate writes and repairs bundles, okf-consume answers questions from one and reports the trust of every concept it used. If you have read our semantic layer concept, OKF is a portable file format for the same knowledge, not a query engine.
What changed in 0.3
The spec's own change list has three parts. The table keeps what changes behavior and drops the editorial fixes.
| Change | Kind | What it means in practice |
|---|---|---|
Paths without a leading / resolve from the file's directory | Breaking | tables/orders.md written in metrics/revenue.md now means metrics/tables/orders.md |
| Only current verification events give the trust tier | Breaking | A review before the last content change no longer counts |
superseded_by on deprecated concepts | Additive | Retire or move a concept without breaking links to it |
Bundle metadata in the root index.md: okf_version, title, description, license | Additive | A consumer can tell which spec a bundle targets and when to use it |
Extension keys allowed at every level; x- reserved for users | Additive | Custom fields such as x-acme-not will not collide with a future spec |
| Timestamps are RFC 3339 date-times with an offset, or a date only, meaning midnight UTC | Clarified | A date-time without an offset is invalid |
An unknown status is not stable; an unparseable stale_after is never fresh | Clarified | Malformed data fails closed for freshness, open for consumption |
| Consumers must not reject unknown keys, unknown types, missing fields or broken links | Clarified | Readers stay tolerant; strictness belongs in your CI |
The spec also lists what it deliberately left out: a wire format for computation receipts, the attester interface, typed relationships between concepts, and a refuted verification event. Until those land, use extension keys and agree a convention inside your organization.
The rule that matters: a review only counts after the last change
OKF keeps two fields apart. generated records who or what last made a meaningful change and when. verified is a list of {by, at} events. An event is current when its at is at or after generated.at. The trust tier comes only from current events: none means unverified, current events from non-human actors only mean machine-confirmed, and a current event from a human: actor means human-reviewed.
That rule exists for exactly the situation OKF is built for: agents editing knowledge. The spec puts it plainly: when an agent rewrites a concept after a human review, "the human did not read the new text."
What we ran
We wrote a minimal reader for three rules (trust tier, staleness and path resolution) straight from the spec text, and fed it the edge cases a migration will hit. The "v0.2-style" column counts any verification event, which is how a reader that ignores the new currency rule behaves.
from datetime import datetime, timezone
from posixpath import normpath, dirname, join
def ts(v):
"""RFC 3339 date-time with an offset, or a date only (midnight UTC); else None."""
if not isinstance(v, str):
return None
try:
if len(v) == 10:
return datetime.strptime(v, "%Y-%m-%d").replace(tzinfo=timezone.utc)
d = datetime.fromisoformat(v.replace("Z", "+00:00"))
return d if d.tzinfo else None
except ValueError:
return None
def tier(fm, rule="v0.3"):
events = fm.get("verified") or []
events = [events] if isinstance(events, dict) else events # bare mapping = list of one
events = [e for e in events if e.get("by") and e.get("at")]
gen = (fm.get("generated") or {}).get("at")
if rule == "v0.3" and gen:
g = ts(gen)
events = [e for e in events if g and ts(e["at"]) and ts(e["at"]) >= g]
if not events:
return "unverified"
return "human-reviewed" if any(e["by"].startswith("human:") for e in events) else "machine-confirmed"
def freshness(fm, now):
v = fm.get("stale_after")
if v in (None, ""):
return "no review date"
t = ts(v)
return "MALFORMED (never fresh)" if t is None else ("stale" if now >= t else "fresh")
def resolve(value, file):
if "://" in value:
return ("external URL", value)
p = normpath(value.lstrip("/")) if value.startswith("/") else normpath(join(dirname(file), value))
return ("outside bundle: do not read", p) if p.startswith("..") else ("in bundle", p)
human review, then an agent rewrite v0.2-style: human-reviewed v0.3: unverified
same-day sign-off written as a date v0.2-style: human-reviewed v0.3: unverified
a team signs off v0.2-style: machine-confirmed v0.3: machine-confirmed
event missing its time v0.2-style: unverified v0.3: unverified
stale_after='2026-09-23T00:00:00Z' -> stale
stale_after='2027-03-31' -> fresh
stale_after='next quarter' -> MALFORMED (never fresh)
stale_after=None -> no review date
in metrics/revenue.md, '/tables/orders.md' -> ('in bundle', 'tables/orders.md')
in metrics/revenue.md, 'tables/orders.md' -> ('in bundle', 'metrics/tables/orders.md')
in metrics/revenue.md, '../tables/orders.md' -> ('in bundle', 'tables/orders.md')
in metrics/revenue.md, '../../../etc/passwd' -> ('outside bundle: do not read', '../../etc/passwd')
in metrics/revenue.md, 'https://wiki.acme/x' -> ('external URL', 'https://wiki.acme/x')
Three findings are worth carrying into a design review.
The same-day trap. The agent regenerated the concept at 09:00 UTC on 25 June. A reviewer signed off the same afternoon but wrote at: "2026-06-25". A date-only value means midnight UTC, which is before 09:00, so the review is not current and the concept is unverified. The spec anticipates this: producers "SHOULD use the date-time form" for both fields because consumers compare them. Make your review tooling write a full timestamp. Do not leave it to people typing YAML.
A team is not a human. A team:finance sign-off gives machine-confirmed, the same as a nightly job. The spec reserves human-reviewed for a human: actor. If a review by a named person matters to your customer's auditors, record the person.
Paths fail without an error. Under 0.3, tables/orders.md written inside metrics/ points at metrics/tables/orders.md. If that file does not exist, the consumer is required to accept the broken link and carry on. A v0.2 bundle that declares okf_version: "0.2" (or no version) allows a reader to fall back to the bundle root. A bundle that upgrades its version without fixing paths loses that fallback. Run a link check in CI before you change the version.
Where OKF fits, and where it does not
OKF is a good fit when knowledge has to move: between a customer's data team and an agent vendor, between two business units, or from a person's head into a reviewed file an agent can cite. It is a weak fit for knowledge that changes every minute or that a system already enforces. A semantic layer already executes metric definitions, and a database already enforces a foreign key. The README says OKF refers to standards such as Avro, Protobuf or OpenAPI rather than absorbing them, and it describes a usecases/ folder for pairing OKF with such standards. At the commit we read, that folder had not been added yet.
| Use OKF for | Use something else for |
|---|---|
| Definitions, joins, policies and runbooks an agent must read and cite | Executing a metric definition: a semantic layer |
| Provenance and review history that travels with the file | Enforcing constraints: the database |
| A computation the agent must run unchanged, checked by an attester | Authorization: your identity and access system |
| Knowledge you want to diff and review like code | Fast-changing operational state: an API |
Two cautions apply however you use it. Trust tiers are, in the spec's words, "advisory signals, not access control," and a file can claim any verifier, so authenticate where bundles come from before letting a tier drive a decision. And attested computations need more than the format: OKF "records the computation and the means to check it" but "does not run anything." The executor, the sandbox and the receipt transport are yours to build.
How we would adopt it with a customer
- Start with one domain the agent gets wrong today. A dozen metric definitions or the joins behind one dashboard is enough.
- Write
okf_version: "0.3"and adescriptionin the rootindex.md. Consumers use the description to decide when a bundle applies. - Make review tooling write full timestamps and named
human:actors. That is the difference between a tier you can show an auditor and one you cannot. - Set
stale_afteronly where someone owns the review date, and treat malformed values as an error in CI even though consumers treat them as stale. - Fail the build on broken links and paths that leave the bundle, because consumers are told not to.
- Let agents propose changes through pull requests. The demotion rule then shows reviewers exactly which concepts lost their human review.
Pros and cons
| Pros | Cons |
|---|---|
| Plain files: diff, review and version like code | No runtime: execution, attestation and identity are left to you |
| Trust and freshness that survive agent edits, by rule | Tolerant consumers mean errors surface late unless CI is strict |
| Apache-2.0, vendor-neutral, now in its own org | Version 0.x: the spec allows breaking changes before 1.0 |
| Reference skills for generating and consuming bundles | Typed relationships and a refuted event are still deferred |
What to say about it in an interview
If an interviewer asks how you would give an agent trustworthy business context, OKF is a good example to reason with, not a product to recommend. The strong answer names the rule: "Every concept records who last changed it and who last checked it, and a check only counts if it came after the change. When an agent edits the knowledge base, the tier drops until a person reads the new text, and the agent tells the user what tier it relied on." That idea works in OKF, in a catalog or in a wiki with a review workflow.
Turn it into offers. Work the real questions and concepts this maps to:
FAQ
OKF is an open, vendor-neutral format for giving AI agents business context as plain Markdown files with YAML frontmatter. A bundle is a directory of concept documents, such as a metric, a table or a procedure, with fields for where each came from, who verified it, when it goes stale and, optionally, an approved computation an agent must run unchanged. Version 0.3 is Apache-2.0 and lives in its own GitHub organization.
Two breaking changes: a path without a leading slash now resolves from the file's own directory, and only verification events at or after the content's last generation count toward its trust tier. It also adds superseded_by for retired concepts, bundle metadata (okf_version, title, description, license) in the root index.md, rules for x- extension keys, fixed timestamp rules, and consumer rules for empty or unexpected values.
Yes, under 0.3. A verification event counts only if its time is equal to or later than generated.at, the last meaningful change to the content. If an agent rewrites a concept after a person reviewed it, the concept is no longer human-reviewed until a person confirms the new text.
No. The spec calls trust tiers advisory signals, not access control, and a consumer must not reject a concept just because trust fields are missing. Anyone who can write a file can also write a verifier name into it, so treat the tier as a claim to check through your own distribution and identity controls.
A semantic layer or catalog executes or governs definitions inside a system. OKF is a portable file format for the knowledge itself: definitions, joins, policies and provenance that any agent or tool can read, diff and review like code. Its README says it refers to standards such as Avro, Protobuf or OpenAPI rather than absorbing them.
Discussion (4)
The demotion rule is the right default and it will surprise people. Every team that lets an agent tidy its knowledge base will watch half its human-reviewed concepts drop a tier overnight. That is not a bug in the agent. It is the format telling you the truth about who has read the current text.
Reader question: why would a team sign-off count as machine-confirmed? A team is people.
Because the spec reserves human-reviewed for a named human actor, and team: names a group, not someone who read the text. If you want a team review to count as human, record the person who did it. If the team signs off through a pipeline, it really is a process.
The path change is the one that will break real bundles quietly. A v0.2 bundle that wrote tables/orders.md from deep inside metrics/ resolves somewhere else under 0.3, and the consumer is told to accept broken links. Declare okf_version and run a link check in CI before you migrate.
