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)

Validate an OKF bundle.

Parameters:

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

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

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 diff in results without modifying.

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.

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 diff in results without modifying.

  • 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.

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.