OKF Guide

Template library

Copy-ready OKF templates

Use these templates to create a first Open Knowledge Format document. The examples follow a stricter guide profile than the draft specification so the files are easier to search and preview.

Before you copy a template

Replace placeholder resources, timestamps, and tags before publishing. If a concept is internal and has no URL, use a stable URN or internal identifier instead of a fake public link.

Keep one concept per file. A short, precise OKF file is easier for an agent to load than a broad document that mixes unrelated ideas.

Template

Website OKF template

Use this when you want search pages, help pages, pricing pages, or landing pages to become a structured knowledge bundle.

Field notes

  • `type` identifies this as a website page concept.
  • `resource` points to the live URL the knowledge describes.
  • `tags` group this page with other website and conversion documents.

Common mistakes

  • Using promotional copy instead of stable facts.
  • Leaving out pricing exclusions that an agent needs for accurate answers.
  • Pointing `resource` to the home page when the concept is about a specific URL.

Recommended next step

Create one OKF file per important public URL, then add an index file for the section.

Website OKF template 
---
type: Website Page
title: Pricing Page
description: Explains plan tiers, billing limits, refund policy, and upgrade paths.
resource: https://openknowledgeformat.online/sample/pricing/
tags: [website, pricing, conversion]
timestamp: 2026-06-17T00:00:00Z
---

# Audience

Describe who should read this page and what decision it supports.

# Key facts

- List the offer, limits, exclusions, and trust statements.
- Link to related OKF documents for product, support, and legal context.

# Citations

[1] Source page or internal owner record.

Template

API OKF template

Use this for REST, GraphQL, or webhook endpoints that agents need to call, explain, or troubleshoot.

Field notes

  • `type` tells consumers this document describes an endpoint.
  • `title` should match the business action, not only the URL.
  • `resource` can be the endpoint URL or canonical API reference URL.

Common mistakes

  • Documenting only the happy path.
  • Omitting authentication, rate limits, and error responses.
  • Mixing multiple endpoints into one concept file.

Recommended next step

Add one companion OKF file for shared authentication and one for common error codes.

API OKF template 
---
type: API Endpoint
title: Create customer endpoint
description: Creates a customer record and returns the new customer identifier.
resource: https://openknowledgeformat.online/sample-api/v1/customers
tags: [api, customers, write]
timestamp: 2026-06-17T00:00:00Z
---

# Method

POST /v1/customers

# Request fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| email | string | yes | Must be unique. |

# Response

Return the created customer id and status.

Template

SaaS OKF template

Use this for product concepts such as accounts, workspaces, roles, billing limits, or feature gates.

Field notes

  • `type` can be a precise business concept label.
  • `description` should be one sentence so search snippets stay clean.
  • `tags` connect the concept to billing, workspace, and support topics.

Common mistakes

  • Using internal jargon without a plain definition.
  • Skipping edge cases such as suspended users or pending invites.
  • Failing to link to plan limits and support playbooks.

Recommended next step

Build a concept map for the main product objects and support workflows.

SaaS OKF template 
---
type: SaaS Product Concept
title: Workspace seats
description: Defines how seats are counted, invited, removed, and billed.
resource: https://openknowledgeformat.online/sample/docs/workspace-seats
tags: [saas, billing, workspace]
timestamp: 2026-06-17T00:00:00Z
---

# Definition

A seat is counted when a user has active access to a paid workspace.

# Rules

- Pending invites do not count until accepted.
- Suspended users stop counting at the next billing sync.

# Related concepts

See [Billing plans](/billing/plans.md).

Template

Documentation OKF template

Use this when developer docs or product docs need a machine-readable summary next to human instructions.

Field notes

  • `title` mirrors the documentation task.
  • `description` summarizes the user goal and main steps.
  • `timestamp` records the last meaningful update.

Common mistakes

  • Turning a long page into one giant OKF document.
  • Missing prerequisites, permissions, or rollback notes.
  • Not linking related troubleshooting topics.

Recommended next step

Split large docs into one OKF document per task, concept, or reference topic.

Documentation OKF template 
---
type: Documentation Topic
title: Import contacts from CSV
description: Guides admins through CSV preparation, upload, validation, and rollback.
resource: https://openknowledgeformat.online/sample/docs/import-csv
tags: [docs, import, csv]
timestamp: 2026-06-17T00:00:00Z
---

# Prerequisites

- Admin role.
- UTF-8 CSV file.
- Required columns: email, first_name, last_name.

# Procedure

1. Open Admin Settings.
2. Upload the CSV file.
3. Review validation warnings before confirming.

# Rollback

Export the affected contacts and remove the imported batch if needed.

Template

AI Agent Context OKF template

Use this to package policies, routing rules, tool boundaries, and escalation notes for an agent.

Field notes

  • `resource` can be a stable URN when no public URL exists.
  • `type` marks this as context, not a customer-facing page.
  • `tags` help route this context into the correct agent workflow.

Common mistakes

  • Mixing policy, tool secrets, and user data in one file.
  • Writing instructions that conflict with the product policy.
  • Forgetting escalation conditions.

Recommended next step

Review the file with support owners before adding it to an agent context bundle.

AI Agent Context OKF template 
---
type: Agent Context
title: Refund support routing
description: Tells the support agent when to answer, when to request proof, and when to escalate refund cases.
resource: urn:agent-context:refund-support-routing
tags: [agent, support, refunds]
timestamp: 2026-06-17T00:00:00Z
---

# Scope

The agent may explain the refund policy and collect order details.

# Boundaries

- Do not promise refunds before eligibility is checked.
- Escalate orders older than 90 days.

# Tool notes

Use the order lookup tool only after the user provides an order id.

Template

Data Catalog OKF template

Use this for tables, datasets, metrics, dashboards, or lineage notes that need human and agent review.

Field notes

  • `resource` should identify the table, dashboard, or metric asset.
  • `description` should state grain and purpose.
  • `tags` support cross-cutting search by domain or metric group.

Common mistakes

  • Leaving out data grain.
  • Not documenting freshness or ownership.
  • Using vague column descriptions that repeat the column name.

Recommended next step

Add related metric, dashboard, and playbook OKF files, then link them together.

Data Catalog OKF template 
---
type: Data Table
title: Orders fact table
description: One row per submitted order with revenue, customer, and fulfillment fields.
resource: bigquery://acme.analytics.orders
tags: [data, orders, revenue]
timestamp: 2026-06-17T00:00:00Z
---

# Schema

| Column | Type | Description |
| --- | --- | --- |
| order_id | string | Unique order id. |
| customer_id | string | Customer identifier. |
| total_usd | numeric | Order total in US dollars. |

# Freshness

Updated hourly from the commerce ingestion pipeline.

Source boundary

This guide is unofficial. It uses public draft references for orientation and adds practical examples for learning.