{
  "markdown": "# okf-schema\n\n[![CI](https://github.com/gsemet/okf-schema/actions/workflows/ci.yml/badge.svg)](https://github.com/gsemet/okf-schema/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/codecov/c/github/gsemet/okf-schema)](https://codecov.io/gh/gsemet/okf-schema)\n[![PyPI](https://img.shields.io/pypi/v/okf-schema)](https://pypi.org/project/okf-schema/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/okf-schema)](https://pypi.org/project/okf-schema/)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Type checked](https://img.shields.io/badge/type%20checked-mypy%2Fty-blue.svg)](./)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://okf-schema.readthedocs.io/en/stable/)\n\n**okf-schema** is a CLI tool and Python library for working with **OKF (Open Knowledge Format)** bundles\nwith JSONSchema validation of the frontmatter metadata, and formatting capabilities while preserving comments.\n\nOKF is a markdown-based knowledge format where each concept is a markdown file with YAML frontmatter.\nSee the [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) for the full format definition.\n\n📚 **Full documentation**: [okf-schema.readthedocs.io](https://okf-schema.readthedocs.io/en/stable/)\n\n> [!IMPORTANT]\n> OKF-schema is opinionated. Generic OKF requires a non-empty `type` but does\n> not centrally register type values, and consumers should tolerate unknown\n> types. When a schema database is present, OKF-schema validates registered\n> types against their corresponding schemas. An unregistered type produces W6;\n> strict validation treats that warning as a failure. Additional frontmatter\n> properties are accepted or rejected according to the selected schema.\n\n## Three layers: generic `okf-schema`, `okfkb`, and `okfreq`\n\nThe package has one generic foundation and two separate opinionated subsets:\n\n| Layer | Scope | Command | What it provides |\n|-------|-------|---------|------------------|\n| **Generic `okf-schema`** | Any OKF bundle | `okf-schema` | Schema validation, frontmatter linting, indexing, links, bundle integrity, and the Python API. |\n| **Knowledge base `okfkb`** | Engineering knowledge | `okfkb` or `okf-schema kb` | A stratified lifecycle for immutable Findings, hypotheses, experiments, concepts, structures, principles, playbooks, and outcomes. |\n| **Requirements `okfreq`** | Stakeholder and software requirements | `okfreq` | Explicit requirement IDs, StRS/SwRS hierarchy, lifecycle, derivation, verification markers, coverage, and traceability. |\n\n`okfkb` and `okfreq` are not aliases and should not be mixed in one bundle:\n`okfkb` manages knowledge maturity, while `okfreq` manages requirements and\ntheir implementation evidence. Both subsets reuse the generic `okf-schema`\nmechanics underneath. A project can use only generic OKF, either subset, or\nboth in separate bundles.\n\n## What `okf-schema` adds to OKF\n\nPlain OKF defines a folder of markdown files. `okf-schema` turns those files into\na validated, searchable knowledge bundle by adding:\n\n| Capability | What it does |\n|-----------|--------------|\n| **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. |\n| **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). |\n| **Bundle integrity checks** | Detects broken internal links, missing `index.md` files, malformed `log.md` entries, and reserved-file violations. |\n| **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`. Also auto-updates `links` and `backlinks` fields from markdown body content. |\n| **Analytics** | Bundle statistics. |\n\nSee a real schema definition in [`examples/ai-llm-knowledge-base/_schema/concept.schema.yaml`](examples/ai-llm-knowledge-base/_schema/concept.schema.yaml).\n\nExample of structure\n\n```raw\nmy-bundle/\n├── _schema/\n│   ├── concept.schema.yaml\n│   ├── tool.schema.json\n│   └── paper.schema.json5\n├── concepts/\n│   ├── rag.md\n│   └── chain-of-thought.md\n├── tools/\n│   ├── langchain.md\n│   └── llamaindex.md\n├── papers/\n│   ├── rag-paper.md\n│   └── chain-of-thought-paper.md\n├── index.md\n└── log.md\n```\n\nThe `type` field in each entity frontmatter determines which schema is used for validation.\nFor example, `type: concept` uses `_schema/concept.schema.yaml`, while `type: tool` uses `_schema/tool.schema.json`.\n\nSchema extensions supported:\n\n- `.schema.yaml` — YAML (human-friendly, supports comments and anchors)\n- `.schema.json` — JSON (strict syntax, widely supported by editors)\n- `.schema.json5` — JSON5 (JSON with comments, trailing commas, and unquoted keys)\n\nFor detailed information on `$ref` support and schema composition, see the [full documentation](https://okf-schema.readthedocs.io/en/stable/).\n\n## Installation\n\nUse UV to install this tool, or to use in your skill:\n\n```bash\nuv tool install okf-schema\n```\n\nThis installs the `okf-schema`, `okfkb` (Knowledge base), and `okfreq` (Requirements) commands.\n\n## Use Cases\n\nThe package serves **three distinct use cases**:\n\n- **Use Case 1 — Generic OKF**: Build, maintain, and validate OKF bundles with JSON Schema.\n- **Use Case 2 — `okfkb`**: Maintain an opinionated knowledge base for empirical findings, hypotheses, and concepts.\n- **Use Case 3 — `okfreq`**: Manage and trace software requirements, linking them to implementation and test evidence.\n- **Use Case 4 — Standalone Markdown**: Validate individual Markdown files against JSON Schemas without a full bundle.\n\n`okfreq` and `okfkb` are separate subsets documented alongside the generic\nworkflow.\n\n### Use Case 1: Build, Maintain & Validate OKF Bundles\n\nCreate and manage complete OKF bundles with folder structure, schemas, index files, and integrity checks.\n\n**Quick Start:**\n\n```bash\n# Initialize a new OKF bundle\nokf-schema init my-bundle\n\n# Update index.md files for all directories\nokf-schema index --path my-bundle/bundle\n\n# Lint frontmatter (flatten nested lists, inline block-style, auto-update links/backlinks)\nokf-schema lint --path my-bundle/bundle\n\n# Validate bundle structure and frontmatter\nokf-schema validate --path my-bundle/bundle --strict\n\n# List all concepts\nokf-schema list --path my-bundle/bundle\n\n# Find backlinks to a concept\nokf-schema backlinks --path my-bundle/bundle concepts/react-pattern\n```\n\nMore information in the documentation: [OKF-Schema CLI](https://okf-schema.readthedocs.io/en/stable/reference/cli.html).\n\n### Use Case 2: Knowledge-base subset (`okfkb`)\n\nRecord empirical findings, hypotheses, and concepts using a stratified knowledge model with structured types and validation.\n\n![generic-vs-okfkb-kb](docs/source/_static/generic-vs-okfkb-kb.svg)\n\n**Quick Start:**\n\n```bash\n# Initialize a new KB bundle\nokfkb init my-knowledge-base\n\n# Record a finding\nokfkb new-finding my-knowledge-base \\\n  --title \"AI agents improve coding speed\" \\\n  --confidence confirmed\n\n# Navigate the KB (agent-native memory tools)\nokfkb search \"cache eviction\" my-knowledge-base --tier findings\nokfkb get findings/2026.07.04-14.30-... my-knowledge-base\nokfkb read concepts my-knowledge-base\nokfkb query \"type:finding confidence:>=high tag:cache\" my-knowledge-base\nokfkb query \"finding[tag=cache] -> concept -> principle\" my-knowledge-base\n```\n\n**For full KB documentation**, see the [OKFKB CLI](https://okf-schema.readthedocs.io/en/stable/reference/kb-commands.html), [OKF-KB Design Choices](https://okf-schema.readthedocs.io/en/stable/explanation/okfkb-choices.html) and [HW Debugging Workflow Tutorial](https://okf-schema.readthedocs.io/en/stable/tutorials/okfkb-hw-debugging-workflow.html).\n\n**Agent skills** complement the CLI: `okf-schema` handles tool mechanics,\n`okfkb` teaches and routes the knowledge lifecycle, and `okfkb-gardening` runs\nexplicit, autonomous KB maintenance. See [Agent Skills](skills/README.md) and\n[Maintain an OKFKB with agent skills](docs/source/how-to/maintain-okfkb-with-skills.md).\n\n### Use Case 3: Requirements subset (`okfreq`)\n\n`okfreq` is an independent, requirements-focused layer built on the same\ngeneric OKF mechanics. It is intended for requirements repositories, not for\nthe `okfkb` knowledge tiers. It provides:\n\n- separate StRS stakeholder and SwRS software-requirement layers;\n- stable requirement IDs and explicit lifecycle states;\n- authored `derives_from` relationships with generated reverse links;\n- `@implements_req` and `@tests_req` markers for implementation and test\n  traceability; and\n- validation, coverage, graph, report, archive, and supersession commands.\n\nInitialize and validate a requirements bundle with:\n\n```bash\nokfreq init my-requirements\nokfreq new strs \"Export report\" \\\n  --description \"When export is requested, the reporting capability SHALL make a portable report available.\" \\\n  --user-need \"Users need a portable report for offline review.\" \\\n  --project demo\nokfreq validate my-requirements\nokfreq trace my-requirements\n```\n\nSee the [`okfreq` requirements tutorial](https://okf-schema.readthedocs.io/en/stable/tutorials/okfreq-traceability.html),\nthe [`okfreq` design choices](https://okf-schema.readthedocs.io/en/stable/explanation/okfreq-choices.html),\nand the [skill scope guide](skills/README.md) for the distinction between\ngeneric OKF, `okfkb`, and `okfreq`.\nSee the complete [`okfreq` CLI reference](docs/source/reference/okfreq-cli.md)\nfor every command and option.\n\n### Use Case 4: Validate Standalone Markdown Files\n\nValidate individual markdown files (or collections) against JSON schemas without needing a full OKF bundle.\n\n**Quick Start:**\n\n```bash\n# Validate all markdown files in a directory\nokf-schema validate-md \\\n  --input 'docs/**/*.md' \\\n  --schemas-dir ./schemas\n\n# Validate multiple patterns with strict mode\nokf-schema validate-md \\\n  --input '*.md' \\\n  --input 'docs/**/*.md' \\\n  --schemas-dir ./schemas \\\n  --strict\n```\n\n**Key Commands:**\n\n| Command | Purpose |\n|---------|---------|\n| `validate-md --input PATTERNS --schemas-dir DIR` | Validate standalone files against schemas |\n| `--input 'pattern'` | Glob pattern for files (supports `**` for recursion); can be used multiple times |\n| `--schemas-dir DIR` | Directory containing schema files (`<type>.schema.{json\\|yaml\\|json5}`) |\n| `--strict` | Treat warnings as errors (exit 1) |\n\n**For examples and troubleshooting**, see the [Standalone File Validation Guide](https://okf-schema.readthedocs.io/en/stable/how-to/validate-standalone-files.html) and [Validation Error & Warning Codes Reference](https://okf-schema.readthedocs.io/en/stable/reference/validation-codes.html).\n\n### Validation Reference\n\n\n\n## Recommended Workflow\n\nBefore packaging or distributing a bundle, run these three commands in order and fix all warnings:\n\n```bash\nokf-schema index --path my-bundle/bundle    # regenerate index.md files\nokf-schema lint --path my-bundle/bundle     # flatten nested lists, inline block lists, update links/backlinks\nokf-schema validate --path my-bundle/bundle --strict # check structure, schema, and links; fail on warnings\n```\n\nOnly 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.\n\n## Example: AI & LLM Knowledge Base\n\nThe [`examples/ai-llm-knowledge-base/`](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/`.\n\n### How `type` selects the schema\n\nThe `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`.\n\n### Schema format support\n\n`okf-schema` accepts schemas in three formats:\n\n| Extension | Format | Notes |\n|-----------|--------|-------|\n| `.schema.yaml` | YAML | Human-friendly, supports comments and anchors |\n| `.schema.json` | JSON | Strict syntax, widely supported by editors |\n| `.schema.json5` | JSON5 | JSON with comments, trailing commas, and unquoted keys |\n\n### Schema highlights\n\n**`concept.schema.yaml`** — AI concepts with enums, email validation, and kebab-case regex:\n\n```yaml\nproperties:\n  category:\n    enum: [LLM, AI Agent, Coding Agent, Prompt Engineering, Tooling, Evaluation]\n  maturity:\n    enum: [experimental, beta, production, deprecated]\n  author_email:\n    type: string\n    format: email\n  tags:\n    type: array\n    items:\n      pattern: \"^[a-z0-9-]+$\"   # kebab-case only\n```\n\n**`tool.schema.json`** — Developer tools with URI validation and language enums:\n\n```json\n{\n  \"properties\": {\n    \"license\": {\n      \"enum\": [\"MIT\", \"Apache-2.0\", \"GPL-3.0\", \"Proprietary\", \"Other\"]\n    },\n    \"language\": {\n      \"enum\": [\"Python\", \"JavaScript\", \"TypeScript\", \"Rust\", \"Go\", \"Java\", \"Multi-language\"]\n    },\n    \"url\": { \"type\": \"string\", \"format\": \"uri\" }\n  }\n}\n```\n\n**`paper.schema.json5`** — Research papers with year bounds and venue enums:\n\n```javascript\n// JSON5 allows comments, trailing commas, and unquoted keys\n{\n  properties: {\n    year: { type: \"integer\", minimum: 1950, maximum: 2030 },\n    venue: {\n      enum: [\"NeurIPS\", \"ICML\", \"ICLR\", \"ACL\", \"EMNLP\", \"arXiv\", \"Other\"]\n    },\n    bibtex_key: { pattern: \"^[A-Za-z0-9_-]+$\" },\n  },\n}\n```\n\n### Schema-aware index generation\n\nSchemas can declare `title`, `description`, and an `x-okf-summary` extension\nfield. When a subdirectory contains concepts of a single type,\n`okf-schema index` uses them to produce richer `index.md` files:\n\n| Field | Purpose | Used in |\n|-------|---------|---------|\n| `title` | Short heading for the concept type | Subdirectory `index.md` H1 |\n| `x-okf-summary` | One-line description of the type | Root listing |\n| `description` | Longer schema description | Subdirectory intro |\n\nFor example, `concept.schema.yaml` declares:\n\n```yaml\ntitle: \"Concept\"\nx-okf-summary: \"AI/LLM concepts such as techniques, patterns, or architectural ideas.\"\ndescription: \"Schema for AI/LLM concepts ...\"\n```\n\nRunning `okf-schema index` turns this into:\n\n- A root `index.md` entry: `[concepts](./concepts/) — AI/LLM concepts such as...`\n- A subdirectory `index.md` with `# Concept` as the heading and the description as\n  the first paragraph.\n\n### Concept file example (`concepts/rag.md`)\n\n```markdown\n---\ntype: concept\ntitle: Retrieval-Augmented Generation\ndescription: >\n  A technique that enhances LLM outputs by retrieving relevant documents\n  from an external knowledge store and injecting them into the prompt.\ncategory: LLM\nmaturity: production\nauthor_email: bob@example.com\ncomplexity: intermediate\ntags: [rag, retrieval, llm, knowledge-base]\nrelated_tools: [LangChain, LlamaIndex, OpenAI-API]\n---\n\n# Retrieval-Augmented Generation\n\nRAG combines parametric knowledge (the model's weights) with non-parametric\nknowledge (external documents) to reduce hallucinations...\n```\n\n### Validation in action\n\n```bash\n# Validates all concepts, tools, and papers against their respective schemas\nokf-schema validate --path examples/ai-llm-knowledge-base\n\n# Show bundle statistics\nokf-schema stats --path examples/ai-llm-knowledge-base\n```\n\n## Opinionated Knowledge Base\n\n`okf-schema` includes a dedicated knowledge-base subcommand group (`okfkb`) for managing OKF\nbundles designed for agent-facing experimental findings. A knowledge base is an\nopinionated OKF bundle with 9 content directories (concepts, experiments,\nfindings, hypotheses, outcomes, playbooks, principles, reference, and structures)\nand 10 YAML schemas including the shared base schema.\n\n```bash\n# Scaffold a new knowledge base in the current directory\nokfkb init my-kb\n\n# Install KB skills and guidelines into a project\nokfkb install-skills /path/to/project\n\n# Alternatively, use the okf-schema init --pattern flag\nokf-schema init my-kb --pattern kb\n```\n\nThe `okfkb` binary is a standalone alias for `okf-schema kb` — both are equivalent.\n\n| Command | Description |\n|---------|-------------|\n| `okfkb init [PATH]` | Scaffold KB layout with 9 content dirs, 10 schemas, `index.md`, `log.md` |\n| `okfkb install-skills [PATH]` | Deploy bundled skills and guideline into a project; patch `AGENTS.md` |\n| `okfkb new-finding [PATH] --title TEXT` | Create a timestamped, schema-valid empirical Finding |\n| `okfkb update [PATH]` | Regenerate indexes and lint frontmatter (index + lint in one step) |\n| `okfkb validate [PATH]` | Validate bundle with strict mode (warnings as errors) |\n| `okfkb search TEXT` | Ranked case-insensitive substring search across the KB (optionally scoped `--tier`) |\n| `okfkb get ID` | Exact fetch of a single node by id or path |\n| `okfkb read TIER` | Read a whole stable tier (e.g. `concepts`, `principles`) |\n| `okfkb query EXPR` | Structured query: frontmatter filter DSL + graph traversal (see below) |\n| `okf-schema init NAME --pattern kb` | Same scaffold as `okfkb init` via the pattern registry |\n\n### Navigating the KB: `search` / `get` / `read` / `query`\n\nBeyond authoring, `okfkb` exposes the KB as a small set of **navigation tools** so an agent\ncan actively pull the right granularity instead of loading whole folders:\n\n- **`search`** — coarse ranked retrieval across titles, context, tags, and body.\n- **`get`** — exact fetch of one node by id/path (the drill-down after a `search`).\n- **`read`** — read an entire stable tier at once (top-down entry, e.g. `read principles`).\n- **`query`** — structured selection combining two styles:\n  - **Filter DSL** (flat frontmatter): `key:value` / `key:<operator>value`, ANDed. Confidence is\n    ordinal, so ranges work:\n    ```bash\n    okfkb query \"type:finding confidence:>=high tag:pll status:active\"\n    ```\n  - **Arrow traversal** (a pocket-Cypher over links and derivation edges):\n    `->` follows `links`, `<-` follows `backlinks`, and `^` follows computed\n    `derives_to` edges:\n    ```bash\n    okfkb query \"finding[tag=pll,confidence=high] ^ concept ^ principle\"\n    okfkb query \"concept[title~boot] -> playbook\"\n    ```\n\n**For full KB documentation and commands**, see the [OKF Knowledge Base reference](https://okf-schema.readthedocs.io/en/stable/reference/kb-commands.html).\n\n## Python API\n\n```python\nfrom okf_schema.api import validate_bundle\n\nreport = validate_bundle(\"path/to/bundle\")\nfor finding in [*report.errors, *report.warnings]:\n    print(finding.code, finding.message, finding.path)\n\n# The _schema/ directory inside the bundle is auto-discovered.\n# You can also pass an explicit schema_db path:\n# report = validate_bundle(\"path/to/bundle\", schema_db=\"path/to/schemas\")\n```\n\n## Agent Skills\n\nThe repository provides six complementary skills:\n\n| Skill | Concise purpose |\n|---|---|\n| [`okf-schema`](skills/okf-schema/SKILL.md) | Operate and troubleshoot the CLI/API, schemas, validation, frontmatter, and generic OKF bundles. |\n| [`okfkb`](skills/okfkb/SKILL.md) | Teach and route the opinionated lifecycle from immutable Findings to stable knowledge and human-governed Principles. |\n| [`okfkb-record-findings`](skills/okfkb-record-findings/SKILL.md) | Capture one dated, immutable empirical Finding after an investigation. |\n| [`okfkb-distill`](skills/okfkb-distill/SKILL.md) | Interactively reconcile contradictions and propose evidence-backed promotions. |\n| [`okfkb-gardening`](skills/okfkb-gardening/SKILL.md) | Perform explicitly invoked, zero-prompt consolidation, graph repair, stale-knowledge review, and project-prescribed validation. |\n| [`okfreq-gardening`](skills/okfreq-gardening/SKILL.md) | Maintain requirement traceability, generated coverage, lifecycle, and health reports without conflating requirements with OKFKB knowledge. |\n\nSee [`skills/README.md`](skills/README.md) for selection guidance and the\nrecommended maintenance rhythm.\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/gsemet/okf-schema/blob/main/CONTRIBUTING.md) for development setup and guidelines.\n\n## Known Alternative\n\nHere is some alternative OKF tooling that may interest you as well:\n\n- [IWE](https://github.com/iwe-org/iwe): Full-featured, Rust-based OKF bundle manager. It does\n  not provide schema validation, but provides querying, indexing, an MCP server, a VS Code extension, and more.\n\nTons of other resources just limit to apply OKF to LLM-Wiki\n(ex: [okf-harness](https://github.com/pumblus/okf-harness) or\n[openknowledge](https://github.com/openknowledge-sh/openknowledge)).\n\nOKF-Schema is deliberately more opinionated, focused on frontmatter validation and preparing\nthe bundle for direct agentic consumption (I do not plan to build a MCP server, I prepare my agent\nto read files directly). `okfkb` is even more opinionated, with a strict but ready-to-use\nknowledge base structure and schema.\n\n## License\n\nMIT License — see [LICENSE](https://github.com/gsemet/okf-schema/blob/main/LICENSE) for details.\n",
  "bytes": 21582,
  "sha": "9e4fb05357e29a0be0dfac4e691b8d495edc541db553cb36c19639263dfdd5f7",
  "repo_slug": "gsemet/okf-schema",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_gsemet_okf_schema_skills_evals_results_i_32bac107/readme"
}