Crate okf

Expand description

§okf: the Open Knowledge Format, in pure Rust

A pure Rust implementation of the Open Knowledge Format (OKF) v0.2, Google’s open, human- and agent-friendly format for representing knowledge as a directory of markdown files with YAML frontmatter.

This crate is the user-facing entry point of the OKF workspace. It ships the okf command-line tool (cargo install okf) and re-exports the entire API of the okf-core crate and the okf-validator crate.

use okf::{Bundle, validate_bundle};

let bundle = Bundle::load("./my_bundle")?;
println!("{} concepts", bundle.len());

let report = validate_bundle(&bundle);
if report.is_conformant() {
    println!("conformant OKF v0.2 bundle");
}

See the okf-core documentation for the full model: Bundle, Document, Frontmatter, ConceptId, the provenance/trust/attestation families, validate_bundle conformance checker, and lint_bundle multi-language syntax and hygiene checks.

Modules§

actor: The actor convention: who or what performed an action.
bundle: Loading and traversing an OKF bundle: a directory tree of markdown files.
computation: Attested Computation concepts.
concept_id: Concept identifiers and their mapping to/from file paths.
date: Calendar dates and ISO-8601 datetimes for the trust and lifecycle families.
diff: Bundle-level diff: an OKF-semantics diff between two Bundles.
document: The OKF concept document: YAML frontmatter + markdown body.
error: Error types for the crate.
fix: Automated remediation and migrations for OKF concepts, bundles, and logs.
footnotes: Markdown footnotes, the carrier for per-claim attribution.
frontmatter: Typed, order-preserving access to a concept’s YAML frontmatter.
index: Generation of index.md directory listings.
links: Markdown link extraction, classification, and path-valued fields.
lint: Opinionated bundle health checks, beyond conformance and validation.
log: Parsing, building, and updating log.md update histories.
markdown: Markdown scanning, link rewriting, heading extraction, and anchor slugs.
provenance: Provenance: the sources frontmatter family and per-claim attribution.
refactor: Knowledge refactoring, concept relocation, deletion, splitting, and merging.
scaffold: Scaffolding and initialization utilities for OKF bundles and concept documents.
syntax: Multi-language syntax validation for Attested Computations and embedded scripts.
trust: Trust and lifecycle frontmatter: generated, verified, status, and stale_after.
validate: Conformance checking and structural validation against OKF v0.2.
yaml: A small YAML subset parser used for OKF frontmatter.

Structs§

Actor: A parsed actor string, retaining the text exactly as written.
AttestedComputation: The contract of an Attested Computation concept: its top-level frontmatter plus the computation itself.
Attester: The deterministic check.
Attribution: A body claim attributed to a source, produced by joining footnote labels to sources[].id.
Bundle: A loaded OKF bundle.
BundleDiff: A bundle-level diff.
BundleFixReport: Remediation report for a whole bundle.
BundleInitOptions: Options for initializing a new OKF bundle.
Citation: A numbered entry under a legacy v0.1 # Citations heading.
Concept: A single concept within a bundle (one markdown document).
ConceptId: A concept identifier: an ordered list of path segments (e.g. ["tables", "users"] for tables/users).
ConceptIdError: Error returned when a concept-id segment is malformed.
ConceptOptions: Options for creating a new concept document.
Date: A proleptic-Gregorian calendar date (YYYY-MM-DD).
DateField: A frontmatter date field: the scalar exactly as written, plus its parse.
DateTime: An ISO-8601 datetime: a Date, an optional time of day, and an optional UTC offset.
DateTimeField: A frontmatter datetime field: the scalar exactly as written, plus its parse.
Diagnostic: A single finding about a bundle.
Document: A parsed OKF concept document.
Executor: How the computation is run.
FencedCodeBlock: A parsed fenced code block from markdown.
FileFixReport: Remediation report for a single file.
FixOptions: Options controlling automated remediation and migration.
FootnoteDef: A [^label]: text definition line.
FootnoteRef: A [^label] reference in the body prose.
Frontmatter: A concept’s frontmatter: an ordered key/value mapping with typed accessors for the well-known OKF fields.
FrontmatterChange: Frontmatter key changes for a concept present in both bundles.
Generated: How the current content was produced: generated: { by, at }.
InlineComputation: A computation held in the body under # Computation.
Link: A markdown link found in a concept body.
Log: A parsed log.md.
LogDay: All entries recorded under a single date heading.
LogEntry: A single log bullet.
Mapping: An ordered YAML mapping (preserves insertion / source order, like the reference implementation which dumps with sort_keys=False).
MarkdownHeading: A parsed markdown heading.
MergeOptions: Options for merging one concept into another.
MergeReport: Summary report of a merge operation.
MoveOptions: Options for moving or renaming a concept.
MoveReport: Summary report of a move/rename operation.
Parameter: One typed, named hole an agent may fill.
ParseActorKindError: Error returned when a string cannot be parsed into an ActorKind.
ParseLinkKindError: Error returned when a string cannot be parsed into a LinkKind.
ParseSeverityError: Error returned when a string cannot be parsed into a Severity.
ParseTrustTierError: Error returned when a string cannot be parsed into a TrustTier.
Remediation: A single remediation action applied to a document or file.
RemoveOptions: Options for removing a concept.
RemoveReport: Summary report of a removal operation.
Rename: A rename detected by matching content hash between a removed and an added concept.
RenameSectionOptions: Options for renaming a section heading within a concept.
RenameSectionReport: Summary report of a section rename operation.
Report: The result of validating a bundle.
ResolvedLink: A cross-link from one concept to another, after resolution.
ResolvedSource: A sources entry resolved against the bundle.
Source: One entry in the sources list: a material the concept derives from.
SplitOptions: Options for splitting a concept section into a new concept.
SplitReport: Summary report of a split operation.
SyntaxError: A syntax diagnostic produced by static AST parsing.
TrustChange: A trust tier or status change for a concept present in both bundles.
UsageWindow: The date/time range that frames usage_count.
Verification: A single verification event: { by, at }.

Enums§

ActorKind: The category an actor string falls into.
BundleError: Errors raised when loading or operating on a bundle on disk.
ComputationSource: Where the sanctioned computation lives.
DocumentError: Errors raised when parsing or validating a single OKF concept document.
Language: Supported languages for static syntax checking.
LinkKind: How a link target is interpreted.
LinkRewriteAction: Action to perform on a detected markdown link during rewrite.
RefactorError: Error returned when a refactoring operation fails.
RemediationKind: What kind of remediation or migration was applied.
ResourceKind: What kind of thing a sources[].resource names.
Severity: Severity of a diagnostic.
Status: A concept’s lifecycle status. An absent key means Status::Stable.
TrustTier: A concept’s trust tier, derived from verified.
Value: A parsed YAML value.

Constants§

ATTESTED_COMPUTATION_TYPE: The type value that marks a concept as an Attested Computation.
KNOWN_FRONTMATTER_KEYS: Every frontmatter key the specification gives a meaning to, across all families. Anything else is a producer extension.
LEGACY_FRONTMATTER_KEYS: Keys v0.2 retired but consumers may still encounter in v0.1 documents. timestamp is superseded by generated.at.
OKF_VERSION: The OKF specification version this crate implements.
PREFERRED_KEY_ORDER: The key order the reference implementation writes documents in (its _PREFERRED_KEY_ORDER): identity first, then lifecycle, trust, and provenance.
RECOMMENDED_FRONTMATTER_KEYS: Keys a producer should fill in before publishing, in the order Document::missing_recommended reports them.
REQUIRED_FRONTMATTER_KEYS: The only frontmatter key OKF always requires: a concept carrying nothing but type is fully conformant.
RESERVED_FILENAMES: Reserved filenames with defined meaning at any level.
SUPPORTED_OKF_VERSIONS: Specification versions this crate can consume.

Functions§

append_log_entry: Appends an entry to log.md in the bundle root, creating the file if needed.
bundle_diff: Computes the OKF-semantics diff between two bundles.
check_syntax: Checks the syntax of source for the given language tag or name.
compute_relative_path: Computes the relative markdown link path from from_concept to to_concept.
create_concept: Creates a new concept markdown file with proper frontmatter and heading.
default_author: Returns a default author actor string based on system user environment variables or "human:author".
extract_fenced_code_blocks: Extracts all fenced code blocks (delimited by 3+ backticks or 3+ tildes) from markdown text.
extract_headings: Extracts all markdown headings in document order, ignoring headings inside fenced code blocks.
field_path_candidates: Normalizes a path-valued frontmatter field into the bundle-relative paths it might name, most likely first.
heading_slug: Derives a standard Markdown anchor slug from a heading text.
init_bundle: Initializes a new OKF bundle at root with index.md, log.md, and optionally an initial concept.
lint_bundle: Lints a loaded bundle, returning all findings.
lint_bundle_at: Lints a bundle, returning all opinionated formatting and style findings.
matches_heading: Checks whether a heading text matches a search query by title, slug, or normalized spacing.
merge_concepts: Merges source concept into target concept and deletes source.
move_concept: Moves or renames a concept, rewriting all incoming links and rebasing outgoing links.
normalize_iso_datetime: Normalizes a date or datetime string to an ISO-8601 datetime with an explicit UTC offset (Z).
parse_heading_line: Parses a single line as an ATX heading (# through ###### ).
rebase_relative_path: Rebases a relative file/resource path from old_dir to new_dir.
remediate_bundle: Remediates an entire bundle directory tree.
remediate_document: Remediates and migrates a single Document.
remediate_file: Remediates a single file on disk.
remediate_log: Remediates a parsed log.md file (consolidating duplicate date headings).
remove_concept: Safely removes a concept from the bundle.
rename_section: Renames a section heading within a concept and updates all internal and external anchor links.
rewrite_markdown_links: Rewrites inline markdown links in a document body using a callback function.
split_concept: Splits a section from an existing concept into a new concept.
validate_bundle: Validates a loaded bundle, returning all findings.
validate_bundle_at: Validates a bundle, additionally reporting concepts that are stale on today.

Crate okf

Crate okf Copy item path

§okf: the Open Knowledge Format, in pure Rust

Modules§

Structs§

Enums§

Constants§

Functions§

Crate okf