my_bundle/library.mdtype: Reference

Pure C#, zero dependencies.

OKF4net is implemented entirely on the .NET base class library — it brings its own YAML-subset parser, markdown link scanner, and directory walker. Nothing to audit but this one package.

##

Install

nuget.org/packages/OKF4net
$ dotnet add package OKF4net

One package, no transitive dependency tree. Targets modern .NET; every public API carries XML documentation.

##

Load a bundle, walk the graph

§3, §6 — Bundle · LinkScanner

Bundle.Load walks the directory tree, parses every concept, and builds the cross-link graph with backlinks. It is permissive by design: a bad file never aborts the load.

using OKF4net;

var bundle = Bundle.Load("./my_bundle");
Console.WriteLine($"{bundle.Count} concepts");

// Conformance check (§11).
var report = BundleValidator.Validate(bundle);
if (report.IsConformant)
    Console.WriteLine($"conformant with OKF v{OkfSpec.Version}");

// Traverse the cross-link graph.
var id = ConceptId.Parse("tables/orders");
foreach (var link in bundle.LinksFrom(id))
    Console.WriteLine($"{id} -> {link.Target} (exists: {link.Exists})");
foreach (var backlink in bundle.Backlinks(id))
    Console.WriteLine($"cited by {backlink}");

Parse failures are collected in ParseErrors; broken cross-links are retained as graph edges to non-existent concepts, so link.Exists tells you exactly where the holes are.

##

Parse and round-trip a document

§4 — OkfDocument · Frontmatter
using OKF4net;

var doc = OkfDocument.Parse("---\ntype: Metric\ntitle: DAU\n---\n\n# Body\n");
Console.WriteLine(doc.Frontmatter.Type); // "Metric"
doc.ValidateConformance(); // throws DocumentValidationException on failure

// Serialize() preserves frontmatter key order and the body.
var text = doc.Serialize();

Rather than deserializing into a fixed type — which would drop producer-defined keys — Frontmatter keeps the full ordered mapping and layers typed getters (Type, Title, Tags, …) on top. Round-trips preserve unknown keys, as the spec requires of consumers.

##

Design choices

what makes it faithful
  • Frontmatter preserves everything. The full ordered mapping survives; typed accessors are a view, not a projection.
  • Permissive loading. Bundle.Load collects errors and keeps going — exactly what §11 asks of consumers.
  • Two levels of validation. §11-only conformance, or the stricter producer-side check (type, title, description, timestamp).
  • A documented YAML subset. Block/flow collections, quoted and plain scalars, |/> block scalars, comments — and clear errors for anchors, tags, and multi-document streams, which frontmatter never uses.
##

API surface

one type per responsibility
Type / namespaceResponsibility
Yaml.YamlValue · YamlMappingYAML-subset value/mapping model for frontmatter
Yaml.YamlValue.Parse · YamlEmitterParser entry point and emitter for the same subset
OkfDocumentFrontmatter + body; parse / serialize / validate (§4)
FrontmatterTyped accessors over an order-preserving mapping (§4.1)
ConceptIdId ↔ path conversion and segment validation (§2)
LinkScannerMarkdown link extraction, classification, citations (§6, §13.1)
BundleWalk a tree, build the concept graph + backlinks (§3, §6)
IndexGeneratorGenerate index.md directory listings (§8)
ChangeLogParse / build log.md update histories (§9)
BundleValidator§11 conformance with severity-tagged diagnostics
Actor · Trust · Provenance · LifecycleProvenance, trust, and lifecycle value types (§5)
StalePolicyConsumer-side policy for stale concepts (§5.5)
BundleConceptWriterAtomic, per-path-locked, reparse-guarded concept writes — shared by Agents & Catalog
ConceptSearchThe full-text scorer shared by okf_search and the local catalog
ConceptAuditThe corpus-level trust/freshness/lifecycle query shared by okf audit and okf_audit

docs/library.md — every member, signature by signature · cli.md — the same engine, as one AOT binary for CI