Governance and contributing

A short, honest clarification first, because it governs everything else: the standard does not belong to this site. The Open Knowledge Format is maintained as an open, vendor-neutral draft in the Google Cloud Platform repository. That is where the authoritative text lives and where changes are decided.

The OKF Knowledge Hub on this site is a consumer and producer of the format, not a governance body. It demonstrates that OKF is usable at the consumption end, and it feeds practical feedback back to the standard. This page documents the path there.

Why OKF is "governed" at all

The entire point of a format is interoperability. One producer writes a bundle; a completely different consumer reads it years later. That only works if the few binding rules stay stable and changes are traceable. So OKF has an explicit versioning model and an open contribution path instead of silent adjustments.

The model is deliberately conservative. A minor bump (0.1 → 0.2) only adds in a backward-compatible way: new optional fields, new conventional section headings. Existing bundles stay valid. A major bump may break – rename a required field, change a reserved filename – and will accordingly be rare and announced in advance.

The contribution path

OKF uses the path software standards have used for years: an open RFC process over version control. Anyone who wants to change or add something proceeds in four steps.

1. Problem benennen. Ein Issue im Repository beschreibt den konkreten Fall: Welches reale Bundle lässt sich mit der heutigen Spec nicht sauber ausdrücken? Ein Vorschlag ohne Problem hat keinen Hebel. / State the problem. An issue in the repository describes the concrete case: which real bundle cannot be expressed cleanly under today's spec? A proposal without a problem has no leverage.
2. Lösung skizzieren. Ein Vorschlag zeigt die vorgeschlagene Regel, ein Vorher-nachher-Beispiel und die Auswirkung auf Konformanz und Kompatibilität. / Sketch the solution. A proposal shows the proposed rule, a before-and-after example, and the effect on conformance and compatibility.
3. Diskutieren und anpassen. Öffentliche Diskussion am Issue oder Pull Request. Gegenargumente, Grenzfälle, Formulierung. / Discuss and revise. Public discussion on the issue or pull request. Counterarguments, edge cases, wording.
4. Einarbeiten und versionieren. Angenommene Änderungen landen in SPEC.md und erhalten die passende Versionsnummer nach dem Minor/Major-Schema. / Merge and version. Accepted changes land in SPEC.md and receive the appropriate version number under the minor/major scheme.

What makes a good proposal

The spec has a clear stance: minimally opinionated. It standardizes only the few structural conventions that make a knowledge corpus self-describing. Everything beyond that stays with the producer. A proposal asking for a new required field therefore carries a heavy burden: it must show that every consumer needs the field, not just one.

Two questions separate viable proposals from the rest. Does the change solve a problem shared by several independent producers or consumers? And can it be framed as an optional, backward-compatible addition rather than devaluing existing bundles? Two yeses is the usual case for adoption.

Extending without changing the spec

Often a proposal needs no spec change at all. The extension rule lets producers set arbitrary additional frontmatter keys; consumers should preserve rather than reject them. So anyone needing a new field can simply set it and use it in their own bundle. Only when several parties introduce the same field independently is it worth taking it into the spec, so everyone names it the same way.

That is exactly how this project's v0.2 profile came to be: the classification fields category, domain, word_count and the trust layer generated, verified, status, stale_after, sources. All extensions over the open base, not a spec change. A bundle carrying them stays fully conformant for any other consumer.

How this site contributes

The role here is that of a vocal practitioner. The Hub processes real bundles – imported from Notion, Obsidian, Logseq, and Confluence, enriched, read, queried. Where a limit of the spec becomes visible, it is documented as an issue in the upstream repository, with the concrete bundle as evidence. Practice beats opinion: a proposal with a real, failed case weighs more than a theoretical improvement.

Continue

The versioning model in detail is in the OKF specification, versioning section. Changes to this site and the Hub are listed in the changelog. The upstream repository with issues and pull requests is on GitHub.