Crate okf 

okf — the Open Knowledge Format, in pure Rust

A dependency-free implementation of the Open Knowledge Format (OKF) v0.1, 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 (§5); the bundle exposes the resulting graph and backlinks.
• index.md directory listings (§6) are generated by index.
• log.md histories (§7) are parsed by log.
• validate_bundle checks §9 conformance.

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

Parsing a single document:

use okf::Document;

let doc = Document::parse("---\ntype: Metric\ntitle: DAU\n---\n\n# Body\n").unwrap();
assert_eq!(doc.frontmatter.type_().as_deref(), Some("Metric"));
assert!(doc.validate_conformance().is_ok());

Modules

bundle

Loading and traversing an OKF bundle: a directory tree of markdown files (§3).

concept_id

Concept identifiers and their mapping to/from file paths.

document

The OKF concept document: YAML frontmatter + markdown body.

error

Error types for the crate.

frontmatter

Typed, order-preserving access to a concept’s YAML frontmatter.

index

Generation of index.md directory listings (§6).

links

Markdown link extraction, classification, and citation parsing (§5, §8).

log

Parsing and building log.md update histories (§7).

validate

Conformance checking against OKF v0.1 §9.

yaml

A small, dependency-free YAML subset used for OKF frontmatter.

Structs

Bundle

A loaded OKF bundle.

Citation

A numbered entry under the # Citations heading (§8).

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.

Diagnostic

A single finding about a bundle.

Document

A parsed OKF concept document.

Frontmatter

A concept’s frontmatter: an ordered key/value mapping with typed accessors for the well-known OKF fields.

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

Report

The result of validating a bundle.

ResolvedLink

A cross-link from one concept to another, after resolution (§5.3).

Enums

BundleError

Errors raised when loading or operating on a bundle on disk.

DocumentError

Errors raised when parsing or validating a single OKF concept document.

LinkKind

How a link target is interpreted under §5.

Severity

Severity of a diagnostic.

Value

A parsed YAML value.

Constants

OKF_VERSION

The OKF specification version this crate implements.

REQUIRED_FRONTMATTER_KEYS

Frontmatter keys the reference enrichment agent requires before a document is considered publishable (its OKFDocument.validate()). Note this is stricter than spec conformance (§9), which requires only type.

RESERVED_FILENAMES

Reserved filenames with defined meaning at any level (§3.1).

Functions

validate_bundle

Validates a loaded bundle against §9, returning all findings.