OKF Compliance as a Superset (Pinned OKF v0.1)
ADR-009: OKF Compliance as a Superset (Pinned OKF v0.1)
Section titled “ADR-009: OKF Compliance as a Superset (Pinned OKF v0.1)”Status
Section titled “Status”Accepted
Context
Section titled “Context”Background and Problem Statement
Section titled “Background and Problem Statement”The Open Knowledge Format (OKF) defines a minimal interoperability surface — a
directory of .md files with YAML frontmatter, a single required type field,
a concept graph of standard markdown links, and the reserved filenames
index.md and log.md. OKF deliberately refuses to define a content model:
typed relationships, contradiction/merge semantics, trust tiers, provenance, and
stale-vs-live handling are all left as open design space.
MIF supplies exactly that missing content model. The architectural question is how MIF should relate to OKF: should MIF subordinate itself to OKF (depending on whatever OKF publishes next), or position itself as an independent specification that remains interoperable with OKF?
Current Limitations
Section titled “Current Limitations”- OKF is an evolving draft. A normative dependency on “OKF, latest” would make MIF’s own conformance non-deterministic — an upstream edit could silently invalidate previously-conformant MIF bundles.
- Without an explicit relationship, “MIF is OKF-compatible” is an unverifiable marketing claim rather than a tested property.
- Consumers need to know which artifacts are OKF-legible (the
.mdconcept files) and which are MIF-specific overlays (typed relationships, the JSON-LD projection), so a generic OKF reader is never confused by MIF extensions.
Decision Drivers
Section titled “Decision Drivers”Primary Decision Drivers
Section titled “Primary Decision Drivers”- Determinism: MIF conformance must be reproducible and not drift when the upstream OKF draft changes.
- Interoperability: Every MIF bundle must be readable by a generic OKF consumer with no MIF-specific knowledge.
- Independence: MIF must retain its own identity model, governance, and release cadence.
Secondary Decision Drivers
Section titled “Secondary Decision Drivers”- Auditability: The OKF relationship should be machine-checkable, not prose-only.
- Forward compatibility: Adopting a newer OKF revision should be a deliberate, reviewable act — never an accident.
Considered Options
Section titled “Considered Options”Option 1: Subordinate MIF to OKF (normative dependency on the live draft)
Section titled “Option 1: Subordinate MIF to OKF (normative dependency on the live draft)”Description: Treat the current upstream OKF document as normative; MIF conformance is defined as “whatever OKF requires now, plus MIF additions.”
Technical Characteristics:
- No pinned criteria; MIF defers to upstream wording.
- MIF releases would need to chase OKF revisions.
Advantages:
- Always “current” with OKF.
- No duplicated criteria text to maintain.
Disadvantages:
- Non-deterministic conformance: an upstream edit can break MIF bundles.
- MIF loses independent governance.
- Conformance cannot be pinned to a MIF version for reproducible validation.
Risk Assessment:
- Technical Risk: High. Validation results depend on an external moving target.
- Schedule Risk: High. MIF releases blocked on upstream cadence.
- Ecosystem Risk: Medium. Consumers cannot rely on a stable contract.
Option 2: Fork OKF (define a MIF-only bundle shape, drop OKF legibility)
Section titled “Option 2: Fork OKF (define a MIF-only bundle shape, drop OKF legibility)”Description: Define MIF’s own bundle shape and abandon the goal of generic OKF readability.
Advantages:
- Maximum design freedom.
Disadvantages:
- Sacrifices the interoperability that motivates using OKF at all.
- A generic OKF consumer can no longer read MIF bundles.
Risk Assessment:
- Technical Risk: Low to build, High to the value proposition.
- Ecosystem Risk: High. Interoperability is the whole point; forking discards it.
Option 3: Superset with a pinned OKF v0.1 (chosen)
Section titled “Option 3: Superset with a pinned OKF v0.1 (chosen)”Description: MIF is a strict superset of a conformant OKF bundle. MIF embeds
a pinned copy of OKF v0.1’s conformance criteria (docs/okf-conformance.md),
normative within MIF, and takes no normative dependency on OKF’s evolving
draft. Adopting a newer OKF revision requires an explicit MIF revision.
Technical Characteristics:
- Every MIF concept is a valid OKF concept; every typed MIF relationship also appears as a plain OKF-legible markdown link.
- The pinned criteria are frozen text, versioned with MIF.
Advantages:
- Deterministic, reproducible conformance tied to a MIF version.
- Generic OKF readers work unchanged.
- MIF keeps independent identity and governance.
- The relationship is testable (see ADR-012).
Disadvantages:
- The pinned criteria text must be deliberately updated to track future OKF.
- Slight duplication between upstream OKF and the pinned copy.
Risk Assessment:
- Technical Risk: Low. The contract is frozen and machine-checkable.
- Schedule Risk: Low. MIF releases are decoupled from upstream cadence.
- Ecosystem Risk: Low. Stable, documented contract for consumers.
Decision
Section titled “Decision”MIF achieves OKF compliance as a superset, not by subordination. Every MIF bundle MUST validate as a conformant OKF bundle, but MIF remains an independent specification with its own identity model and governance.
MIF takes no normative dependency on OKF’s evolving draft. It pins OKF v0.1’s
conformance criteria in docs/okf-conformance.md, which is normative within
MIF (SPECIFICATION.md, Invariant 5 — “No
floating dependency on OKF”). A future MIF revision MAY replace that pinned
section with newer upstream text, but only as a deliberate, reviewed act.
The superset relationship is made concrete by the MIF → OKF mapping
(docs/okf-conformance.md §2): concept files map to OKF concepts, the
frontmatter type satisfies OKF’s required field, typed relationships[] are a
MIF overlay on plain OKF markdown-link edges, and the JSON-LD projection uses the
.jsonld extension so it falls outside OKF’s *.md glob.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Deterministic conformance: Validation is reproducible against a frozen criteria set tied to the MIF version.
- Generic interoperability: A plain OKF consumer reads every MIF bundle without MIF-specific code.
- Independent governance: MIF evolves on its own cadence; OKF adoption is explicit.
- Testable claim: “OKF-compliant” becomes a CI-enforced invariant (see ADR-012), not marketing.
Negative
Section titled “Negative”- Maintenance of pinned text: Tracking a future OKF version is a manual, deliberate revision.
- Apparent duplication: The pinned criteria restate the upstream surface.
Neutral
Section titled “Neutral”- Two artifact classes:
.mdconcepts are OKF-legible; the.jsonldprojection and typed-relationship overlay are MIF-only — by design.
Decision Outcome
Section titled “Decision Outcome”The superset-with-pinned-v0.1 approach achieves the primary drivers: determinism (frozen criteria), interoperability (generic OKF legibility), and independence (own governance). Mitigations:
- The “no floating dependency” rule (Invariant 5)
is documented at the top of
docs/okf-conformance.mdand in SPECIFICATION.md’s Abstract. - The relationship is enforced mechanically by
scripts/okf_validate.pyand the lossless round-trip, gated in CI (ADR-012).
Related Decisions
Section titled “Related Decisions”- ADR-010: Repositioning to Modeled Information Format — establishes MIF’s independent identity that this superset relationship presupposes.
- ADR-011: Markdown-Canonical with Derived JSON-LD — the
.jsonldprojection stays outside OKF’s*.mdsurface. - ADR-012: OKF Conformance as a Tested Invariant — makes this decision machine-checkable.
- ADR-001: Cognitive Triad Taxonomy — the base-type taxonomy is MIF’s answer to OKF’s deliberately-absent concept-type system.
- ADR-008: Decay Model Rationale — validity/freshness is MIF’s answer to OKF’s open “stale-vs-live” question.
docs/okf-conformance.md— the pinned OKF v0.1 conformance criteria, normative within MIF (the authoritative source; upstream OKF wording is reconstructed/frozen here per that document’s provenance note).
More Information
Section titled “More Information”- Date: 2026-06-18
- Source: SPECIFICATION.md Abstract (“MIF answers OKF’s open questions”) and Invariant 5;
docs/okf-conformance.md. - Related ADRs: ADR-010, ADR-011, ADR-012, ADR-001, ADR-008
Findings cite durable anchors (heading text), not raw line numbers — line
numbers in SPECIFICATION.md and docs/okf-conformance.md shift as
unrelated content is added, which had already made this entry’s original
citations stale by the 2026-07-11 audit below (see that entry’s Summary).
grep -n for the quoted anchor text to find its current line.
2026-06-18
Section titled “2026-06-18”Audited revision: 7f8d2de6c671cf5f354e4034b1524c0c112ddf1f
Status: Compliant
Findings:
| Finding | Files | Reference | Assessment |
|---|---|---|---|
| Superset-not-subordination and “no normative dependency / pin OKF v0.1” stated normatively | SPECIFICATION.md |
the Abstract paragraph beginning “OKF compliance is achieved as a superset, not by subordination” | compliant |
| Invariant 5 (“normative within MIF”) pinned criteria document present | docs/okf-conformance.md |
document heading “# OKF Conformance (pinned)” plus the phrase “normative within MIF” in the sentence following it | compliant |
Pinned OKF v0.1 criteria enumerated (bundle shape, required type, reserved filenames, concept graph, broken-links-tolerated) |
docs/okf-conformance.md |
heading “## 1. Pinned OKF v0.1 criteria” | compliant |
MIF → OKF mapping (typed relationships overlay OKF links; .jsonld outside *.md glob) |
docs/okf-conformance.md |
heading “## 2. MIF → OKF mapping” | compliant |
| “MIF answers OKF’s open questions” positioning table | SPECIFICATION.md |
heading “### MIF answers OKF’s open questions” | compliant |
Summary: The superset relationship, the pinned-v0.1 / no-floating-dependency rule (Invariant 5), and the MIF→OKF mapping are all present and normative in the specification and the pinned conformance document.
Action Required: None.
2026-07-11
Section titled “2026-07-11”Audited revision: 88b4a8f20d87773286abbc64644f4d5c762f6ce8
Status: Compliant
Findings:
| Finding | Files | Reference | Assessment |
|---|---|---|---|
| Superset-not-subordination and “no normative dependency / pin OKF v0.1” stated normatively | SPECIFICATION.md |
the Abstract paragraph beginning “OKF compliance is achieved as a superset, not by subordination” | compliant |
| Invariant 5 (“normative within MIF”) pinned criteria document present | docs/okf-conformance.md |
document heading “# OKF Conformance (pinned)” plus the phrase “normative within MIF” in the sentence following it | compliant |
Pinned OKF v0.1 criteria enumerated (bundle shape, required type, reserved filenames, concept graph, broken-links-tolerated) |
docs/okf-conformance.md |
heading “## 1. Pinned OKF v0.1 criteria” | compliant |
MIF → OKF mapping (typed relationships overlay OKF links; .jsonld outside *.md glob) |
docs/okf-conformance.md |
heading “## 2. MIF → OKF mapping” | compliant |
| “MIF answers OKF’s open questions” positioning table | SPECIFICATION.md |
heading “### MIF answers OKF’s open questions” | compliant |
Summary: Re-verified every finding against current file content, not just
against a resolving citation. Both cited source files (SPECIFICATION.md,
docs/okf-conformance.md) are functionally unchanged since 2026-06-18.
SPECIFICATION.md still self-declares “Last Updated: 2026-06-18”;
docs/okf-conformance.md carries no such field (it instead self-declares
“Conforms to OKF v0.1, criteria copied 2026-06”), but its content is likewise
unchanged since the 2026-06-18 audit. The only observed drift is line-number
shift from unrelated edits elsewhere in the same files (e.g. the positioning
table moved from ~L49-57 to ~L50-58), exactly the class of churn durable
anchors are meant to survive. The pinned-OKF-v0.1 criteria (§1), the
MIF→OKF mapping (§2), and the positioning table’s row content (Supersedes/
ConflictsWith, sourceType/trustLevel, TTL/freshness) were spot-checked
against SPECIFICATION.md §8 and the schema, not just re-cited — all still
match. All five related ADRs (ADR-010, ADR-011, ADR-012, ADR-001, ADR-008)
remain status: accepted; none have been superseded or renumbered, so no
update to this ADR’s related: frontmatter or Related Decisions section is
needed. ADR-012’s own 2026-07-11 re-audit found one real discrepancy
(validate-ontologies job scope, tracked as #240), but that finding is
scoped to .github/workflows/validate.yml, which this ADR does not cite —
it does not affect any finding here. One pre-existing, non-blocking gap
independently confirmed during this audit (not a change since 2026-06-18):
“Invariant 5” and “Invariant 2” (and others, 1-6, cited across the repo) are
referenced by number in prose throughout SPECIFICATION.md and several
ADRs, but no enumerated invariants list exists anywhere defining them
collectively — filed as
#252. This
doesn’t invalidate the finding above (the citation itself resolves fine); it
is a gap in what the citation points at, not in this ADR.
Action Required: None for this ADR. See #252 for the separately-tracked “Invariant 5 cited but not enumerated” gap.
2026-07-11 (follow-up)
Section titled “2026-07-11 (follow-up)”Audited revision: 252767a724a20771555942afc25a622c5b7ab1a9
Status: Compliant
Findings:
| Finding | Files | Reference | Assessment |
|---|---|---|---|
| Canonical enumerated Invariants list now exists; this ADR’s Invariant 5 citations link to it | SPECIFICATION.md, adr/ADR-009-okf-compliance-superset.md |
SPECIFICATION.md’s ### Invariants section; the two Invariant 5 citations in this ADR’s Decision Outcome and Consequences/Negative sections |
compliant |
Summary: #252 is fixed: SPECIFICATION.md now has a ### Invariants
section enumerating Invariants 2-6 (no citation anywhere in the repo names
an Invariant 1 or 7+), and this ADR’s own Invariant 5 references now link to
it. Issue #252 closed.
Action Required: None.