OKF vs OpenAPI

OKF vs OpenAPI in one table

Use OpenAPI when you need to describe an API contract. Use OKF when you need to package the surrounding knowledge that helps people and AI agents understand why an endpoint exists, how it is used, what the edge cases are, and where the source documentation lives.

Where OpenAPI is stronger

OpenAPI is a specification for describing HTTP APIs. It can define paths, methods, parameters, request bodies, response shapes, status codes, authentication, examples, and other contract-level details used by documentation and developer tooling.

Where OKF is different

Open Knowledge Format is a Markdown-and-frontmatter approach for packaging knowledge files. An OKF file can describe an API endpoint in plain language, link to its OpenAPI reference, explain support boundaries, and add review notes that do not belong inside the contract itself.

Key differences

• OpenAPI is contract-first; OKF is context-first.
• OpenAPI is strong at schema and endpoint structure; OKF is strong at readable explanations and source boundaries.
• OpenAPI powers developer tooling; OKF can feed documentation, support, retrieval, and agent context workflows.
• OpenAPI should remain the source of truth for endpoint shape; OKF should point back to that source instead of duplicating it blindly.

When to use OpenAPI

• You need an API contract that developers and tools can rely on.
• You need generated reference docs, client SDKs, mocks, or tests.
• You need precise request and response schemas.
• You need endpoint-level details that must stay aligned with implementation.

When to use OKF

• You need plain-language context around an endpoint, not just the schema.
• You need support, docs, or agent workflows to understand endpoint purpose and boundaries.
• You need to link examples, known limits, owner notes, troubleshooting, and related docs.
• You want reviewed Markdown files that can live next to docs or in a static knowledge bundle.

When to use both

Yes. A practical pattern is to keep OpenAPI as the canonical contract and create OKF files that reference important endpoints. The OKF file should explain business purpose, common mistakes, support boundaries, and related documentation without pretending to replace the API contract.

Convert API context without replacing OpenAPI

• Choose one important endpoint from the OpenAPI file.
• Create one OKF file with type API Endpoint.
• Set resource to the canonical API reference URL or stable endpoint identifier.
• Add human-readable purpose, request notes, common errors, owner notes, and related docs.
• Validate the OKF file with the OKF Validator.
• Use the OpenAPI to OKF guide before expanding a full API context bundle.
• Review the file when the OpenAPI contract changes.

---
type: API Endpoint
title: Create customer endpoint
description: Explains endpoint purpose, required inputs, common errors, and support notes.
resource: https://openknowledgeformat.online/sample-api/v1/customers
tags: [api, openapi, customers]
timestamp: 2026-06-21T00:00:00Z
---

# Create customer endpoint

This OKF file explains the business context around the OpenAPI contract.

## Source contract

Use the canonical OpenAPI reference as the source of truth for schema details.

## Common errors

- Missing email
- Duplicate customer
- Invalid workspace permissions

Related pages

• OKF vs RAG for retrieval context.
• OKF vs MCP for tool and context boundaries.
• OpenAPI to OKF for the conversion workflow.
• OKF Templates for copy-ready starters.
• OKF Examples for bundle patterns.
• OKF Validator for checking frontmatter.

FAQ