Python API Reference

The okf_schema.api module provides a clean, typed Python interface for all okf-schema operations.

Bundle operations

okf_schema.api.validate_bundle(bundle_path, schema_db=None, *, check_links=False, project_root=None)

Validate an OKF bundle.

Parameters:

  • bundle_path (str | Path) – Path to the OKF bundle directory.

  • schema_db (str | Path | None) – Optional directory containing JSON or YAML schema files. If not provided, the _schema subdirectory inside the bundle is used automatically when it exists.

  • check_links (bool) – Enable opt-in x-okf-link target checking.

  • project_root (str | Path | None) – Explicit project root for project-relative links. If unavailable, the containing Git root of each document is used.

Return type:

Report

Returns:

A Report with all errors and warnings.

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

okf_schema.api.format_bundle(bundle_path, check=False, diff=False)

Format frontmatter in all concept files of an OKF bundle.

Parameters:

  • bundle_path (str | Path) – Path to the OKF bundle directory.

  • check (bool) – If True, do not modify files; only report changes needed.

  • diff (bool) – If True, include unified diffs in results without modifying files.

Return type:

list[FormattedResult]

Returns:

List of FormattedResult, one per markdown file.

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

Examples

>>> from tempfile import TemporaryDirectory
>>> from okf_schema.api import format_bundle
>>> with TemporaryDirectory() as directory:
...     results = format_bundle(directory, check=True)
okf_schema.api.lint_bundle(bundle_path, check=False, diff=False, links=False)

Lint frontmatter in all concept files of an OKF bundle.

Converts block-style (multi-line) lists to inline notation so that frontmatter stays compact. This is important for coding agents that load only the first n lines of a file.

Parameters:

  • bundle_path (str | Path) – Path to the OKF bundle directory.

  • check (bool) – If True, do not modify files; only report changes needed.

  • diff (bool) – If True, include unified diffs in results without modifying files.

  • links (bool) – If True, also update links and backlinks frontmatter fields based on markdown body content.

Return type:

list[FormattedResult]

Returns:

List of FormattedResult, one per markdown file.

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

Examples

>>> from tempfile import TemporaryDirectory
>>> from okf_schema.api import lint_bundle
>>> with TemporaryDirectory() as directory:
...     results = lint_bundle(directory, check=True, links=True)
okf_schema.api.list_bundle(bundle_path)

List all concepts in an OKF bundle.

Parameters:

bundle_path (str | Path) – Path to the OKF bundle directory.

Return type:

list[ConceptSummary]

Returns:

Sorted list of ConceptSummary objects.

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

okf_schema.api.show_bundle(bundle_path, concept_path)

Show a single concept’s frontmatter and body.

Parameters:

  • bundle_path (str | Path) – Path to the OKF bundle directory.

  • concept_path (str) – Relative path to the concept markdown file.

Return type:

ConceptDetail

Returns:

A ConceptDetail with frontmatter dict and body text.

Raises:

FileNotFoundError – When the concept file does not exist.

okf_schema.api.index_bundle(bundle_path)

Regenerate all index.md files in an OKF bundle.

For each directory containing markdown files, generates or updates an index.md listing child concepts and subdirectories. Preserves bundle-root frontmatter if present.

Parameters:

bundle_path (str | Path) – Path to the OKF bundle directory.

Return type:

list[IndexUpdate]

Returns:

List of IndexUpdate records describing what changed.

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

okf_schema.api.search_bundle(bundle_path, query)

Search concepts in an OKF bundle.

Performs a case-insensitive substring search across title, description, type, and tags frontmatter fields.

Parameters:

  • bundle_path (str | Path) – Path to the OKF bundle directory.

  • query (str) – Search string.

Return type:

list[SearchResult]

Returns:

Sorted list of matching SearchResult objects.

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

okf_schema.api.stats_bundle(bundle_path)

Compute statistics for an OKF bundle.

Parameters:

bundle_path (str | Path) – Path to the OKF bundle directory.

Return type:

BundleStats

Returns:

A BundleStats object with file counts, link counts, type/tag distributions, and directory counts.

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

okf_schema.api.graph_bundle(bundle_path)

Build a concept link graph for an OKF bundle.

Parses all internal markdown links in concept bodies and returns an adjacency dictionary mapping each concept’s relative path to the list of concept paths it links to.

Parameters:

bundle_path (str | Path) – Path to the OKF bundle directory.

Returns:

{concept_path: [linked_path, ...]}.

Return type:

dict[str, list[str]]

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

Find all concepts that link to any of the given target concepts.

For each target path, scans every concept in the bundle and returns a backlink record for each concept that contains an internal markdown link pointing to that target. Reserved files (index.md, log.md) are excluded as sources. Self-links are ignored.

Targets may be given with or without the .md extension.

Parameters:

  • bundle_path (str | Path) – Path to the OKF bundle directory.

  • targets (list[str]) – List of relative concept paths to find backlinks for.

Return type:

list[BacklinkResult]

Returns:

Sorted list of BacklinkResult records, one per backlink. Results are ordered by (target, source).

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

okf_schema.api.validate_markdown_files(input_patterns, schemas_dir=None, *, check_links=False, bundle_root=None, project_root=None)

Validate standalone markdown files against JSON schemas.

This is useful for validating markdown files with frontmatter that are not part of a full OKF bundle. Each pattern is resolved using pathlib’s glob syntax (supports ** for recursive matching).

Parameters:

  • input_patterns (list[str] | str) – One or more glob patterns (for example, "docs/**/*.md"). Can be a single string or a list of strings. Patterns are resolved relative to the current working directory. Absolute paths are also supported.

  • schemas_dir (str | Path | None) – Optional directory containing JSON or YAML schema files. If not provided, schema validation is skipped. Because no schema database was requested, missing-schema (W6) warnings are not emitted. Schema files should be named <type>.schema.{json|json5|yaml|yml}.

  • check_links (bool) – Enable opt-in x-okf-link target checking.

  • bundle_root (str | Path | None) – Optional bundle root for bundle-relative and filename-stem links.

  • project_root (str | Path | None) – Explicit project root for project-relative links. If unavailable, the containing Git root of each document is used.

Return type:

Report

Returns:

A Report with all errors and warnings.

Raises:

  • FileNotFoundError – When schemas_dir does not exist (if provided).

  • NotADirectoryError – When schemas_dir is not a directory (if provided).

Rewrite markdown body links pointing to superseded documents.

Scans all documents for status: superseded with a superseded_by field. For each such document, every other document whose markdown body links to it has that link rewritten to the first superseded_by path.

The links / backlinks frontmatter fields are not updated here; they are refreshed by the subsequent lint_bundle() call that update_bundle() performs automatically.

Parameters:

  • bundle_path (str | Path) – Path to the OKF bundle directory.

  • check (bool) – If True, report rewrites without modifying files.

Return type:

tuple[list[SupersededRewrite], list[DeferredRewrite]]

Returns:

A tuple (rewrites, deferred) where rewrites lists performed replacements and deferred lists superseded docs whose links could not be automatically updated (missing or non-existent superseded_by).

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

Examples

>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> from okf_schema.api import rewrite_superseded_links
>>> with TemporaryDirectory() as directory:
...     bundle = Path(directory)
...     old = "---\nstatus: superseded\nsuperseded_by: [new.md]\n---\n"
...     source = "---\ntype: concept\n---\nSee [old](old.md).\n"
...     _ = (bundle / "old.md").write_text(old)
...     _ = (bundle / "new.md").write_text("---\ntype: concept\n---\n")
...     _ = (bundle / "source.md").write_text(source)
...     rewrites, deferred = rewrite_superseded_links(bundle, check=True)
...     (len(rewrites), len(deferred))
(1, 0)
okf_schema.api.update_bundle(bundle_path, check=False, diff=False, links=True)

Regenerate indexes and lint frontmatter in an OKF bundle.

Combines rewrite_superseded_links(), index_bundle(), and lint_bundle() into a single operation. This is the recommended command for keeping a knowledge base up to date after edits.

The superseded-link rewriting pass runs first so that the subsequent lint pass can update the links / backlinks frontmatter to reflect the rewritten targets.

Parameters:

  • bundle_path (str | Path) – Path to the OKF bundle directory.

  • check (bool) – If True, do not modify files; only report changes needed.

  • diff (bool) – If True, include unified diffs in results without modifying files.

  • links (bool) – If True, also update links and backlinks frontmatter fields based on markdown body content.

Return type:

UpdateResult

Returns:

An UpdateResult with index, lint, and rewrite results.

Raises:

  • FileNotFoundError – When bundle_path does not exist.

  • NotADirectoryError – When bundle_path is not a directory.

Examples

>>> from tempfile import TemporaryDirectory
>>> from okf_schema.api import update_bundle
>>> with TemporaryDirectory() as directory:
...     result = update_bundle(directory, check=True, links=True)

Result types

class okf_schema.api.UpdateResult(index_updates, lint_results, superseded_rewrites=<factory>, deferred_rewrites=<factory>)

Result of updating an OKF bundle (index + lint).

Parameters:
class okf_schema.api.SupersededRewrite(source, old_target, new_target)

A link in a document rewritten from a superseded target to its replacement.

Parameters:

  • source (str)

  • old_target (str)

  • new_target (str)

class okf_schema.api.DeferredRewrite(superseded_doc, reason)

A superseded document whose backlinks could not be automatically rewritten.

Parameters:

  • superseded_doc (str)

  • reason (str)

Result identities and inspection lifetime

value_identity is an escaped JSON Pointer: /a.b identifies a literal dotted key, /a/b identifies a nested key, and /attachments/0 identifies an array item. ~ and / in keys escape as ~0 and ~1; the document root is the empty string. Use this identity for editor state and matching results; field_path remains a human-readable label such as attachments[0] and is not a unique key.

A local $ref and its siblings both constrain union applicability. Only the selected then or else branch contributes conditional annotations. A literal null character in a target produces E10 rather than interrupting inspection.

Filename-stem resolution indexes Markdown candidates once per bundle in an inspection or validation campaign. The index is discarded after the call, so a later call observes added files and newly ambiguous names. There is no global cache and callers do not need to invalidate editor state.