Open Knowledge Format

Open Knowledge Format (OKF)

Open Knowledge Format (OKF) is an open, human- and agent-friendly format for representing knowledge: the metadata, context, and curated insight that surrounds data and systems. It is designed to be authored by people, generated by agents, exchanged across organizations, and consumed by both. ^[raw/articles/google-okf-spec-v02.md] The format is intentionally minimal: a directory of markdown files with YAML frontmatter. There is no schema registry, no central authority, and no required tooling.

Core Structure

An OKF knowledge unit consists of:

1. YAML frontmatter: type is required. The v0.1 draft recommends title, description, resource, tags, and timestamp.
2. Markdown body: the main explanatory content, which may include:
   • Sections with hierarchical headings
   • Links to related knowledge units
   • Attribution to source materials
   • Additional metadata as needed

The concept ID is the file path within the bundle without its .md suffix. The v0.1 draft represents cross-links as relative Markdown paths, rather than prescribing this vault’s Obsidian-style wikilinks.

v0.2 Structure (confidence: high, captured 2026-07-31)

The v0.2 spec supersedes v0.1 with a minor version bump. The two breaking changes (see §13.1) are: timestamp is superseded by generated.at; the body # Citations list is superseded by the sources frontmatter field.

The v0.2 frontmatter adds three frontmatter families that are optional but make agent-maintained corpora trustable:

Family	Fields	Purpose
Provenance (sources)	id, resource (required), title, author, usage_count, last_modified, usage_window	Where the concept was derived from; credibility signals (author, usage_count, last_modified) are recorded, not inferred
Trust (generated, verified)	by (actor convention), at (ISO 8601); trust tiers derived from verified	How the content was produced; who confirmed it
Lifecycle (status, stale_after)	draft / stable / deprecated; absolute staleness date	Whether the concept is current

The actor convention uses <producer>/<version> for agents/tools, human:<id> for people, and process:<id> for automated processes. Trust tiers are derived: no verified → unverified; verified only by non-human → machine-confirmed; verified by a human: actor → human-reviewed.

v0.2 per-claim attribution uses markdown footnotes keyed to sources[].id (stable keys that survive reordering), not positional [sources[0]] indexing:

The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]
 
[^ga4-schema]: GA4 BigQuery Export schema

v0.2 sources as an object list (confidence: high)

This is the key difference from this vault’s current sources: [raw/path.md] string-list form. In v0.2, sources is a list of objects, each with:

• resource (required) — an absolute URL, a bundle-relative path (begins with /), or a relative path
• id — optional stable key for per-claim footnote attribution
• title — optional human-readable label
• author — optional, actor convention (§7)
• usage_count — optional, how often the resource was exercised
• last_modified — optional, YYYY-MM-DD when the source last changed
• usage_window — optional { from, to } to frame every usage_count

Confidence signals are inferred from these per-source fields, never stored as a score.

Implications

Adopting the sources[] object form would let this vault distinguish “internal synthesis” from “external evidence” with precision, carry freshness signals (last_modified, usage_count), and support per-claim attribution via keyed footnotes. The migration is vault-wide (frontmatter + lint + MCP parser) — see docs/plans/external-linking-features-plan.md for the deferred migration path.

Required vs Recommended Fields

According to the captured v0.1 draft:

• Required: type
• Recommended: title, description, resource, tags, and timestamp
• Consumer tolerance: consumers must not reject a bundle for missing optional fields, unknown type values or additional keys, broken cross-links, or a missing index.md.

According to the v0.2 spec (captured 2026-07-31):

• Required: type (the only always-required key; a concept carrying just type is fully conformant)
• Recommended: title, description, resource (URI naming the underlying asset), tags
• Optional families: sources (provenance), generated/verified (trust), status/stale_after (lifecycle), and computation fields for type: Attested Computation
• Consumer tolerance (unchanged from v0.1): consumers must NOT reject a bundle for missing optional frontmatter fields, unknown type values, unknown additional keys, or broken cross-links. This is a baseline for interop, not a prohibition on stricter local governance.

These are interoperability rules for OKF consumers, not a prohibition on a particular vault applying stricter local quality rules. ^[raw/articles/google-okf-spec.md]

Role in LLM Wiki Systems

In an LLM Wiki implementation like the Synaptic Lattice vault:

1. Standardization: Ensures all knowledge units follow the same structure, making automated processing possible
2. Interoperability: Allows different LLM agents (Claude Code, Codex, Gemini CLI, etc.) to read and write to the same knowledge base
3. Tooling Enablement: Facilitates the development of linters, query engines, and visualization tools that can rely on consistent metadata
4. Atomic Updates: Each knowledge unit is a self-contained file that can be individually processed, versioned, and referenced

Implementation in this Vault

All wiki pages in this repository follow local governance aligned with the format’s Markdown-and-frontmatter approach:

• Every .md file in wiki/ begins with a YAML frontmatter block
• The type field distinguishes between concepts, entities, and comparisons
• tags include the page category and domain-specific labels such as llm-wiki, okf, and rag
• created and updated timestamps track the lifecycle of each knowledge unit
• The sources field (a custom extension) lists the raw source files that contributed to this knowledge unit

The vault’s requirements for frontmatter completeness, provenance, and healthy links are local governance enforced through lint. They are deliberately stricter than the format’s consumer-tolerance rules. ingest records the provenance when it writes or extends a page, while index.md remains the optional catalog rather than the ingest operation. ^[raw/articles/google-okf-spec.md]

Benefits of Adopting OKF

1. Consistency: Eliminates ad-hoc formatting that makes automated processing difficult
2. Future-Proofing: Aligns with an emerging standard that may enable integration with broader knowledge ecosystems
3. Collaboration Ready: Provides a clear contract for multiple agents or humans contributing to the same knowledge base
4. Machine-Readability: Enables automated tools to extract statistics, generate visualizations, or validate structural integrity

Comparison with Alternatives

Compared to alternatives like:

• Plain Markdown without frontmatter: Lacks structured metadata for automated processing
• JSON/YAML-only formats: Loses the human-readability and rich formatting capabilities of Markdown
• Proprietary schemas: Creates lock-in and limits tooling compatibility

OKF strikes a balance by providing essential structure while preserving the flexibility and accessibility of Markdown.

Evolution of the Specification

The captured specification is a v0.1 draft from a Google Cloud Platform source URL. It presents the L0-L3 lifecycle profiles as an atomicstrata extension, not as a universal core-OKF requirement.

On 2026-07-31, the v0.2 spec was captured from the same URL. The v0.2 version is a minor version bump that makes provenance, trust, and lifecycle first-class frontmatter families (§5), adds a formal references/ convention (§6.3), the actor convention (§7), an Attested Computation concept type (§10), and a conformance section (§11). The two breaking changes are timestamp → generated.at and body # Citations → frontmatter sources.

As the format evolves, this vault can add newly standardized optional fields, adjust lint validation rules, and maintain backward compatibility with existing entries. These are local maintenance choices made while preserving the draft’s consumer-tolerance baseline.

TrueHOOHA’s OKF Interpretation (confidence: medium)

TrueHOOHA/LLM-Wiki-Skilled adopts OKF with specific producer conventions layered on top:

• resource field: instead of a sources array, TrueHOOHA uses a single resource URI field in frontmatter to point at the raw asset. Abstracts concepts omit it.
• aliases field: a YAML list of alternative names used for wikilink resolution — a wikilink resolves to a kebab-case filename if the target matches an aliases entry on the target page. This is a producer extension permitted by OKF §4.1.
• timestamp instead of updated: ISO 8601 date of last meaningful change, replacing the legacy updated field.
• SPEC.md as conformance anchor: the project ships a formal SPEC.md declaring okf_version: "0.1" and documenting which OKF rules it follows and which it extends. This is an explicit conformance declaration that our vault’s SPEC.md implies but does not formalize.
• Obsidian-first deviation from OKF §5: TrueHOOHA explicitly documents its deviation from OKF’s standard-markdown-link recommendation, choosing Obsidian wikilinks for internal links. This is the same choice our vault makes, but TrueHOOHA declares it as a documented exception rather than a silent convention.

These conventions represent the most detailed public OKF producer profile in the ecosystem.

Source Conflict: “Google OKF”

The direct corpus source is an Open Knowledge Format v0.1 draft captured from a Google Cloud Platform URL. In contrast, the later deep-research report says that its public-search context did not establish “Google OKF” as a stable term and treated the casual phrase as ambiguous, potentially confused with Open Knowledge Foundation or OKR. Both records are retained: the report documents ambiguity in that search context, while the direct specification documents this specific OKF draft. This page does not treat either statement as evidence that every use of the phrase refers to the same thing. ^[raw/articles/google-okf-spec.md]

The previously cited report that was meant to establish a sharper community-to-standard timeline is not present in the current evidence layer. That chronology is therefore not treated as evidence here; the direct specification and the ambiguity report remain the authoritative records for this page.

External Linking Alignment (new, 2026-07-31)

The OKF v0.2 sources[].resource field directly addresses the vault’s external-linking gap. ^[raw/articles/google-okf-spec-v02.md] The plan at docs/plans/external-linking-features-plan.md proposes: (1) capturing external URLs into immutable raw/.external-snapshots/ files with resource: pointing at the original URL; (2) tracking external links in wiki/ pages via a wiki/.external-links/ ledger; (3) a freshness checker that reports HTTP status + content-hash drift per URL. The v0.2 last_modified and usage_count credibility signals are the model for the ledger’s freshness fields.

SPEC v0.2 Canônica (fonte oficial Google Cloud Platform, 2026-08-07)

Em 2026-08-07 capturamos a SPEC v0.2 direto do repositório GoogleCloudPlatform/knowledge-catalog (okf/SPEC.md), a fonte canônica GCP (snapshot: raw/external/raw-githubusercontent-com-spec-md-5a3311d2.md, HTTP 200). Esta captura resolve a dúvida de hospedagem registrada na seção “Source Conflict”: OKF v0.2 é publicada oficialmente pelo Google Cloud Platform num repo público.

Seções que a página ainda não detalhava:

• §8 Index files: index.md pode existir em qualquer diretório (bundle root inclusive) para progressive disclosure; sem frontmatter, exceto um okf_version opcional no root. Entries listam títulos+descrição.
• §9 Log files: log.md em qualquer nível, lista plana de entradas agrupadas por data ISO 8601 (newest-first), com palavras-chave convencionais (**Update**, **Creation**).
• §10 Attested Computations: um conceito type: Attested Computation é um conceito standalone — o runtime define o significado de parameters; executor (como roda) + attester (verificação determinística) + receipt (campos de evidência). Trust é per-computation. Exemplo de caso real no Apêndice A (income statement: v0.1 monólito vs v0.2 split em duas computations).
• §12 Versioning: <major>.<minor>; minor é aditivo (novos opcionais), major pode quebrar. Bundle pode declarar okf_version no index raiz. Considered/deferred: protocolo runtime completo, attester ABI, caching de attestation, templates semânticos.
• §13 Changes from v0.1: os 2 breaking changes confirmados — timestamp → generated.at e # Citations → frontmatter sources.

Implicação local: a forma index.md (progressive disclosure + okf_version) e log.md (newest-first, ISO 8601) do OKF batem com as declarações de catalog/log do wiki-scopes.json deste vault — o manifest já implementa o desenho §8/§9 do OKF.

Related

• docs/plans/external-linking-features-plan.md — implementation plan for external URL capture and freshness checking
• llm-wiki — the artifact-first pattern that the draft relates to its operations.
• ingest — the source-writing operation defined by the draft.
• query — the retrieval and synthesis operation defined by the draft.
• lint — local governance that checks a stricter vault than the consumer baseline.

Sources

^[raw/articles/google-okf-spec.md] ^[raw/articles/google-okf-spec-v02.md] ^[raw/articles/karpathy-llm-wiki-gist.md] ^[raw/articles/genai-unplugged-llm-wiki.md] ^[raw/articles/levelup-llm-wiki-deep-dive.md] ^[raw/articles/venturebeat-llm-wiki.md] ^[raw/transcripts/sozai-fable-llm-wiki-video.md]