magnus919_agent-skills/open-knowledge-format/references/spec-summary.md

OKF v0.1 — Specification Summary

The full specification lives at GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md. This reference covers the key structural rules, conformance criteria, and design decisions.

Goals

1. Define a universal format that enrichment agents can write into
2. Inform how consumption agents should read and traverse it
3. Facilitate exchange of knowledge across systems and organizations
4. Standardize the small number of required fields for meaningful consumption

Non-goals

• Defining a fixed taxonomy of concept types
• Prescribing storage, serving, or query infrastructure
• Replacing domain-specific schemas (Avro, Protobuf, OpenAPI) — OKF references them, does not subsume them

Terminology

Term	Definition
Knowledge Bundle	Self-contained, hierarchical collection of knowledge documents. The unit of distribution.
Concept	A single unit of knowledge within a bundle. One markdown document.
Concept ID	The path of the concept's file within the bundle, with .md suffix removed. E.g. tables/users.md has ID tables/users.
Frontmatter	YAML metadata block delimited by --- at the top of a markdown file
Body	Everything in the file after the frontmatter
Link	Standard markdown link from one concept to another
Citation	A link from a concept to an external source supporting a claim

Bundle Structure Rules

bundle/
├── index.md           # Reserved — directory listing (optional)
├── log.md             # Reserved — update history (optional)
├── <concept>.md       # Any other .md file is a concept
└── <subdirectory>/
    ├── index.md
    └── …

Reserved filenames

Filename	Purpose
index.md	Directory listing. Optional. No frontmatter (except at bundle root for okf_version).
log.md	Update history. Optional. ISO 8601 date headings, newest first.

All other .md files are concept documents.

Frontmatter Specification

---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI>
tags: [<tag>, …]                   # Optional
timestamp: <ISO 8601 datetime>     # Optional
---

type field — REQUIRED

A short string identifying the kind of concept. Examples: BigQuery Table, BigQuery Dataset, API Endpoint, Metric, Playbook, Reference.

• Types are NOT registered centrally
• Producers SHOULD pick descriptive, self-explanatory values
• Consumers MUST tolerate unknown types gracefully (treat as generic concept)

Recommended fields (priority order)

1. title — Human-readable display name. If omitted, consumers may derive from filename
2. description — Single sentence summary. Used by index generators, search snippets, previews
3. resource — URI identifying the underlying asset. Absent for abstract ideas
4. tags — YAML list of short strings for cross-cutting categorization
5. timestamp — ISO 8601 datetime of last meaningful change

Extensions

Producers MAY include any additional keys. Consumers SHOULD preserve unknown keys on round-trip and SHOULD NOT reject unrecognized fields.

Conventional Body Sections

Heading	Purpose
# Schema	Structured column/field descriptions
# Examples	Usage examples, often fenced code blocks
# Citations	External sources backing claims

These are conventions, not requirements. Any markdown content is valid.

Cross-linking Rules

Two forms of links:

1. Absolute (bundle-relative): Start with /, interpreted relative to bundle root. Recommended form.
2. Relative: Standard markdown relative paths.

A link from concept A to concept B asserts a relationship. The specific kind (parent/child, references, joins-with, depends-on) is conveyed by surrounding prose, not by the link itself. Graph consumers treat all links as directed edges of an untyped relationship.

Consumers MUST tolerate broken links — a link whose target does not exist in the bundle is not malformed; it may represent not-yet-written knowledge.

Index Files (index.md)

May appear in any directory. Contains no frontmatter (except optionally at bundle root):

# Section Heading

* [Title 1](relative-url-1) - short description
* [Title 2](relative-url-2) - short description

Entries SHOULD include the description from the linked concept's frontmatter. Producers MAY generate index.md automatically; consumers MAY synthesize one on the fly.

Log Files (log.md)

Flat list of date-grouped entries, newest first:

## 2026-05-22
* **Update**: Added [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Playbook](/playbooks/dataplex.md).

Date headings MUST use ISO 8601 YYYY-MM-DD form. Leading bold word (**Update**, **Creation**, **Deprecation**) is a convention, not a requirement.

Citations

Sources listed under # Citations at the bottom of a document, numbered:

# Citations

[1] [Source title](https://...)
[2] [Source title](path/to/reference.md)

Citation links may be absolute URLs, bundle-relative paths, or paths into a references/ subdirectory.

Conformance Criteria

A bundle is conformant with OKF v0.1 if:

1. Every non-reserved .md file in the tree contains a parseable YAML frontmatter block
2. Every frontmatter block contains a non-empty type field
3. Every reserved filename follows its defined structure when present

Consumers MUST NOT reject a bundle because of:

• Missing optional frontmatter fields
• Unknown type values
• Unknown additional frontmatter keys
• Broken cross-links
• Missing index.md files

Versioning

Format: <major>.<minor>

• Minor bump: Backward-compatible additions (new optional fields, new conventional headings)
• Major bump: Breaking changes (renaming required fields, changing reserved filenames)

Bundles MAY declare their target version via okf_version: "0.1" in a bundle-root index.md frontmatter block (the only place frontmatter is permitted in index.md). Consumers that don't understand the declared version SHOULD attempt best-effort consumption.