Skip to content
Surfacev0.8.0

Surface and the Open Knowledge Format

Google’s Open Knowledge Format (OKF) is a vendor-neutral standard for representing knowledge as a directory of markdown files with YAML frontmatter. It standardizes how knowledge is written down so a wiki produced by one tool can be consumed by another without translation.

OKF is deliberately minimal. Its spec requires exactly one frontmatter field (type), recommends a few more (title, description, resource, tags, timestamp), and mandates that consumers preserve unknown keys and never reject a document for extra fields, unknown types, or broken links. And it explicitly leaves several things undefined - most importantly, freshness: OKF has no notion of “has the thing this describes changed?”, no verification status, no anchoring to code, no drift detection.

That gap is exactly what Surface fills. The payoff lands hardest with agents, which read your docs on every run: OKF makes the docs portable enough to reach every agent, Surface keeps them fresh enough to trust, and portable-plus-fresh docs measurably improve how well those agents perform.

Surface = OKF + freshness

Section titled “Surface = OKF + freshness”

A Surface hub is a conformant OKF concept. Surface adds the freshness layer OKF omits.

Because OKF ignores keys it doesn’t recognize, Surface’s governance metadata rides along inside an otherwise-normal OKF concept:

---
type: BigQuery Table          # OKF: the one required field
title: Orders                 # OKF: display name
description: One row per order # OKF: preserved (Surface keeps it in `extra`)
tags: [sales, revenue]        # OKF
timestamp: 2026-05-28T14:30:00Z  # OKF: last *modified*
anchors:                      # Surface extension - OKF readers ignore it
  - claim: an order is immutable once `status = shipped`
    at: src/orders/model.ts > Order > freeze
    hash: 2:9b1c33ade8f1
    id: c_18be…                 # stable identity (claim timelines)
    verified_at: 2026-06-30T09:12:00Z   # last *attested* against the code
    verified_commit: 4d5e6f2            # who is recovered from git blame, not stored
---


# Orders


Prose a human or agent reads to understand this table…
  • An OKF consumer - Google’s Knowledge Catalog, the OKF visualizer, Nansidian, Obsidian - reads this as a normal concept and silently ignores anchors.
  • Surface reads anchors and governs freshness: when src/orders/model.ts > Order > freeze changes, surf check fails until a human re-confirms the claim.
  • The two timestamps are different on purpose: OKF’s timestamp is last modified; Surface’s per-claim verified_at is last attested against the code - the freshness OKF can’t express.

What conformance means here

Section titled “What conformance means here”

A hub is a conformant OKF concept when it carries a type. Surface makes this cheap:

  • surf new scaffolds hubs with type: concept already set.
  • Hubs written before OKF (no type) still parse - Surface treats a missing type as concept in memory. They are byte-unchanged on disk; run a future surf migrate (or add type: by hand) to make them OKF-conformant on disk.
  • Any extra frontmatter key (OKF’s description/resource, a doc system’s author/created/ pinned) is preserved verbatim on round-trip - Surface never drops what it doesn’t recognize.

The one boundary worth stating plainly:

Surface only fact-checks concepts that describe code. A concept anchored to a code symbol is governed. A concept with no anchors (a BigQuery table’s business meaning, an RFC, a playbook) is a valid, rendered, ungoverned OKF concept - it passes the gate untouched. Verifying non-code resources (e.g. a table’s schema against the live warehouse) is future work; today the deterministic gate is scoped to code.

Bundles

Section titled “Bundles”

OKF ships knowledge as a bundle: a directory tree where each file is a concept, the path is its identity, and two filenames are reserved - index.md (a directory listing for progressive disclosure) and log.md (a change history). Point Surface at a bundle with bundles in surf.toml:

# Govern a flat hubs/ dir, an in-repo OKF bundle, or both.
hubs    = ["hubs/*.md"]
bundles = ["knowledge/sales"]   # expands to knowledge/sales/**/*.md

Reserved files are recognized and skipped for governance (they hold no claims), so a bundle’s index.md/log.md never trip the gate. surf lint additionally checks OKF cross-links in a hub’s body and warns (never blocks - OKF tolerates broken links) on a dangling .md target.

Doc systems

Section titled “Doc systems”

Because an OKF bundle is just markdown in a directory, it drops into any doc system that reads markdown - Obsidian vaults, Notion imports, and git-backed editors. The intended integration is a CI gate on the git repos those systems sync: run surf check as a GitHub Action over the doc repo, so the freshness gate guards the code-anchored subset of the knowledge base wherever the docs are edited.

See also

Section titled “See also”
  • Authoring hubs - a hub is an onboarding doc, not a claim-log (the same shape OKF’s prose-first concepts encourage).
  • Configuration - the bundles glob and frontmatter fields.
  • How the gate works - what Surface hashes and why.