okf-schema

okf-schema is a CLI tool and Python library for working with OKF (Open Knowledge Format) bundles with JSONSchema validation of the frontmatter metadata, and formatting capabilities while preserving comments.

OKF is a markdown-based knowledge format where each concept is a markdown file with YAML frontmatter. See the OKF specification for the full format definition.

📚 Full documentation: okf-schema.readthedocs.io

Three layers: generic okf-schema, okfkb, and okfreq

The package has one generic foundation and two separate opinionated subsets:

okfkb and okfreq are not aliases and should not be mixed in one bundle: okfkb manages knowledge maturity, while okfreq manages requirements and their implementation evidence. Both subsets reuse the generic okf-schema mechanics underneath. A project can use only generic OKF, either subset, or both in separate bundles.

What okf-schema adds to OKF

Plain OKF defines a folder of markdown files. okf-schema turns those files into a validated, searchable knowledge bundle by adding:

See a real schema definition in examples/ai-llm-knowledge-base/_schema/concept.schema.yaml.

Example of structure

my-bundle/
├── _schema/
│   ├── concept.schema.yaml
│   ├── tool.schema.json
│   └── paper.schema.json5
├── concepts/
│   ├── rag.md
│   └── chain-of-thought.md
├── tools/
│   ├── langchain.md
│   └── llamaindex.md
├── papers/
│   ├── rag-paper.md
│   └── chain-of-thought-paper.md
├── index.md
└── log.md

The type field in each entity frontmatter determines which schema is used for validation. For example, type: concept uses _schema/concept.schema.yaml, while type: tool uses _schema/tool.schema.json.

Schema extensions supported:

• .schema.yaml — YAML (human-friendly, supports comments and anchors)
• .schema.json — JSON (strict syntax, widely supported by editors)
• .schema.json5 — JSON5 (JSON with comments, trailing commas, and unquoted keys)

For detailed information on $ref support and schema composition, see the full documentation.

Installation

Use UV to install this tool, or to use in your skill:

uv tool install okf-schema

This installs the okf-schema, okfkb (Knowledge base), and okfreq (Requirements) commands.

Use Cases

The package serves three distinct use cases:

• Use Case 1 — Generic OKF: Build, maintain, and validate OKF bundles with JSON Schema.
• Use Case 2 — okfkb: Maintain an opinionated knowledge base for empirical findings, hypotheses, and concepts.
• Use Case 3 — okfreq: Manage and trace software requirements, linking them to implementation and test evidence.
• Use Case 4 — Standalone Markdown: Validate individual Markdown files against JSON Schemas without a full bundle.

okfreq and okfkb are separate subsets documented alongside the generic workflow.

Use Case 1: Build, Maintain & Validate OKF Bundles

Create and manage complete OKF bundles with folder structure, schemas, index files, and integrity checks.

Quick Start:

# Initialize a new OKF bundle
okf-schema init my-bundle

# Update index.md files for all directories
okf-schema index --path my-bundle/bundle

# Lint frontmatter (flatten nested lists, inline block-style, auto-update links/backlinks)
okf-schema lint --path my-bundle/bundle

# Validate bundle structure and frontmatter
okf-schema validate --path my-bundle/bundle --strict

# List all concepts
okf-schema list --path my-bundle/bundle

# Find backlinks to a concept
okf-schema backlinks --path my-bundle/bundle concepts/react-pattern

More information in the documentation: OKF-Schema CLI.

Use Case 2: Knowledge-base subset (okfkb)

Record empirical findings, hypotheses, and concepts using a stratified knowledge model with structured types and validation.

Quick Start:

# Initialize a new KB bundle
okfkb init my-knowledge-base

# Record a finding
okfkb new-finding my-knowledge-base \
  --title "AI agents improve coding speed" \
  --confidence confirmed

# Navigate the KB (agent-native memory tools)
okfkb search "cache eviction" my-knowledge-base --tier findings
okfkb get findings/2026.07.04-14.30-... my-knowledge-base
okfkb read concepts my-knowledge-base
okfkb query "type:finding confidence:>=high tag:cache" my-knowledge-base
okfkb query "finding[tag=cache] -> concept -> principle" my-knowledge-base

For full KB documentation, see the OKFKB CLI, OKF-KB Design Choices and HW Debugging Workflow Tutorial.

Agent skills complement the CLI: okf-schema handles tool mechanics, okfkb teaches and routes the knowledge lifecycle, and okfkb-gardening runs explicit, autonomous KB maintenance. See Agent Skills and Maintain an OKFKB with agent skills.

Use Case 3: Requirements subset (okfreq)

okfreq is an independent, requirements-focused layer built on the same generic OKF mechanics. It is intended for requirements repositories, not for the okfkb knowledge tiers. It provides:

• separate StRS stakeholder and SwRS software-requirement layers;
• stable requirement IDs and explicit lifecycle states;
• authored derives_from relationships with generated reverse links;
• @implements_req and @tests_req markers for implementation and test traceability; and
• validation, coverage, graph, report, archive, and supersession commands.

Initialize and validate a requirements bundle with:

okfreq init my-requirements
okfreq new strs "Export report" \
  --description "When export is requested, the reporting capability SHALL make a portable report available." \
  --user-need "Users need a portable report for offline review." \
  --project demo
okfreq validate my-requirements
okfreq trace my-requirements

See the okfreq requirements tutorial, the okfreq design choices, and the skill scope guide for the distinction between generic OKF, okfkb, and okfreq. See the complete okfreq CLI reference for every command and option.

Use Case 4: Validate Standalone Markdown Files

Validate individual markdown files (or collections) against JSON schemas without needing a full OKF bundle.

Quick Start:

# Validate all markdown files in a directory
okf-schema validate-md \
  --input 'docs/**/*.md' \
  --schemas-dir ./schemas

# Validate multiple patterns with strict mode
okf-schema validate-md \
  --input '*.md' \
  --input 'docs/**/*.md' \
  --schemas-dir ./schemas \
  --strict

Key Commands:

For examples and troubleshooting, see the Standalone File Validation Guide and Validation Error & Warning Codes Reference.

Validation Reference

Recommended Workflow

Before packaging or distributing a bundle, run these three commands in order and fix all warnings:

okf-schema index --path my-bundle/bundle    # regenerate index.md files
okf-schema lint --path my-bundle/bundle     # flatten nested lists, inline block lists, update links/backlinks
okf-schema validate --path my-bundle/bundle --strict # check structure, schema, and links; fail on warnings

Only zip or ship the bundle once validate --strict reports zero errors and zero warnings. Warnings such as missing index.md (W4), block-style lists (W7), or broken cross-links (W2) signal issues that will degrade the experience for downstream consumers.

Example: AI & LLM Knowledge Base

The examples/ai-llm-knowledge-base/ directory contains a realistic knowledge base with three concept types — concept, tool, and paper — each validated by its own schema in _schema/.

How type selects the schema

The type field in a concept's frontmatter determines which schema file is loaded. A file with type: concept is validated against _schema/concept.schema.yaml; type: tool against _schema/tool.schema.json; and type: paper against _schema/paper.schema.json5.

Schema format support

okf-schema accepts schemas in three formats:

Schema highlights

concept.schema.yaml — AI concepts with enums, email validation, and kebab-case regex:

properties:
  category:
    enum: [LLM, AI Agent, Coding Agent, Prompt Engineering, Tooling, Evaluation]
  maturity:
    enum: [experimental, beta, production, deprecated]
  author_email:
    type: string
    format: email
  tags:
    type: array
    items:
      pattern: "^[a-z0-9-]+$"   # kebab-case only

tool.schema.json — Developer tools with URI validation and language enums:

{
  "properties": {
    "license": {
      "enum": ["MIT", "Apache-2.0", "GPL-3.0", "Proprietary", "Other"]
    },
    "language": {
      "enum": ["Python", "JavaScript", "TypeScript", "Rust", "Go", "Java", "Multi-language"]
    },
    "url": { "type": "string", "format": "uri" }
  }
}

paper.schema.json5 — Research papers with year bounds and venue enums:

// JSON5 allows comments, trailing commas, and unquoted keys
{
  properties: {
    year: { type: "integer", minimum: 1950, maximum: 2030 },
    venue: {
      enum: ["NeurIPS", "ICML", "ICLR", "ACL", "EMNLP", "arXiv", "Other"]
    },
    bibtex_key: { pattern: "^[A-Za-z0-9_-]+$" },
  },
}

Schema-aware index generation

Schemas can declare title, description, and an x-okf-summary extension field. When a subdirectory contains concepts of a single type, okf-schema index uses them to produce richer index.md files:

For example, concept.schema.yaml declares:

title: "Concept"
x-okf-summary: "AI/LLM concepts such as techniques, patterns, or architectural ideas."
description: "Schema for AI/LLM concepts ..."

Running okf-schema index turns this into:

• A root index.md entry: [concepts](./concepts/) — AI/LLM concepts such as...
• A subdirectory index.md with # Concept as the heading and the description as the first paragraph.

Concept file example (concepts/rag.md)

---
type: concept
title: Retrieval-Augmented Generation
description: >
  A technique that enhances LLM outputs by retrieving relevant documents
  from an external knowledge store and injecting them into the prompt.
category: LLM
maturity: production
author_email: bob@example.com
complexity: intermediate
tags: [rag, retrieval, llm, knowledge-base]
related_tools: [LangChain, LlamaIndex, OpenAI-API]
---

# Retrieval-Augmented Generation

RAG combines parametric knowledge (the model's weights) with non-parametric
knowledge (external documents) to reduce hallucinations...

Validation in action

# Validates all concepts, tools, and papers against their respective schemas
okf-schema validate --path examples/ai-llm-knowledge-base

# Show bundle statistics
okf-schema stats --path examples/ai-llm-knowledge-base

Opinionated Knowledge Base

okf-schema includes a dedicated knowledge-base subcommand group (okfkb) for managing OKF bundles designed for agent-facing experimental findings. A knowledge base is an opinionated OKF bundle with 9 content directories (concepts, experiments, findings, hypotheses, outcomes, playbooks, principles, reference, and structures) and 10 YAML schemas including the shared base schema.

# Scaffold a new knowledge base in the current directory
okfkb init my-kb

# Install KB skills and guidelines into a project
okfkb install-skills /path/to/project

# Alternatively, use the okf-schema init --pattern flag
okf-schema init my-kb --pattern kb

The okfkb binary is a standalone alias for okf-schema kb — both are equivalent.

Navigating the KB: search / get / read / query

Beyond authoring, okfkb exposes the KB as a small set of navigation tools so an agent can actively pull the right granularity instead of loading whole folders:

• search — coarse ranked retrieval across titles, context, tags, and body.
• get — exact fetch of one node by id/path (the drill-down after a search).
• read — read an entire stable tier at once (top-down entry, e.g. read principles).
• query — structured selection combining two styles:
  • Filter DSL (flat frontmatter): key:value / key:<operator>value, ANDed. Confidence is ordinal, so ranges work:

    okfkb query "type:finding confidence:>=high tag:pll status:active"
    

  • Arrow traversal (a pocket-Cypher over links and derivation edges): -> follows links, <- follows backlinks, and ^ follows computed derives_to edges:

    okfkb query "finding[tag=pll,confidence=high] ^ concept ^ principle"
    okfkb query "concept[title~boot] -> playbook"
    

For full KB documentation and commands, see the OKF Knowledge Base reference.

Python API

from okf_schema.api import validate_bundle

report = validate_bundle("path/to/bundle")
for finding in [*report.errors, *report.warnings]:
    print(finding.code, finding.message, finding.path)

# The _schema/ directory inside the bundle is auto-discovered.
# You can also pass an explicit schema_db path:
# report = validate_bundle("path/to/bundle", schema_db="path/to/schemas")

Agent Skills

The repository provides six complementary skills:

See skills/README.md for selection guidance and the recommended maintenance rhythm.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Known Alternative

Here is some alternative OKF tooling that may interest you as well:

• IWE: Full-featured, Rust-based OKF bundle manager. It does not provide schema validation, but provides querying, indexing, an MCP server, a VS Code extension, and more.

Tons of other resources just limit to apply OKF to LLM-Wiki (ex: okf-harness or openknowledge).

OKF-Schema is deliberately more opinionated, focused on frontmatter validation and preparing the bundle for direct agentic consumption (I do not plan to build a MCP server, I prepare my agent to read files directly). okfkb is even more opinionated, with a strict but ready-to-use knowledge base structure and schema.

License

MIT License — see LICENSE for details.