Proposal: an opt-in `okf_profile` declaration (parallel to `okf_version`) — plus a spec clarification on root-index frontmatter keys

[jpavley]

Summary

§9's conformance surface is deliberately minimal: parseable frontmatter, non-empty type, reserved-file structure. Everything else about authoring quality is left to producers — so every serious producer builds a private validation layer. This tracker is itself the evidence: #196 (okft) is an independently built community linter, and we built our own before finding it.

Proposal: give that layer a name the format understands — an optional, domain-scoped profile declaration — and clarify one spec seam it depends on.

The proposal (opt-in, advisory, no consumer change)

A bundle MAY declare, in root-index frontmatter beside okf_version:

okf_version: 0.1
okf_profile: civic-v1

A profile is a producer-published document that pins, for one domain: a type vocabulary, any required-beyond-type fields, and lint rules. Consumers that don't know the profile ignore the key — exactly the okf_version mechanism §11 already established. Nothing becomes rejectable; profile checks are authoring-time warnings, never consumer-side errors. This is deliberately NOT a central or mandatory type registry (an explicit spec Non-goal) — profiles are domain-scoped, opt-in, and live with their producers.

Why it's worth a spec-level convention rather than staying private: interop between the authoring tools this ecosystem is already growing. A linter like #196's okft could read a declared profile and apply the domain's rules instead of only generic hygiene checks; two producers in the same domain could share one profile instead of two private validators.

The spec clarification this depends on

We hit a genuine ambiguity implementing this: may a producer key appear in root-index frontmatter at all? §4.1's extension-key permission governs concept documents; §6 says index files contain no frontmatter; §11 carves an exception for okf_version in the root index — and is silent on additional keys. okf_profile (or any bundle-level producer key) has no clearly legal home. A one-line clarification in §6 or §11 — "the root index MAY carry additional producer keys beside okf_version" (or "MUST NOT," and bundle-level metadata belongs somewhere else) — would settle it either way.

Evidence

We publish an OKF v0.1 bundle of local-government public records for a large county in the US Northeast (~230 concepts), authored under a civic-v1 profile: a pinned civic type vocabulary, per-type required fields, a typed-relation vocabulary (see comment on #148), and a linter that warns on broken links, missing resource/description, orphan concepts, and index-vs-atom drift. The profile mechanism is what lets us keep the bundle strictly v0.1-conformant while enforcing domain rules — a compatible superset, not a fork. Our validator predates #196's okft and overlaps it heavily, which is the reinvention problem in miniature.

Happy to contribute the validator as a reference implementation, or draft the profile-mechanism text, if maintainers are interested.

[andrewcrenshaw]

Supporting this, both halves - the okf_profile key and the §6/§11 clarification it depends on.

On the clarification, one piece of producer evidence: our exporter (the remember wiki compiler at Lexenne, the producer behind #182 and PR #195) hit the same ambiguity when we implemented our bundle's root index. We wanted the root index to carry bundle-level keys, could not tell from §6/§11 whether anything beside okf_version was legal there, and resolved it conservatively - we emit okf_version and nothing else. An explicit MAY (with consumers ignoring unknown keys, per §4.1) would have settled in one line what we settled by guessing. okf_profile reads as exactly the key that exception exists for.

On the mechanism itself: we would be the second producer to use it, in a second domain. Our bundles carry agent-memory conventions that already have homes across these threads - the reliability object and its basis vocabulary (#151/#159), the validity window (#159), and the two lifecycle edges with their query-time semantics (#148, now PR #195). A memory/0.1 profile would pin that set as the authoring convention for agent-memory bundles: a type vocabulary, the required-beyond-type fields, and lint rules - warnings at authoring time only, per your framing, never something a consumer rejects. Notably it would mint nothing new; it only names a set that already exists, which I take as a sign the profile mechanism is the right size.

Your civic-v1 (local-government records) and a memory/0.1 (agent memory) would then be two profiles from independent producers in unrelated domains - the cleanest demonstration that the mechanism generalizes. Happy to write ours up as a published sample alongside yours; its lint rules would slot into the lint-affordances section PR #195 added last week.

[1wgrumph]

Building on the “compatible superset, not a fork” idea, I think it would help to make one thing explicit: OKF conformance and profile warnings should be reported separately.

A bundle might pass OKF v0.2 while civic-v1 reports a missing field. That warning shouldn’t be described as OKF nonconformance. Likewise, passing the profile shouldn’t override a real OKF failure.

I’m not suggesting a central registry or standard result format—just a short note in §11 that keeps those results separate. Would that be useful?

[andrewcrenshaw]

Useful, yes - and worth stating in both directions, which you already have: a profile warning is never core nonconformance, and a profile pass never rescues a core failure. Two verdicts, one bundle, no arithmetic between them.

Section 11 already has the right posture for the note: it enumerates what a consumer MUST NOT reject a bundle for, and unknown keys are on that list. A sentence alongside it - profile-declared checks report on the profile's own axis and leave the §11 verdict untouched - closes the loop without a registry or a standard result format, exactly as you say.

One practical consequence that makes the separation worth having: a consumer selecting bundles can compose the two verdicts as independent predicates ("conformant AND civic-v1-clean" for a strict ingest, "conformant, profile warnings logged" for a tolerant one). Merge them and neither selection is expressible. The conformance fixture we're building for the remember exporter keeps the two as separate outputs for the same reason.

The two clarifications in this issue would also land well together: a declared okf_profile needs a defined place to be declared (the §6/§11 root-index question upthread), and a profile verdict needs a defined boundary to be computed over - which is the line #232 is now drawing.