How OpenRiC evolves
OpenRiC is run as an open specification with visible governance, not as a vendor product. This page describes who stewards the spec, how changes are proposed, how implementations influence decisions, and how external collaborators can take part.
Current state
OpenRiC is at v0.55.1 - a stable spec with one reference implementation, a live toolchain (viewer, capture, API explorer, conformance probe), and one related platform from the same maintainers (Heratio) that reads from it. The spec is published under CC-BY 4.0; the reference code is AGPL-3.0.
Governance is deliberately lightweight at this stage - the goal is to attract a second independent implementation before formalising. Heavy governance structures before that happens can deter the very contributors the project needs.
Roles
Maintainer
Currently: Dr Johan Pieterse (johan@theahg.co.za) - The Archive and Heritage Digital Commons Group (Pty) Ltd. Wrote the initial spec + reference implementation; operates ric.theahg.co.za; merges changes.
This is a single-maintainer-for-now model. It will change once additional stewards are invited (see the governance roadmap below).
Implementers
Anyone running a server that passes the conformance probe. Implementers have a strong voice in spec changes because their feedback is concrete: “this endpoint is ambiguous”, “this shape doesn’t round-trip”, “this constraint is impossible in our database”.
Contributors
Anyone who opens an issue, a discussion, or a pull request against the spec or any of the four ecosystem repositories. No CLA is required.
Reviewers (planned)
The next step in the governance roadmap is to invite 2-3 external spec editors - people with standing in the archival standards community (ideally EGAD-adjacent or running another implementation) - to form a small review group. Until that happens, major changes are circulated via Discussions before being merged.
How changes get made
Small changes (typo, clarification, broken link)
Open a pull request against the relevant repo. Merged if sensible.
Spec changes that affect conformance
Minor spec changes (new optional endpoint, new SHACL warning, relaxed constraint) happen via:
- GitHub Discussion with a concrete proposal (what changes, why, migration note if any).
- At least one week of visibility before merge, so implementers can object.
- Merged to the
mainbranch if no objection, and released with the maintainer’s approval line in the changelog, as change control requires.
Major changes (breaking shape change, new required endpoint, new conformance level) require:
- Discussion as above.
- Prototype implementation in the reference server before merging.
- Conformance fixture demonstrating the change.
- Explicit announcement tagged with the target version.
Breaking changes bump the minor version until v1.0; the major version after that.
Code changes to the reference implementation
PRs against openric/service (reference API) or any of openric/viewer, openric/capture, openric/spec are welcome under AGPL-3.0 / CC-BY 4.0 respectively. PRs that don’t touch the protocol contract can be merged at the maintainer’s discretion; PRs that do change the contract follow the spec-change process above.
Compatibility policy
The full policy is Change control: what carries a version, what each kind of change bumps, deprecation periods, migration notes, release approval and the signed change log, and which releases are supported. In short:
v0.xseries - Breaking changes bump the minor version and need a migration note. Implementations advertise what they support per profile, each carrying its own version (e.g.{ "id": "core-discovery", "version": "0.5.0", "conformance": "full" }), so a profile can stabilise without waiting for the spec as a whole.v1.0onward - Breaking changes only on major version bumps. Deprecated items stay until the next major release.- JSON Schemas, SHACL shapes, the API contract - versioned with the spec. A server claiming conformance to a given spec version MUST validate against that version’s shape files.
How to contribute feedback
| I want to… | Do this |
|---|---|
| Report a bug in the spec | Open an issue |
| Propose a new endpoint / change | Open a Discussion first; PR after the discussion settles |
| Share an implementation experience | Discussion #2 - “second-implementer questions” |
| Push back on the mapping | Discussion #3 - “mapping sanity-check” |
| Ask a general question | Open a Discussion (the Q&A category) |
| Propose yourself as a spec editor | Email the maintainer directly with a short motivation + implementation or archival-standards background |
Becoming a conformant implementation
You don’t need permission - run the conformance probe:
git clone https://github.com/openric/spec
BASE=https://your.server/api/ric/v1 \
bash conformance/probe.sh
Add KEY=your-write-key to test the write surface too, on a server whose data you may change.
If it passes, you can publicly claim OpenRiC v0.55.1 conformance for the profiles the probe covered. If you’d like your server listed on openric.org as a known implementation, open a Discussion with the URL and a one-paragraph context note - and we review it for listing on related implementations.
Roadmap for governance itself
| Phase | When | What |
|---|---|---|
| Now | to the Standard Acceptance Gate | Single maintainer; change control in force since 2026-10-15; an external technical review of the specification before the gate is signed. |
| Next | after the gate, to v1.0 | Invite 2-3 external spec editors. Formalise a proposal template. Add an implementation registry. Move to a MAINTAINERS.md file. |
| v1.0 | when a second implementation exists and passes conformance | Cut v1.0. Freeze the core contract. Major changes only on major bumps. |
| Post-v1.0 | later | Move governance to a working group or steering committee if community size warrants. Adopt a CoC if the contributor base grows beyond a handful. |
Why lightweight for now
Heavy governance ahead of community is cargo cult. Until OpenRiC has:
- A second independent implementation passing conformance,
- At least one external institution committing to deploy,
- 2-3 active non-maintainer contributors with sustained engagement,
…formal working groups would add process without matching substance. The current model gets the spec out, the tools public, and the probe in adopters’ hands. When those three adoption signals arrive, governance scales up accordingly.
Release gates and maturity goals
These are two different lists, and only the first decides when v1.0 is cut.
The gate for v1.0 is a single condition: a second implementation, built independently of the maintainers, passes the conformance probe for at least one profile. “Independently” means by people outside The AHG; the reference service, the planned OpenRiC Workspace and Heratio all come from the same organisation, so none of them counts (known issue K-6). Before the gate, every release still follows change control, and the Standard Acceptance Gate has its own sign-off.
The maturity goals are the adoption signals above: an institution committing to deploy, and outside contributors with sustained engagement. They decide when governance grows - external editors, a working group, a code of conduct - not when the version number changes. v1.0 can come before them, and they can arrive before v1.0.
Licence
Specification: CC-BY 4.0. Reference implementation + viewer + capture client + conformance probe: GNU AGPL-3.0.
Contributors retain copyright in their contributions. By opening a PR you agree to license your contribution under the same terms.
Contact
- Mailing list: currently via GitHub Discussions
- Maintainer: Dr Johan Pieterse - johan@theahg.co.za