Data Models

These dataclasses are returned by the Python API and used throughout okf-schema.

Validation

class okf_schema._internal.models.Finding(code, message, path=None)

A single validation finding (error or warning).

Parameters:

  • code (str)

  • message (str)

  • path (Path | None)

class okf_schema._internal.models.Report(errors=<factory>, warnings=<factory>)

Aggregated validation report for an OKF bundle.

Parameters:
property is_conformant: bool

Return True if the report contains no errors.

add_error(code, message, path=None)

Append an error finding to the report.

Parameters:

  • code (str) – Stable machine-readable finding code.

  • message (str) – Human-readable explanation.

  • path (Path | None) – Optional path associated with the finding.

Return type:

None

Examples

>>> from okf_schema._internal.models import Report
>>> report = Report()
>>> report.add_error("missing-title", "Title is required")
>>> report.is_conformant
False
add_warning(code, message, path=None)

Append a warning finding to the report.

Parameters:

  • code (str) – Stable machine-readable finding code.

  • message (str) – Human-readable explanation.

  • path (Path | None) – Optional path associated with the finding.

Return type:

None

Examples

>>> from okf_schema._internal.models import Report
>>> report = Report()
>>> report.add_warning("missing-description", "Description is recommended")
>>> len(report.warnings)
1

Concepts

class okf_schema._internal.models.ConceptInfo(title, description, type)

Extracted metadata from an OKF concept file.

Parameters:

  • title (str)

  • description (str)

  • type (str)

class okf_schema._internal.models.ConceptSummary(path, type, title, stale=False)

Summary of a single concept in an OKF bundle.

Parameters:

  • path (str)

  • type (str)

  • title (str)

  • stale (bool)

class okf_schema._internal.models.ConceptDetail(frontmatter, body, trust_tier='unverified', stale=False)

Detailed view of a single concept file.

Parameters:

  • frontmatter (dict[str, object])

  • body (str)

  • trust_tier (str)

  • stale (bool)

Search and navigation

class okf_schema._internal.models.SearchResult(path, type, title)

Result from searching an OKF bundle.

Parameters:

  • path (str)

  • type (str)

  • title (str)

class okf_schema._internal.models.BacklinkResult(target, source)

A single backlink: a source concept that links to a target concept.

Parameters:

  • target (str)

  • source (str)

class okf_schema._internal.models.IndexUpdate(path, action)

Record of an index.md update operation.

Parameters:

  • path (str)

  • action (str)

Statistics

class okf_schema._internal.models.BundleStats(total_files, total_concepts, files_without_frontmatter, total_size, total_links, broken_links, types_distribution, tags_distribution, directories)

Statistics for an OKF bundle.

Parameters:

  • total_files (int)

  • total_concepts (int)

  • files_without_frontmatter (int)

  • total_size (int)

  • total_links (int)

  • broken_links (int)

  • types_distribution (dict[str, int])

  • tags_distribution (dict[str, int])

  • directories (int)