okf_core/
lib.rs

1//! # okf-core: the Open Knowledge Format, in pure Rust
2//!
3//! A dependency-free implementation of the [Open Knowledge Format (OKF)
4//! v0.2][spec], Google's open, human- and agent-friendly format for
5//! representing knowledge as a directory of markdown files with YAML
6//! frontmatter.
7//!
8//! OKF is intentionally minimal ("if you can `cat` a file, you can read OKF; if
9//! you can `git clone` a repo, you can ship it"), so this crate implements it
10//! with the standard library alone: its own [YAML-subset parser](yaml), a
11//! markdown [link scanner](links), and a directory walker. There are **no
12//! third-party dependencies**. The companion `okf` crate re-exports this
13//! entire library and ships the `okf` command-line tool.
14//!
15//! ## Model
16//!
17//! - A [`Bundle`] is a directory tree of markdown files (§3).
18//! - A [`Concept`] is one markdown [`Document`] = YAML [`Frontmatter`] + body
19//!   (§4).
20//! - A [`ConceptId`] is a concept's path within the bundle, minus `.md` (§2).
21//! - Concepts relate via markdown [`links`] (§6); the bundle exposes the
22//!   resulting graph and backlinks.
23//! - `index.md` directory listings (§8) are generated by [`index`].
24//! - `log.md` histories (§9) are parsed by [`log`].
25//! - §11 conformance checking and linting live in the companion
26//!   [`okf-validator`](https://docs.rs/okf-validator) crate.
27//!
28//! ## What v0.2 adds
29//!
30//! v0.2 makes provenance, trust, lifecycle, and attestation first-class. Every
31//! one of the new keys is optional, and absence is meaningful rather than
32//! invalid, so a v0.1 document is still a conformant v0.2 document.
33//!
34//! | Concern     | Frontmatter                                                    | Module          |
35//! |-------------|----------------------------------------------------------------|-----------------|
36//! | Provenance  | `sources`, `usage_window` (§5.1)                                | [`provenance`]  |
37//! | Trust       | `generated`, `verified` (§5.2), trust tiers (§5.3)              | [`trust`]       |
38//! | Lifecycle   | `status` (§5.4), `stale_after` (§5.5)                           | [`trust`]       |
39//! | Identity    | the actor convention (§7)                                       | [`actor`]       |
40//! | Attestation | `runtime`, `parameters`, `computation`, `executor`, `attester` (§10) | [`computation`] |
41//! | Attribution | `[^label]` footnotes keyed to `sources[].id` (§5.1)             | [`footnotes`]   |
42//!
43//! Two v0.1 constructs are superseded (§13.1) but still readable, since a v0.2
44//! consumer is expected to handle v0.1 bundles: `timestamp` gives way to
45//! `generated.at` (see [`Frontmatter::content_changed_at`]), and the body
46//! `# Citations` list gives way to `sources` (see [`Document::citations`]).
47//!
48//! ## Example
49//!
50//! ```no_run
51//! use okf_core::{Bundle, ConceptId};
52//!
53//! let bundle = Bundle::load("./my_bundle")?;
54//! println!("{} concepts", bundle.len());
55//!
56//! let id = ConceptId::parse("tables/orders")?;
57//! for link in bundle.links_from(&id) {
58//!     println!("{} -> {} (exists: {})", id, link.target, link.exists);
59//! }
60//! # Ok::<(), Box<dyn std::error::Error>>(())
61//! ```
62//!
63//! Reading a concept's trust signals:
64//!
65//! ```
66//! use okf_core::{Document, TrustTier};
67//!
68//! let doc = Document::parse(
69//!     "---\n\
70//!      type: Metric\n\
71//!      title: Revenue\n\
72//!      status: stable\n\
73//!      generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }\n\
74//!      verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }\n\
75//!      stale_after: 2026-12-31\n\
76//!      ---\n\n\
77//!      # Definition\n",
78//! )
79//! .unwrap();
80//!
81//! // A bare `verified` mapping counts as a one-element list (§5.2).
82//! assert_eq!(doc.frontmatter.verified().len(), 1);
83//! assert_eq!(doc.frontmatter.trust_tier(), TrustTier::HumanReviewed);
84//! assert_eq!(doc.frontmatter.status().to_string(), "stable");
85//! ```
86//!
87//! [spec]: https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md
88
89#![forbid(unsafe_code)]
90#![warn(missing_docs)]
91// Pedantic and nursery lints keep the published crate tidy; the few cases
92// where a lint is genuinely wrong for this codebase are silenced inline with a
93// justification.
94#![warn(clippy::pedantic, clippy::nursery)]
95
96pub mod actor;
97pub mod bundle;
98pub mod computation;
99pub mod concept_id;
100pub mod date;
101pub mod diff;
102pub mod document;
103pub mod error;
104pub mod footnotes;
105pub mod frontmatter;
106pub mod index;
107pub mod links;
108pub mod log;
109pub mod provenance;
110pub mod trust;
111pub mod yaml;
112
113/// The OKF specification version this crate implements.
114pub const OKF_VERSION: &str = "0.2";
115
116/// Specification versions this crate can consume.
117///
118/// v0.2 is a minor bump over v0.1 (§12) with two documented supersessions
119/// (§13.1), both of which this crate still reads, so a v0.1 bundle loads and
120/// validates without special handling.
121pub const SUPPORTED_OKF_VERSIONS: [&str; 2] = ["0.1", "0.2"];
122
123#[doc(inline)]
124pub use actor::{Actor, ActorKind};
125#[doc(inline)]
126pub use bundle::{Bundle, Concept, RESERVED_FILENAMES, ResolvedLink, ResolvedSource};
127#[doc(inline)]
128pub use computation::{
129    ATTESTED_COMPUTATION_TYPE, AttestedComputation, Attester, ComputationSource, Executor,
130    InlineComputation, Parameter,
131};
132#[doc(inline)]
133pub use concept_id::{ConceptId, ConceptIdError};
134#[doc(inline)]
135pub use date::{Date, DateField, DateTime, DateTimeField};
136#[doc(inline)]
137pub use diff::{BundleDiff, FrontmatterChange, Rename, TrustChange, bundle_diff};
138#[doc(inline)]
139pub use document::Document;
140#[doc(inline)]
141pub use error::{BundleError, DocumentError};
142#[doc(inline)]
143pub use footnotes::{FootnoteDef, FootnoteRef};
144#[doc(inline)]
145pub use frontmatter::{
146    Frontmatter, KNOWN_FRONTMATTER_KEYS, LEGACY_FRONTMATTER_KEYS, PREFERRED_KEY_ORDER,
147    RECOMMENDED_FRONTMATTER_KEYS, REQUIRED_FRONTMATTER_KEYS,
148};
149#[doc(inline)]
150pub use links::{Citation, Link, LinkKind};
151#[doc(inline)]
152pub use log::Log;
153#[doc(inline)]
154pub use provenance::{Attribution, ResourceKind, Source, UsageWindow};
155#[doc(inline)]
156pub use trust::{Generated, Status, TrustTier, Verification};
157#[doc(inline)]
158pub use yaml::{Mapping, Value};
okf_core/lib.rs

okf_core/
lib.rs
