S436 — OKF Conformance Check (our usage vs upstream OKF v0.1)

Task: does Canonical utilise OKF (Open Knowledge Format) correctly, per the latest upstream spec and our platform’s purpose? Read-only research. Upstream = OKF v0.1 (GoogleCloudPlatform/knowledge-catalog/okf). Ours = okf-record-model-v3.md §1/§7 + id-132 {132.1} PRODUCT / {132.2} TECH. Date: 02/07/2026. British English.

Plain-English summary (for a non-technical owner)

We are using OKF correctly, and legitimately calling it OKF — not merely “OKF-inspired”. Our bundle matches the upstream format on every structural point that matters (markdown files with frontmatter, index.md + log.md, a # Citations section, a references/ folder, one concept per file). We lift Google’s own reference tooling, which is the strongest possible conformance signal. Upstream explicitly intends the “map an AI agent traverses” use we built it for, so the fit is genuine, not a stretch.

There are only two things to fix and two to write down. Fix: (1) our house rule “UK dates (DD/MM/YYYY) everywhere in the bundle” breaks OKF’s requirement that the timestamp field and log.md use ISO dates (2026-07-02) — bodies can stay UK, but those two must be ISO; (2) we should stamp okf_version: "0.1" so any reader knows which OKF we target. Write down (document as deliberate, both are OKF-legal): our closed list of concept types enforced by a validator (OKF lets types be free-form — we are deliberately stricter), and our private canonical:// link scheme (OKF allows any link; ours just isn’t resolvable outside Canonical — no worse than OKF’s own example, which uses an un-dereferenceable Google Cloud console URL). Do not rename the format. One genuine simplification: OKF’s own examples use Metric and Playbook as ordinary type: values, so our plan to hide them inside tags: is a self-inflicted, spec-mistaken complication — drop it.

A. What upstream OKF actually is (v0.1 spec essentials)

Format (§4): every concept is one UTF-8 markdown file = YAML frontmatter (----delimited)
- markdown body. No YAML/JSON concept files; no binary.
Frontmatter (§4.1): type is the ONLY required field (a short free string). Recommended: title, description, resource (a URI that uniquely identifies the underlying asset), tags (YAML list for cross-cutting categorisation — separate from type), timestamp (ISO 8601). Producers MAY add any extra keys.
Concept types (§4.1): NO central registry, NO fixed taxonomy — producers SHOULD pick descriptive values. Spec’s own examples: BigQuery Table, API Endpoint, Metric, Playbook, Reference.
Linking (§5): ordinary markdown links between concepts (bundle-relative /… recommended) form an untyped directed graph. Citations (§8): claims sourced externally go under a # Citations heading; entries are absolute URLs, bundle-relative paths, or paths into a references/ subdirectory.
Bundle (§3/§6/§7): flat/nested <concept>.md files + two reserved filenames — index.md (optional, no frontmatter, progressive-disclosure directory listing, may be one per dir) and log.md (optional, ISO 8601 YYYY-MM-DD date-grouped change history).
Consumption (§1): “authored by people, generated by agents, exchanged across organizations, and consumed by both” — human-readable AND agent-parseable, no SDK/account required. Blog intent: solve fragmented internal knowledge / repeated agent context-assembly; a format, not a platform; vendor-neutral; explicitly “give your agents a shared markdown library”.
Conformance (§9): producers MUST emit parseable frontmatter with non-empty type + valid reserved-file structure; consumers MUST NOT reject for missing optional fields, unknown type, extra keys, broken links, or missing index.md. Deliberate producer-strict / consumer-permissive.
Versioning (§11): <major>.<minor>, currently 0.1; bundle-root index MAY declare okf_version. Ships: SPEC.md, README.md, LICENSE.md, pyproject.toml, 3 example bundles/ (+ viz.html), samples/ recipes, src/reference_agent/ (the producer POC), tests/. No standalone JSON schema and no standalone validator — validation lives in the reference agent.

B. Conformance matrix (our v3 / id-132 usage vs the spec)

#	Dimension	Upstream spec says	We do	Verdict
1	File format	Markdown + YAML frontmatter (§4)	Markdown concept files w/ frontmatter (BI-12)	CONFORMANT
2	Required fields	`type` only required; rest recommended (§4.1, §9)	Require type/title/description/timestamp + resource + tags; unpublishable if missing (BI-12/13)	CONFORMANT (producer superset, explicitly OKF-legal & documented, E8)
3	Type taxonomy	Free-form, no central registry (§4.1)	Closed set `{topic,product,company,certification,case_study}` enforced by validator (BI-4/13)	DELIBERATE-DIVERGENCE (producer-side strictness; OKF-legal)
3b	`type` encoding	`type` is a dedicated scalar; `Metric`/`Playbook` are example type values (§4.1)	Plan to carry metric/playbook in `tags:`, calling it “Google’s okf pattern”	ACCIDENTAL-DRIFT (misreads spec; spec uses them as `type:`)
4	`resource:` URI	”A URI that uniquely identifies the asset”; any scheme (§4.1); example = GCP console URL	`canonical://<table>/<uuid>` opaque vendor scheme (BI-6)	CONFORMANT (URI is scheme-free; caveat in C)
5	Citations	`# Citations` heading; URLs / bundle paths / `references/` (§8)	`# Citations` cite {source_document, reference_item, concept}; Pass-2 creates `references/<slug>` (BI-9/16)	CONFORMANT
6	Cross-concept links	Markdown links, bundle-relative graph (§5)	concept→concept by path (BI-9); resource/citation-centric	CONFORMANT (leans on citations more than inline-link graph)
7	Bundle structure	`index.md` + `log.md` reserved; progressive disclosure (§3/§6)	Exactly one `index.md` (themes→concepts) + one `log.md` (BI-11)	CONFORMANT (we mandate one root index; spec allows per-dir — stricter)
8	Date / timestamp format	`timestamp` ISO 8601 (§4.1); `log.md` ISO `YYYY-MM-DD` (§7)	House rule: UK DD/MM/YYYY throughout the bundle (BI-12, quality bars)	ACCIDENTAL-DRIFT (conflicts w/ ISO 8601 — real fix)
9	Consumption model	Human + agent, no SDK; cross-org interchange (§1)	Agent-traversal map, loaded wholesale + vector index; client-private (BI-24/25)	CONFORMANT (interchange dimension unused, not violated)
10	Producer-strict / consumer-permissive	§9 mandate	Strict write-gate; explicitly notes any future OKF consumer must be permissive (E8)	CONFORMANT (well-handled, spec-aware)
11	`okf_version` stamp	Bundle root MAY declare (§11)	Not mentioned anywhere in our docs	CONFORMANT (optional, unused — cheap interop win missed)
12	Concept “distil, never store”	Spec bodies freely embed schema tables (§4 example)	BI-1: concepts point, never store record content	DELIBERATE-DIVERGENCE (stricter; architectural, harmless to conformance)
13	Table/query resource form	Silent (any URI)	`canonical://q_a_pairs?scope_tag=…` novel query form (BI-8)	UPSTREAM-SILENT
14	Bundle licence	Format ships LICENSE.md; silent on produced-bundle licence	Bundle = client-owned private git repo (BI-14)	UPSTREAM-SILENT (owner’s call; fine)
15	Tooling reuse	reference_agent + viewer are the reference impl	Lift Source protocol/prompts/viewer + evaluate okf-skills validator + MarkdownFileset	CONFORMANT (aligns w/ upstream)

Verdict counts: CONFORMANT 9 · DELIBERATE-DIVERGENCE 2 · ACCIDENTAL-DRIFT 2 · UPSTREAM-SILENT 2 (of 15 dimensions; row 3b counted within the 15).

C. Fit assessment — is OKF the right tool for “the map agents traverse a client’s knowledge”?

Yes, and upstream directly intends this use. The blog frames OKF around exactly our problem — “every agent builder is solving the same context-assembly problem from scratch”, knowledge “locked behind whichever surface created it” — and prescribes “give your agents a shared markdown library that grows more useful over time”. Our L-concepts bundle is that library. OKF is positioned for three uses (agent traversal, cross-org data sharing, living wiki); we exercise the **agent-traversal

living-wiki** pair and simply don’t use the cross-org interchange leg. Not using a leg is not a violation — §9’s permissive posture and the private-bundle model both accommodate it.

Are we “OKF-inspired” or genuinely “OKF-conformant”? Genuinely conformant at the producer level, and it matters. We match §3–§8 structurally and lift Google’s actual reference_agent (Source protocol, prompts, viewer, MarkdownFileset, and evaluate their okf-skills validator) — you cannot get closer to a format than running its reference implementation. A generic OKF consumer can read our bundle today: frontmatter, bodies, tags, index.md, concept-path links all parse. The two things that would make us merely “inspired” are avoidable: the ISO-8601 date drift (the one change that could make a strict consumer mis-parse timestamp) and the un-dereferenceable canonical:// scheme — but the latter is no worse than the spec’s own example, which uses a Google Cloud console URL no outsider can resolve either, and §9 requires consumers to tolerate opaque/broken links. So calling it OKF is credible and defensible, preserving tooling-reuse and interchange credibility, provided we fix the date drift and document the deliberate supersets.

The two deliberate divergences (closed type set + validator; distil-never-store) are producer-side strictness the spec explicitly permits — they constrain what we emit, never what a consumer must accept, so they don’t cost conformance. They should be documented, not removed.

D. Recommendation — documented deliberate superset (conform on mechanics, write down the rest)

Not “rename” (we are genuinely conformant, and lift the reference impl). Not “conform fully by stripping our extensions” (the closed type set + validator are legitimate producer strictness worth keeping). The right posture is a documented deliberate superset/subset: fix the two mechanical drifts, then record the deliberate choices in a short CONFORMANCE note in the bundle.

Concrete changes:

Dates → ISO 8601 (fix ACCIDENTAL-DRIFT, row 8). Amend BI-12 / the quality bars: the timestamp frontmatter field and all log.md date grouping MUST be ISO 8601 (YYYY-MM-DD / RFC3339). Keep UK English + DD/MM/YYYY in concept body prose only. This is the single change that affects machine-readability by a strict OKF consumer.
Stamp okf_version: "0.1" in the bundle-root index.md frontmatter (§11) — one line, buys consumer version-negotiation and signals conformance intent.
Use the free-form type: field as OKF intends (fix row 3b) + add a CONFORMANCE.md note. Set type: metric / type: playbook directly (the spec’s own example types) instead of encoding them in tags: — simpler and more conformant; drop the “type-in-tags is the okf pattern” claim from BI-4. In a short bundle CONFORMANCE.md, document the two remaining deliberate supersets as OKF-legal: (a) a closed, validator-enforced type taxonomy (spec §4.1 allows free types — we are deliberately stricter at write time; our validator must never be used as a read gate on third-party OKF, per E8); (b) the canonical:// resource/citation scheme is a vendor-private, opaque, non-dereferenceable pointer (spec allows any URI; external consumers treat it as an opaque link per §9).

Net: two small fixes + one simplification + one documentation file convert us from “conformant with a latent date bug and undocumented supersets” to “cleanly, defensibly OKF-conformant v0.1”.