OKGF v0.1: Open Knowledge and Governance Format

Author: welsbach

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+<!-- Thanks for contributing to OKGF. Keep PRs focused on one change. -->
+
+## What and why
+
+<!-- What does this change, and what problem does it solve? Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] The change keeps OKGF a strict superset of OKF (governance stays in `x-okgf-*`; bundles remain
+      valid OKF).
+- [ ] `python -m pytest tests/ -q` passes.
+- [ ] The example bundles still validate (`--strict`), and any new example passes the validator.
+- [ ] New or changed behaviour has a test.
+- [ ] No em/en dashes in Markdown or Python (CI rejects them).
+- [ ] Commits are signed off (`git commit -s`), per [CONTRIBUTING.md](../CONTRIBUTING.md) (DCO).

.github/workflows/conformance.yml

@@ -0,0 +1,25 @@
+name: conformance
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: python -m pip install -r requirements-dev.txt
+      - name: Validate example bundles (strict, with signature verification)
+        run: |
+          python tools/okgf_validate.py --strict \
+            --pubkey examples/governed/ORG_PUBKEY.pem \
+            examples/governed
+          python tools/okgf_validate.py --strict examples/minimal
+      - name: Run tests
+        run: python -m pytest tests/ -q

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+.pytest_cache/

CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Code of Conduct
+
+OKGF is a project of the OneHill Foundation. We want participation to be a welcoming, harassment-free
+experience for everyone, regardless of background or identity.
+
+## Our standards
+
+Examples of behaviour that helps the community:
+
+- Being respectful of differing viewpoints and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Focusing on what is best for the project and its users.
+- Showing empathy toward other community members.
+
+Examples of unacceptable behaviour:
+
+- Harassment, insults, or derogatory comments, public or private.
+- Personal or political attacks.
+- Publishing others' private information without permission.
+- Other conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Scope
+
+This applies in all project spaces (issues, pull requests, discussions, and any official channel) and when
+an individual is representing the project in public.
+
+## Enforcement
+
+Report unacceptable behaviour to **dev@onehill.org**. Reports are handled confidentially. Maintainers
+will review and respond, and may warn, remove content, or ban a participant for behaviour they judge
+inappropriate, threatening, or harmful.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

CONFORMANCE.md

@@ -0,0 +1,79 @@
+# OKGF Conformance
+
+This document defines what it means for a page or bundle to conform to **OKGF v0.1**, and how to check
+it with the reference validator in [`tools/okgf_validate.py`](tools/okgf_validate.py). The normative rules
+live in [`SPEC.md`](SPEC.md); this file restates them as a checklist and describes the tooling.
+
+## What conformance means
+
+OKGF is a strict superset of [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog). A conformant
+OKGF artifact is therefore a conformant OKF artifact that additionally respects the governance rules.
+
+### A conformant page
+
+1. Has a `---`-delimited YAML frontmatter block that parses as a YAML mapping.
+2. Declares a non-empty `type` (the only OKF-required field).
+3. For every governance field present, the value is within range:
+   - `x-okgf-scope` is one of `personal`, `team`, `org`
+   - `x-okgf-review` is one of `draft`, `proposed`, `approved`
+   - `x-okgf-tier` is one of `bronze`, `silver`, `gold`
+   - `x-okgf-sources` is a list of strings (URIs)
+   - `x-okgf-signature` is base64 that decodes to a 64-byte Ed25519 signature
+4. Preserves any unrecognized frontmatter keys (they are never an error).
+
+Governance fields are **optional**. A page that omits all of them is a conformant (ungoverned) OKGF page.
+
+### A conformant bundle
+
+1. Contains a root `index.md` whose frontmatter declares `okf_version`.
+2. `log.md`, `index.md`, `principles.md`, and `schema.md` are reserved and are not validated as content
+   pages.
+3. Every other `.md` file is a conformant page (above).
+
+### Signature verification (optional)
+
+`x-okgf-signature` is base64 Ed25519 over the UTF-8 bytes of:
+
+```
+<type>\n<title>\n<x-okgf-scope>\n<x-okgf-review>\n<body>
+```
+
+The verifying public key is distributed out of band. A present-but-invalid signature MUST be treated as
+untrusted (the validator reports it as an error when a key is supplied). An unsigned page is valid. When no
+key is supplied, the validator format-checks the signature and reports it as **unverified**, not trusted.
+
+## Checking conformance
+
+The reference validator needs Python 3.9+ and PyYAML. Signature verification additionally needs the
+`cryptography` package and a public key.
+
+```sh
+# Validate pages and/or bundle directories (structure + governance ranges):
+python tools/okgf_validate.py examples/minimal examples/governed
+
+# Also cryptographically verify signatures against an org public key:
+python tools/okgf_validate.py --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
+
+# Treat warnings (e.g. missing recommended OKF fields, unverified signatures) as failures:
+python tools/okgf_validate.py --strict examples/governed
+```
+
+Exit status is `0` when there are no errors (and, under `--strict`, no warnings), otherwise `1`. A usage or
+environment problem (bad key, missing dependency) exits `2`.
+
+### Errors vs warnings
+
+- **Errors** are conformance violations: missing frontmatter, empty `type`, an out-of-range governance
+  value, a malformed or cryptographically invalid signature, or a bundle whose `index.md` is missing or
+  does not declare `okf_version`.
+- **Warnings** are advisory: a missing recommended OKF field (`title`, `description`, `timestamp`), an
+  `okf_version` the validator does not recognize, or a signature that could not be verified because no key
+  was supplied.
+
+## Examples
+
+The [`examples/`](examples/) directory ships two bundles that are held conformant by CI:
+
+- `examples/minimal/` - the smallest valid bundle, OKF baseline with no governance.
+- `examples/governed/` - full governance: scoped/reviewed/tiered pages, provenance, and a real signed `org`
+  promotion with its public key (`ORG_PUBKEY.pem`).

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to OKGF
+
+Thanks for helping improve the Open Knowledge and Governance Format. OKGF is an open specification
+stewarded by the OneHill Foundation. This repo holds the spec, the conformance definition, examples, and
+the reference validator.
+
+## What contributions look like
+
+- **Spec clarifications or fixes** - wording, ambiguities, or errors in `SPEC.md` / `CONFORMANCE.md`.
+- **New or improved examples** - sample bundles under `examples/` that show a real pattern.
+- **Validator improvements** - bug fixes or checks in `tools/okgf_validate.py`, with tests.
+- **Proposed field or lifecycle changes** - larger changes to the governance model. Open an issue first
+  (see below) so we can discuss before you write it.
+
+Because OKGF is a superset of [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog), a change
+must not break OKF conformance.
+
+## Proposing a change
+
+1. **Open an issue** describing the problem or idea. For anything beyond a wording fix, agree on the
+   direction in the issue before writing a PR.
+2. **Branch and make the change.** Keep PRs focused on one thing.
+3. **Run the checks locally:**
+   ```sh
+   pip install -r requirements-dev.txt
+   python -m pytest tests/ -q
+   python tools/okgf_validate.py --strict examples/minimal
+   python tools/okgf_validate.py --strict --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
+   ```
+   New or changed behaviour needs a test. New example bundles must pass the validator (CI enforces this).
+4. **Open a pull request** against `main`. CI runs the validator and the test suite on every PR.
+
+## Style
+
+- Plain ASCII in Markdown and Python: no em dashes or en dashes (use `-`). CI rejects them.
+- Match the surrounding tone: concise and direct.
+
+## Sign your work (DCO)
+
+Contributions are accepted under a **Developer Certificate of Origin (DCO)**: your contribution is
+licensed to the project under its outbound license (**Apache-2.0**; see `LICENSE`). There is no separate
+copyright assignment.
+
+You certify the [DCO 1.1](https://developercertificate.org/) by adding a `Signed-off-by` line to each
+commit, matching your real name and email:
+
+```
+Signed-off-by: Your Name <you@example.com>
+```
+
+`git commit -s` adds it automatically. By signing off you state that you wrote the contribution or
+otherwise have the right to submit it under Apache-2.0.
+
+## License of contributions
+
+By contributing you agree that your contribution is licensed under **Apache-2.0**, the same license as the
+rest of this repository. Software that *implements* OKGF is licensed separately by its own project; that is independent of this spec's license.

GOVERNANCE.md

@@ -0,0 +1,47 @@
+# OKGF Governance
+
+OKGF is an open specification stewarded by the **OneHill Foundation**. This document describes how the
+spec is maintained and versioned. It governs *this repository*; it is separate from the governance model
+that OKGF the format describes (scope / review / trust for knowledge bundles).
+
+## Steward
+
+The OneHill Foundation maintains the specification, publishes releases, and holds the trademark and
+copyright for the OKGF name and text. The Foundation's role is to keep OKGF open, stable, and faithful to
+its goal: portable knowledge with portable trust, built as a clean superset of OKF.
+
+## Principles
+
+- **Superset, not fork.** Every version of OKGF remains a strict superset of a published OKF version. A
+  change that would break OKF conformance is out of scope.
+- **Additive and reserved.** Governance lives in the reserved namespace. Existing fields are
+  not repurposed; new capability is added, not mutated, so older bundles stay valid.
+- **Optional by default.** Governance fields are optional. An ungoverned bundle is always conformant.
+- **Implementable and testable.** A normative change ships with the conformance definition and validator
+  updates that let anyone check it.
+
+## Versioning
+
+OKGF uses a `MAJOR.MINOR` spec version (currently `0.1`), recorded in tagged releases and stamped by a
+bundle's `okf_version` in its root `index.md`.
+
+- **Minor** version: backwards-compatible additions (new optional field, new allowed value, clarified
+  wording). Existing conformant bundles stay conformant.
+- **Major** version: a change that could make a previously conformant bundle non-conformant. Avoided
+  wherever possible; requires a migration note.
+
+While OKGF is pre-1.0, minor versions may still refine field semantics; changes are announced on tagged
+releases.
+
+## Decision process
+
+- **Small changes** (wording, examples, validator fixes) are reviewed and merged by a maintainer via pull
+  request.
+- **Normative changes** (fields, values, lifecycle, signature format) start as an issue for discussion,
+  then a PR. The Foundation is the final arbiter and is responsible for keeping the spec coherent and the
+  superset relationship intact.
+
+## Relationship to implementations
+
+Implementations are licensed and governed
+independently. This repo defines the format they target; it does not govern their code.