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, §5 — 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 (§9).
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 §9 asks of consumers.
  • Two levels of validation. §9-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 (§5, §8)
BundleWalk a tree, build the concept graph + backlinks (§3, §5)
IndexGeneratorGenerate index.md directory listings (§6)
ChangeLogParse / build log.md update histories (§7)
BundleValidator§9 conformance with severity-tagged diagnostics

cli.md — the same engine, as one AOT binary for CI