Back to Journal
•6 min read

Evolving Google Open Knowledge Format to v0.2: Agentic Trust & Signals

How OKF v0.2 tackles agentic trust, provenance, trust tiers, staleness, and anti-hallucination Attested Computations in AI knowledge graphs.

Google CloudAI AgentsRAGOKFBigQueryData Engineering
Evolving Google Open Knowledge Format to v0.2: Agentic Trust & Signals

When I first documented our implementation of Google's Open Knowledge Format in Implementing Google's Open Knowledge Format (OKF) in Practice, the core goal was solving context isolation for AI agents. By organizing flat markdown files into a navigable, linked graph with YAML frontmatter, agents could recursively traverse documentation tree nodes instead of relying on lossy vector search.

OKF v0.1 established a clean baseline: standard Markdown, lightweight YAML metadata (type, title, description, tags), and explicit relative links.

However, as platform engineering teams shifted from human-written documentation to autonomous multi-agent systems, a fundamental challenge surfaced: When AI agents continuously write and update thousands of knowledge concepts overnight, how can downstream agents or humans trust the corpus?

Human-authored documentation carries an implicit trust guarantee—a developer wrote it and takes accountability for its accuracy. When an agent autonomously generates 10,000 table definitions, metric specifications, and runbooks, that implicit guarantee disappears.

To address this challenge, Google Cloud released the Open Knowledge Format (OKF) v0.2 specification. This update introduces structured Agentic Trust Signals and Attested Computations directly into frontmatter metadata without breaking v0.1 backward compatibility.

From Describing Context to Deciding Trust

In OKF v0.1, frontmatter metadata answered descriptive questions: What is this node, what tags describe it, and where does it point?

OKF v0.2 introduces deciding fields—metadata designed to evaluate a node's origin, freshness, and authority before an agent spends context tokens reading the markdown body.

Parsing the full body of thousands of documentation nodes to evaluate trust is computationally expensive. Elevating trust signals to frontmatter allows agents and deterministic systems to filter out unverified, stale, or deprecated concepts cheaply during graph traversal.

OKF Concept Frontmatter
├── Describing Fields (v0.1)  ──> type, title, description, resource, tags
└── Deciding Fields   (v0.2)  ──> generated, verified, status, stale_after, sources

The 5 Core Trust Signals in OKF v0.2

OKF v0.2 establishes five standardized metadata families that answer critical questions about any knowledge concept:

1. Provenance (sources)

Rather than assigning a single, arbitrary trust score, OKF v0.2 records raw provenance signals in a sources array. Entries can point to external documentation, relative bundle paths, or database scopes, enriched with credibility markers (author, usage_count, last_modified).

Inside the body text, specific claims link back to these sources using standard Markdown footnotes (e.g., [^warehouse-schema]):

sources:
  - id: warehouse-schema
    resource: https://wiki.acme.internal/data/warehouse/schemas/sales
    title: Acme Retail Warehouse Schema
    author: team:data-platform
    usage_count: 1240
    last_modified: 2026-06-15
  - id: revenue-policy
    resource: policies/revenue-recognition.md
    title: Revenue Recognition Policy (FY2026)
    author: human:jsmith@acme
    last_modified: 2026-06-15

2. Trust Tiers (generated vs verified)

OKF v0.2 explicitly separates who authored a concept from who confirmed it:

  • generated: { by, at }: Records the authoring entity (e.g., reference_agent/gemini-2.5-pro) and creation timestamp.
  • verified: [ { by, at } ]: Records independent reviews by machine processes or human sign-offs.

From these fields, consumers infer three distinct Trust Tiers:

  1. Unverified: Missing verified key.
  2. Machine-Confirmed: Verified strictly by automated background tools (e.g., nightly CI/CD linters).
  3. Human-Reviewed: Explicitly signed off by a human actor (e.g., human:kliu@acme).
generated: 
  by: reference_agent/gemini-2.5-pro
  at: 2026-06-30T14:00:00Z
verified:
  - by: human:jsmith@acme
    at: 2026-07-01T09:00:00Z

An executive reporting pipeline can filter specifically for human-reviewed metrics, while a staging environment can accept machine-confirmed concepts.

3. Freshness (stale_after)

Instead of relative TTL durations (e.g., "valid for 30 days"), OKF v0.2 uses an absolute ISO-8601 date (e.g., stale_after: 2026-12-31).

Relative TTLs depend on when a concept was fetched, leading to non-deterministic agent behavior. Absolute dates enable simple date comparisons: if the current system timestamp exceeds stale_after, the concept is flagged for re-verification before serving.

4. Lifecycle (status)

Concepts move through explicit lifecycle states: draft → stable → deprecated (omitted defaults to stable).

When business logic evolves—such as updating a cost-allocation formula—the previous definition is marked status: deprecated. This preserves historical query reproducibility while preventing agents from applying outdated metrics to new tasks:

type: Metric
title: Gross Margin (Legacy, pre-FY2026)
status: deprecated

Attested Computations: Preventing Agent SQL Improvisation

Provenance and verification confirm that a metric definition matches company policy. However, when an agent reports a financial metric (e.g., Year-to-Date Revenue), a dangerous failure mode remains: the agent might improvise its own SQL query.

OKF v0.2 introduces a new concept type: Attested Computation. It defines both the sanctioned calculation and a mechanism to verify that the query executed matched the sanctioned definition.

      ┌─────────────────────────────────────────────────────────┐
      │               Attested Computation Node                 │
      │  - runtime: bigquery                                    │
      │  - parameters: [year]                                   │
      │  - executor: skills/run-on-bq.md                        │
      │  - attester: attesters/sql_equality.py                  │
      └──────────────────────────┬──────────────────────────────┘
                                 │
                 1. Binds declared parameters
                 2. Executes sanctioned SQL
                                 ▼
                      ┌─────────────────────┐
                      │ Execution Receipt   │
                      │ - job_id            │
                      │ - executed_sql      │
                      │ - result            │
                      └──────────┬──────────┘
                                 │
                 3. Deterministic AST verification
                                 ▼
                      ┌─────────────────────┐
                      │  Attester Verdict   │
                      │  - OK / REJECTED    │
                      └─────────────────────┘

Production Example: BigQuery Revenue Attestation

Below is an OKF v0.2 Attested Computation concept node for BigQuery fiscal revenue:

---
type: Attested Computation
title: Revenue for a Fiscal Year
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: skills/run-on-bq.md
receipt: [job_id, executed_sql, result]
attester:
  resource: attesters/sql_equality.py
generated:
  by: reference_agent/gemini-2.5-pro
  at: 2026-06-30T14:00:00Z
verified:
  - by: human:jsmith@acme
    at: 2026-07-01T09:00:00Z
status: stable
stale_after: 2026-12-31
sources:
  - id: revenue-policy
    resource: policies/revenue-recognition.md
    title: Revenue Recognition Policy (FY2026)
    author: human:jsmith@acme
    last_modified: 2026-06-15
---

# Computation

```sql
SELECT
  SUM(
    CASE 
      WHEN o.currency = 'USD' THEN o.net_amount
      ELSE o.net_amount * fx.rate_to_usd
    END
  ) AS revenue_usd
FROM `acme.sales.orders` AS o
LEFT JOIN `acme.finance.fx_daily_rates` AS fx
  ON fx.currency = o.currency 
 AND fx.rate_date = DATE(o.order_ts)
WHERE o.order_status = 'delivered'
  AND DATE_DIFF(CURRENT_DATE(), DATE(o.order_ts), DAY) >= 30
  AND EXTRACT(YEAR FROM o.order_ts) = @year

How Attestation Runs

  1. Parameter Binding Only: The agent is restricted to supplying declared parameters (@year). It cannot edit the SQL text or add custom WHERE clauses.
  2. Execution Receipt: The execution layer returns a signed receipt containing the job_id, executed_sql, and result.
  3. Deterministic Attestation: A non-LLM Python script (sql_equality.py) parses both the target SQL and executed_sql into Abstract Syntax Trees (AST). If keywords, table joins, or filter conditions differ, attestation fails and the result is rejected.

Backward Compatibility & Migration

OKF v0.2 is designed as a fully additive, backward-compatible release. Existing v0.1 bundles remain valid without modification.

Key schema evolutions include:

  • timestamp is superseded by generated.at.
  • # Citations markdown sections are superseded by the structured sources frontmatter array.
  • In both cases, v0.2 parsers fall back directly to v0.1 fields if the new keys are absent.
// OKF v0.2 Parser Fallback Pattern
const creationTime = frontmatter.generated?.at ?? frontmatter.timestamp;
const documentSources = frontmatter.sources ?? parseLegacyCitations(markdownBody);

Key Takeaways

Google's OKF v0.2 specification transforms flat markdown knowledge bases into verifiable agentic graph networks:

  1. Deciding over Describing: Frontmatter elevated metadata enables cheap trust filtering before loading prose.
  2. Explicit Trust Tiers: Clear separation between generated and verified metadata exposes human sign-offs vs machine confirmations.
  3. Deterministic Staleness: Absolute stale_after dates prevent non-deterministic TTL evaluation.
  4. Attested Computations: Combining parameter-bound execution with AST equality attesters eliminates agent SQL hallucination.

By adopting OKF v0.2 standards, platform teams can safely scale autonomous AI workflows while maintaining strict data governance and auditability.

Share this article