What is front matter in open knowledge format

 Front matter is a block of metadata placed at the very top of a plain text file (typically Markdown). Delimited by triple dashes (---), it acts as machine-readable data that allows AI agents, search indexes, and static site generators to index, filter, and traverse knowledge without having to parse the main document body.

In the Open Knowledge Format (OKF)—the specification published by Google Cloud to package markdown knowledge bases into traversable graphs for AI agents—front matter is written in YAML format.

OKF Front Matter Structure

An OKF concept document requires a structured YAML block at the head of the file, followed by the Markdown body:

---
type: metric
title: Active Monthly Users
description: Count of unique authenticated users who performed at least one action in the last 30 days.
resource: bigquery://analytics_db.tables.user_events
tags:
  - analytics
  - user-growth
timestamp: 2026-06-12T00:00:00Z
status: active
---

Front Matter Fields Breakdown

The specification keeps front matter minimal and extensible. It makes a clear distinction between required, standard optional, and custom keys:

Field	Requirement	Purpose	Example
type	Required	Defines the category of the knowledge node (e.g., metric, table, runbook, policy, api).	type: metric
title	Recommended	Human-readable title of the concept node.	title: Revenue Definition
description	Recommended	Concise summary used by retrieval systems to gauge relevance.	description: Core calculation method...
resource	Optional	External URI mapping to an underlying dataset, API, or DB table.	resource: postgres://db/orders
tags	Optional	Categorization keywords for filtering.	tags: [finance, quarter-1]
timestamp	Optional	Provenance date for tracking currency and staleness.	timestamp: 2026-06-12
status	Optional	Indicates context validity (e.g., active, deprecated, draft).	status: active

Key Properties

• Extensibility: You can add custom key-value pairs (e.g., owner: "@data-team") without breaking OKF parsers; compliant tooling must tolerate unknown keys.
• Decoupled Relationships: While general metadata lives in the front matter, links to other concepts are expressed directly in the Markdown body using standard Markdown links ([Orders Table](/entities/orders.md)), forming a traversable knowledge graph.