okf-schema 0.2.0

CLI tool and Python library for working with OKF (Open Knowledge Format) bundles

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.

[!IMPORTANT] OKF-schema is opinionated. It delivers a valid OKF bundle but is adds a structure on the frontmatter that is not allowed in OKF specification:

Type values are **not** registered centrally. Producers SHOULD pick
values that are descriptive and self-explanatory; consumers MUST
tolerate unknown types gracefully (typically by treating them as
generic concepts).

In a strict OKF bundle, the type field is mandatory but can take any value and the validator needs to allow any field in the frontmatter.

OKF-schema requires the type to be one of the registered types in the _schema/ directory and validates the frontmatter against the corresponding schema. Additional properties may or may not be allowed depending on the schema definition.

What okf-schema adds to OKF

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

Capability	What it does
Schema-driven frontmatter validation	Every concept's YAML frontmatter is checked against a JSONSchema. Invalid fields, missing required keys, or wrong types are reported as structured errors.
Auto-discovered schemas	Schemas live inside the bundle under _schema/ (e.g. _schema/concept.schema.yaml). The type field in a concept's frontmatter tells okf-schema which schema file to load. A concept with type: concept is validated against _schema/concept.schema.yaml. Schemas can be written in YAML, JSON, or JSON5 (JSON with comments and trailing commas).
Bundle integrity checks	Detects broken internal links, missing index.md files, malformed log.md entries, and reserved-file violations.
Safe linting	Normalizes YAML frontmatter by flattening nested lists and converting block-style to inline notation while preserving comments and custom quotes via ruamel.yaml.
Analytics	Bundle statistics.

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)

Installation

uv tool install okf-schema

Quickstart

# 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 and convert block-style to inline)
okf-schema lint --path my-bundle/bundle

# Validate a bundle
okf-schema validate --path my-bundle/bundle
# or enforce strict validation (fail on warnings)
okf-schema validate --path my-bundle/bundle --strict

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

CLI Reference

Subcommand	Description
init <name>	Create a new OKF bundle directory structure
new --path <dir> --name <name>	Create a new concept file with frontmatter template
validate --path <bundle>	Validate bundle structure and frontmatter
validate --path <bundle> --strict	Validate and fail on warnings
lint --path <bundle>	Lint frontmatter: flatten nested lists and convert block-style to inline
list --path <bundle>	List all concepts in a bundle
show --path <bundle> <concept>	Show a single concept's frontmatter and body
index --path <bundle>	Regenerate all index.md files
stats --path <bundle>	Show bundle statistics

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 and convert block lists to inline
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:

Extension	Format	Notes
.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

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_-]+$" },
  },
}

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: [e-mail]
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

Python API

from okf_schema.api import validate_bundle

report = validate_bundle("path/to/bundle")
for finding in report.findings:
    print(finding.level, finding.message)

# 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")

Documentation

Full documentation is available at https://okf-schema.readthedocs.io.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License — see LICENSE for details.