GO TO A SECTION

↑ ↓ to navigate · Enter to openExplore all sections →
FDEInterviews logo

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.

A bundle is a folder; a concept answers four questionsWhat is it?: type, title, description, resource, tags. Where did it come from?: sources[] with author, usage_count, last_modified; footnotes cite a source id. How far can I trust it?: generated {by, at} and verified [{by, at}] give the trust tier. Is it still current?: status, superseded_by, stale_after. Attested Computation: runtime, parameters, executor, attester. The agent fills in parameter values; a deterministic attester checks the receipt.. metrics link to it. The bundle tree shows index.md with okf_version, log.md, table, metric and computation concepts, and an attester asset. The revenue metric concept answers what it is, where it came from, how far to trust it, and whether it is current. Metrics can link to an attested computation. A bundle is a folder; a concept answers four questions OKF v0.3. Frontmatter families are optional; a consumer must still accept a concept that lacks them. BUNDLE index.md okf_version: "0.3" log.md history, not a concept tables/ └ orders.md type: BigQuery Table metrics/ └ revenue.md type: Metric └ gross-margin.md status: deprecated computations/ └ revenue-ytd.md type: Attested Computation references/ └ attesters/sql-equality.py an asset, not a concept What is it? type, title, description, resource, tags Where did it come from? sources[] with author, usage_count, last_modified; footnotes cite a source id How far can I trust it? generated {by, at} and verified [{by, at}] give the trust tier Is it still current? status, superseded_by, stale_after Attested Computation runtime, parameters, executor, attester. The agent fills in parameter values; a deterministic attester checks the receipt. metrics link to it

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.

ChangeKindWhat it means in practice
Paths without a leading / resolve from the file's directoryBreakingtables/orders.md written in metrics/revenue.md now means metrics/tables/orders.md
Only current verification events give the trust tierBreakingA review before the last content change no longer counts
superseded_by on deprecated conceptsAdditiveRetire or move a concept without breaking links to it
Bundle metadata in the root index.md: okf_version, title, description, licenseAdditiveA consumer can tell which spec a bundle targets and when to use it
Extension keys allowed at every level; x- reserved for usersAdditiveCustom 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 UTCClarifiedA date-time without an offset is invalid
An unknown status is not stable; an unparseable stale_after is never freshClarifiedMalformed data fails closed for freshness, open for consumption
Consumers must not reject unknown keys, unknown types, missing fields or broken linksClarifiedReaders 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.

How an OKF 0.3 consumer computes the trust tierCollect verified events: Ignore any event missing by or at. A bare mapping counts as a list of one.. Keep events at or after generated.at: If generated is absent, every event is current. A date-only value means midnight UTC.. Is any current event by a human: actor?: team: and process: actors are not human for this rule.. yes. no, but some. no current event. human-reviewed: A named person checked this text.. machine-confirmed: A process or team checked it.. unverified: Earlier events stay as history.. A date-only verification on 25 June means midnight UTC, before a 09:00 regeneration that day, so it does not count. How an OKF 0.3 consumer computes the trust tier Section 5.3. Only events at or after generated.at count. Trust tiers are advisory, not access control. Collect verified events Ignore any event missing by or at. A bare mapping counts as a list of one. Keep events at or after generated.at If generated is absent, every event is current. A date-only value means midnight UTC. Is any current event by a human: actor? team: and process: actors are not human for this rule. yes no, but some no current event human-reviewed A named person checked this text. machine-confirmed A process or team checked it. unverified Earlier events stay as history. THE SAME-DAY TRAP 00:00 UTC verified at: "2026-06-25" 09:00 generated.at reviewer actually signed here

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.

python
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)
Code
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.

One path, two readings"/tables/orders.md": Leading slash: from the bundle root. Resolves to tables/orders.md.. "tables/orders.md": No slash: from this file’s folder. In 0.3 that is metrics/tables/orders.md.. "../../../etc/passwd": Leaves the bundle root. External: never read from the local file system.. A bundle that declares okf_version 0.2, or no version, may fall back to the bundle root for a bare path. Fix paths before you change the declared version. One path, two readings Links and path fields written inside metrics/revenue.md, resolved under OKF 0.3 section 6. BUNDLE ROOT index.md tables/ └ orders.md metrics/ └ revenue.md └ tables/orders.md does not exist: a broken link, accepted "/tables/orders.md" Leading slash: from the bundle root. Resolves to tables/orders.md. "tables/orders.md" No slash: from this file’s folder. In 0.3 that is metrics/tables/orders.md. "../../../etc/passwd" Leaves the bundle root. External: never read from the local file system. A bundle that declares okf_version 0.2, or no version, may fall back to the bundle root for a bare path. Fix paths before you change the declared 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 forUse something else for
Definitions, joins, policies and runbooks an agent must read and citeExecuting a metric definition: a semantic layer
Provenance and review history that travels with the fileEnforcing constraints: the database
A computation the agent must run unchanged, checked by an attesterAuthorization: your identity and access system
Knowledge you want to diff and review like codeFast-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

  1. Start with one domain the agent gets wrong today. A dozen metric definitions or the joins behind one dashboard is enough.
  2. Write okf_version: "0.3" and a description in the root index.md. Consumers use the description to decide when a bundle applies.
  3. 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.
  4. Set stale_after only where someone owns the review date, and treat malformed values as an error in CI even though consumers treat them as stale.
  5. Fail the build on broken links and paths that leave the bundle, because consumers are told not to.
  6. Let agents propose changes through pull requests. The demotion rule then shows reviewers exactly which concepts lost their human review.

Pros and cons

ProsCons
Plain files: diff, review and version like codeNo runtime: execution, attestation and identity are left to you
Trust and freshness that survive agent edits, by ruleTolerant consumers mean errors surface late unless CI is strict
Apache-2.0, vendor-neutral, now in its own orgVersion 0.x: the spec allows breaking changes before 1.0
Reference skills for generating and consuming bundlesTyped 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.

PRACTICE THIS

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.

Discussion (4)

Arjun MehtaEditor

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.

Emily CarterEditor

Reader question: why would a team sign-off count as machine-confirmed? A team is people.

Lukas HoffmannEditor

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.

Hannah BryantEditor

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.