OpenRiC
An open specification for Records in Contexts (RiC) — implementation-neutral, IIIF-inspired.
OpenRiC defines how archival descriptions (ISAD(G), ISAAR(CPF), ISDIAH) map to Records in Contexts (RiC-CM / RiC-O), how RiC data is served for viewing, and how graph-based interfaces can render it consistently across different systems.
OpenRiC is not a product. It is a specification. Any system — AtoM, Heratio, Archivematica, a bespoke national-archive platform — can implement it.
Where we are
Current release: v0.1.0 · Status: draft, open for review · Last update: 2026-04-18
| Component | Status |
|---|---|
| Four specification documents (mapping, viewing API, graph primitives, conformance) | ✓ Published |
| JSON Schemas (12) | ✓ All entity responses + list + error + service-description |
| SHACL shape files (core + full-graph) | ✓ 254 + 31 triples |
Validator CLI (openric-validate) |
✓ Schema + SHACL + graph-invariant checks |
| Conformance fixture pack | ✓ 20 canonical fixtures |
| Reference implementation (Heratio) | ✓ 8 endpoint types live-validate |
| Live demo — browser-side viewer calling the reference implementation | ✓ 2D + 3D graph, interactive drill-down |
Standalone viewer package @openric/viewer |
✓ v0.1.0 published on npm — demo at viewer.openric.org |
| CI — unit tests, schema well-formedness, SHACL parse, Markdown links | ✓ GitHub Actions green |
| Frozen v0.1.0 release | ✓ Tagged — see CHANGELOG |
Condensed roadmap
Phase 1 — Frozen v0.1.0 (in progress)
Close out the spec’s machine-verifiable half: remaining 9 JSON Schemas, 19 fixtures, endpoint walker in the validator, CI pipeline, then tag v0.1.0. Target: ~3 weeks.
Phase 2 — Beyond the reference (in progress)
@openric/viewer is extracted and published to npm — this spec site’s own live demo now consumes it from CDN, not from local source. Remaining: demonstrate the viewer against a non-Heratio backend (portability proof) to complete the decoupling story. Target: ~1 month after Phase 1.
Phase 3 — Governance & external review
Invite spec editors from outside AHG. Engage with EGAD-adjacent reviewers. Freeze v1.0 when at least one non-reference implementation passes conformance. Target: 6+ months.
Beyond v1.0
- OpenRiC-Rights (ODRL-backed rights enforcement)
- OpenRiC-Preservation (PREMIS-equivalent event vocabulary)
- Jurisdictional extensions (POPIA, GDPR, CDPA, GRAP 103, etc.) — decoupled from the core
Detailed plans: ric-phase1-closeout-plan.md and ric-status-and-plan.md in the Heratio repository.
The four specification documents
| Document | Purpose |
|---|---|
| Mapping Spec | How to translate archival-description schemas into RiC-CM / RiC-O |
| Viewing API | REST + JSON-LD contract for delivering RiC for interactive viewing |
| Graph Primitives | Abstract concepts — node, edge, cluster, drill, layout hints |
| Conformance | JSON Schemas, fixtures, and a validator CLI |
All four are drafts. Open-ended feedback and proposals → GitHub Discussions. Concrete bugs or spec typos → Issues.
Reference implementation
Heratio is the first reference implementation of OpenRiC. The 2D and 3D graph viewer will be published separately as @openric/viewer, usable against any OpenRiC-conformant server.
Licence
- Specification — Creative Commons Attribution 4.0 (CC-BY 4.0)
- Reference implementation — GNU AGPL 3.0
Contact
Johan Pieterse — johan@theahg.co.za The Archive and Heritage Group (Pty) Ltd