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

okf_core/
lib.rs
