Crate okf

Expand description

§okf: the Open Knowledge Format, in pure Rust

A dependency-free 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.

OKF is intentionally minimal (“if you can cat a file, you can read OKF; if you can git clone a repo, you can ship it”), so this crate implements it with the standard library alone: its own YAML-subset parser, a markdown link scanner, a directory walker, and (in the binary) CLI argument parsing. There are no third-party dependencies.

§Model

A Bundle is a directory tree of markdown files (§3).
A Concept is one markdown Document = YAML Frontmatter + body (§4).
A ConceptId is a concept’s path within the bundle, minus .md (§2).
Concepts relate via markdown links (§6); the bundle exposes the resulting graph and backlinks.
index.md directory listings (§8) are generated by index.
log.md histories (§9) are parsed by log.
validate_bundle checks §11 conformance.

§What v0.2 adds

v0.2 makes provenance, trust, lifecycle, and attestation first-class. Every one of the new keys is optional, and absence is meaningful rather than invalid, so a v0.1 document is still a conformant v0.2 document.

Concern	Frontmatter	Module
Provenance	`sources`, `usage_window` (§5.1)	`provenance`
Trust	`generated`, `verified` (§5.2), trust tiers (§5.3)	`trust`
Lifecycle	`status` (§5.4), `stale_after` (§5.5)	`trust`
Identity	the actor convention (§7)	`actor`
Attestation	`runtime`, `parameters`, `computation`, `executor`, `attester` (§10)	`computation`
Attribution	`[^label]` footnotes keyed to `sources[].id` (§5.1)	`footnotes`

Two v0.1 constructs are superseded (§13.1) but still readable, since a v0.2 consumer is expected to handle v0.1 bundles: timestamp gives way to generated.at (see Frontmatter::content_changed_at), and the body # Citations list gives way to sources (see Document::citations).

§Example

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");
}

Reading a concept’s trust signals:

use okf::{Document, TrustTier};

let doc = Document::parse(
    "---\n\
     type: Metric\n\
     title: Revenue\n\
     status: stable\n\
     generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }\n\
     verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }\n\
     stale_after: 2026-12-31\n\
     ---\n\n\
)
.unwrap();

// A bare `verified` mapping counts as a one-element list (§5.2).
assert_eq!(doc.frontmatter.verified().len(), 1);
assert_eq!(doc.frontmatter.trust_tier(), TrustTier::HumanReviewed);
assert_eq!(doc.frontmatter.status().to_string(), "stable");

Modules§

actor: The actor convention (§7): who or what performed an action.
bundle: Loading and traversing an OKF bundle: a directory tree of markdown files (§3).
computation: Attested Computation concepts (§10).
concept_id: Concept identifiers and their mapping to/from file paths.
date: Calendar dates and ISO-8601 datetimes for the trust and lifecycle families (§5).
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.
footnotes: Markdown footnotes, the carrier for per-claim attribution (§5.1).
frontmatter: Typed, order-preserving access to a concept’s YAML frontmatter.
index: Generation of index.md directory listings (§8).
links: Markdown link extraction, classification, and path-valued fields (§6).
lint: Opinionated bundle health checks, beyond §11 conformance.
log: Parsing and building log.md update histories (§9).
provenance: Provenance: the sources frontmatter family and per-claim attribution (§5.1).
trust: Trust and lifecycle frontmatter: generated, verified, status, and stale_after (§5.2 to §5.5).
validate: Conformance checking against OKF v0.2 §11.
yaml: A small, dependency-free YAML subset used for OKF frontmatter.

Structs§

Actor: A parsed actor string (§7), retaining the text exactly as written.
AttestedComputation: The contract of an Attested Computation concept: its top-level frontmatter (§10.2) plus the computation itself (§10.3).
Attester: The deterministic check (§10.2).
Attribution: A body claim attributed to a source, produced by joining footnote labels to sources[].id (§5.1).
Bundle: A loaded OKF bundle.
BundleDiff: A bundle-level diff.
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.
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 (§10.2).
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 (§5.2): generated: { by, at }.
InlineComputation: A computation held in the body under # Computation (§10.3).
Link: A markdown link found in a concept body.
Log: A parsed log.md.
Mapping: An ordered YAML mapping (preserves insertion / source order, like the reference implementation which dumps with sort_keys=False).
Parameter: One typed, named hole an agent may fill (§10.2).
Rename: A rename detected by matching content hash between a removed and an added concept.
Report: The result of validating a bundle.
ResolvedLink: A cross-link from one concept to another, after resolution (§6.1).
ResolvedSource: A sources entry resolved against the bundle (§5.1).
Source: One entry in the sources list: a material the concept derives from.
TrustChange: A trust tier or status change for a concept present in both bundles.
UsageWindow: The date range that frames usage_count (§5.1).
Verification: A single verification event (§5.2): { 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 (§10.3).
DocumentError: Errors raised when parsing or validating a single OKF concept document.
LinkKind: How a link target is interpreted under §6.1.
ResourceKind: What kind of thing a sources[].resource names (§5.1).
Severity: Severity of a diagnostic.
Status: A concept’s lifecycle status (§5.4). An absent key means Status::Stable.
TrustTier: A concept’s trust tier, derived from verified (§5.3).
Value: A parsed YAML value.

Constants§

ATTESTED_COMPUTATION_TYPE: The type value that marks a concept as an Attested Computation (§10.1).
KNOWN_FRONTMATTER_KEYS: Every frontmatter key the specification gives a meaning to, across all families. Anything else is a producer extension (§4.1).
LEGACY_FRONTMATTER_KEYS: Keys v0.2 retired but consumers may still encounter in v0.1 documents (§13.1). 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 (§4.1): a concept carrying nothing but type is fully conformant (§11).
RESERVED_FILENAMES: Reserved filenames with defined meaning at any level (§3.1).
SUPPORTED_OKF_VERSIONS: Specification versions this crate can consume.

Functions§

bundle_diff: Computes the OKF-semantics diff between two bundles.
lint_bundle: Lints a loaded bundle, returning all findings.
lint_bundle_at: Lints a bundle, additionally flagging concepts that are stale on today.
validate_bundle: Validates a loaded bundle against §11, returning all findings.
validate_bundle_at: Validates a bundle, additionally reporting concepts that are stale on today (§5.5).

Crate okf

Crate okf Copy item path

§okf: the Open Knowledge Format, in pure Rust

§Model

§What v0.2 adds

§Example

Modules§

Structs§

Enums§

Constants§

Functions§

Crate okf