Records in Contexts, served over HTTP — implementation-neutral, IIIF-inspired.
OpenRiC is an open specification for how archival descriptions map to RiC-CM / RiC-O, how that data is served over HTTP for both reading and writing, and how graph-based interfaces can render it consistently across any conformant server. Not a product. A contract anyone can implement.
In plain language: OpenRiC lets different archival systems publish, exchange, validate, and explore RiC-based archival data in a consistent way. It's a shared contract — like IIIF for images, but for archival description. Any system that implements it can be read, written to, and graph-walked the same way.
See it in action
Open the live 2D/3D viewer against a real archival dataset — no install, no signup. The viewer talks to ric.theahg.co.za/api/ric/v1, the public reference implementation. Click Browse for curated seed entities, or paste any path.
How the pieces fit together
Four base documents, seven normative profiles (one draft), JSON Schemas, SHACL shapes, a 27-case fixture pack, an OpenAPI 3.0 contract, and a black-box conformance probe. CC-BY 4.0. Versioned; v0.37.0 is current (RiC-O 1.1 conformant).
One Laravel service that implements the OpenRiC contract. Real archival data behind it. 46 endpoints across full 8-entity CRUD (Records, Agents, Places, Rules, Activities, Instantiations, Repositories, Functions), OAI-PMH, auto-generated OpenAPI. AGPL-3.0. Anyone can run their own.
Three pure-browser apps that talk to any conformant server — not just the reference. 2D + 3D graph rendering, data capture, Swagger UI. No privileged access; they use the same HTTP contract adopters see.
An existing GLAM platform that consumes the Reference API over HTTP for every mutating admin action — no special shortcut. Proves the contract is sufficient for a real, production archive. Independent AGPL project.
If you only remember one thing: OpenRiC is the contract; Heratio is one consumer of that contract. The contract is deliberately designed so that any archival system — not just Heratio — can speak it.
Who is this for?
You want to read data, write data, or build a client. Start with the 15-min walkthrough, then the API Explorer.
You're evaluating whether OpenRiC is worth adopting, requesting from vendors, or endorsing. Non-technical 3-min brief.
You care about ISAD(G) / ISAAR / ISDF / ISDIAH → RiC mapping. Read the mapping doc first, then the graph primitives.
You want to build a conformant server, submit a spec change, or steward the project. See how governance + conformance work.
Start here — evaluate OpenRiC in 5 minutes
Zero to working integration: reads, writes, graph, harvest, embed.
Full 8-entity CRUD (46 endpoints): Records, Agents, Places, Rules, Activities, Instantiations, Repositories, Functions.
Click any node to drill into its RiC-O neighbourhood. Same data, visual.
Swagger UI over the OpenAPI 3.0 spec. "Try it out" on every endpoint with your own key.
Pure bash + jq. Point at any OpenRiC server; get a pass/fail report across every required endpoint.
Four short documents: mapping, viewing API, graph primitives, conformance.
Four public deployments
These are the four independently-hosted, separately-licensed, interoperable surfaces that make up the OpenRiC ecosystem. Any one of them can be replaced by a third-party implementation without touching the others — that is the point.
Specification live
Four documents, 19 JSON Schemas, SHACL shapes, 27-case fixture pack, validator CLI, conformance probe, OpenAPI 3.0 contract. CC-BY 4.0.
Viewer live
2D + 3D graph rendering for any conformant server. Drives Heratio's reference API and a non-Heratio static-fixture backend in the same page.
Capture live
Pure-browser data-entry client. Paste a server URL + API key, create Places, Rules, Activities, Instantiations, relations.
Reference API live
Independently-deployed Laravel service backed by a real archival database. 46 endpoints across read/write/OAI-PMH with full 8-entity CRUD, X-API-Key auth, auto-generated OpenAPI at /api/ric/v1/openapi.json. Also hosts a live RiC-CM reference navigator at /reference/ric-cm/ — SPARQL-backed, declared-vs-inherited separation, versioned URLs.
Pages on openric.org
These live inside the specification site itself — interactive tools, reference material, and evidence pages layered on top of the four deployments above.
API Explorer live
Interactive Swagger UI. Point at any OpenRiC server, paste an API key, try every endpoint live from the browser.
Conformance Suite live
Black-box probe: point at any server, get a pass/fail report across every documented endpoint. Pure bash + jq.
Browse demo live
Live catalogue view — cards, per-type filters, pagination. Points at any OpenRiC server; click-through to the graph viewer.
Proof of implementation live
Real numbers, end-to-end walkthrough, ISAD(G) → RiC-O mapping, one live example per RiC-O type. The evidence the contract works.
Profiles v0.3-draft
Named, bounded conformance targets. Implement the subset you can support — Core Discovery is the minimum. Five more profiles planned.
Condensed roadmap
Spec v0.1.0 frozen done
Four documents, 12 JSON Schemas, 20-case fixture pack, validator CLI, CI green. Tagged & published.
Beyond the reference done
Viewer on npm, capture client shipped, reference API split into its own deployment. Portability proven on both read and write sides.
Spec v0.2.0 frozen done
Agent + Record write endpoints, OAI-PMH v2.0, OpenAPI 3.0 spec + Swagger UI, conformance probe, self-service API key flow, getting-started walkthrough. Tagged 2026-04-18.
Proof + Profiles draft done
Proof-of-implementation page with live numbers, 7-step use case, ISAD(G)→RiC-O mapping. Profiles framework defining six named capability axes; Core Discovery Profile v0.3-draft normative doc landed for review. Tagged 2026-04-19.
Governance & review current
Invite external spec editors. Engage EGAD-adjacent reviewers on the Core Discovery draft's open questions. Ratify profile framework. Attract a second, non-reference implementation.
v0.30.0 — Core Discovery freeze done
All 7 Core Discovery design questions resolved (Q6 RFC 7807 mandated and migrated in reference impl; ContactPoint shape pinned to openricx:ContactPoint). Profile-scoped SHACL includes :ContactPointShape. Core Discovery Profile flipped from Draft to Normative. Tagged 2026-04-21.
v0.31.0 — Authority & Context done
Second normative profile. Authority & Context covers Places, Rules, and Activities (Production, Accumulation) as first-class entities with reconciliation-friendly identifiers via owl:sameAs. Six of seven fixtures shipped; function-with-activities planned. All four design questions resolved. Tagged 2026-04-21.
v0.32.0 — Graph Traversal done
Third normative profile. Graph Traversal defines /graph?uri=&depth=, /relations, /relations-for/{id}, /hierarchy/{id} — cross-entity walks keyed to the Graph Primitives vocabulary, plus six full-graph SHACL shapes for store-wide hygiene (orphaned records, unlinked agents, duplicate identifiers). Five of seven fixtures shipped. Also: corrected "six profiles" → "seven profiles" across FAQ, data-management, and profile index — the spec has always declared seven. Tagged 2026-04-21.
v0.33.0 — Digital Object Linkage done
Fourth normative profile — the profile matrix now sits at a majority. Digital Object Linkage covers rico:Instantiation carriers (MIME, checksums via openricx:technicalCharacteristics, extent, record-backlinks) and openricx:Function (ISDF business functions), plus the optional POST /upload and thumbnail derivative endpoints. Two shipped fixtures (instantiation-tiff, instantiation-application) + two planned. All five design questions resolved on-page. Tagged 2026-04-21.
v0.34.0 — Round-Trip Editing done
Fifth normative profile. Round-Trip Editing covers the full write surface: POST / PATCH / DELETE across every RiC entity type and relations, gated by API-key scopes (write, delete), with a public per-entity audit trail at /{type}/{id}/revisions. New SHACL file shapes/profiles/round-trip-editing.shacl.ttl (3 shapes); two new fixtures (write-response-success, revision-list) join the two already shipped. All six design questions resolved on-page. Tagged 2026-04-21.
v0.35.0 — Provenance & Event done
Sixth normative profile. Provenance & Event tightens Authority & Context's Activity shapes: production-typed rico:Activity events (those carrying rico:hasActivityType <…/production>) MUST carry results + participants + dates (Violation, not Warning); cross-entity link targets MUST be the correct RiC-O class. New SHACL file shapes/profiles/provenance-event.shacl.ttl (5 shapes); two new fixtures (activity-production-full, activity-custody) shipped. Reference serializer gap closed in service v0.8.13; data backfill still pending before the reference claims this profile. Tagged 2026-04-21.
v0.36.0 — Export-Only done
Seventh normative profile — profile matrix complete. Export-Only mandates OAI-PMH v2.0 at /oai (six verbs; oai_dc + rico_ld prefixes, the latter carrying CDATA-wrapped RiC-O JSON-LD for full-semantics harvest) plus content-negotiated per-record dumps at /records/{slug}/export (JSON-LD default, Turtle and RDF-XML alternatives — lossless triple-set parity MUST hold across the three). New SHACL file (thin — OAI-PMH responses are XML and validate against the OAI-PMH XSD, not SHACL); three new fixtures (oai-identify, oai-list-metadata-formats, record-export-jsonld). All five design questions resolved on-page. Tagged 2026-04-21.
v1.0 freeze planned
The profile matrix is complete. Remaining path to v1.0 is governance-bound per governance §117, §125–129: a second independent implementation passing conformance on any profile; at least one external institution committing to deploy; 2–3 active non-maintainer contributors. Plus the data-side close of the Provenance & Event backfill so the reference server claims all seven profiles rather than six.
Extensions planned
OpenRiC-Rights (ODRL). OpenRiC-Preservation (PREMIS-equivalent). Jurisdictional extensions — decoupled from the core.
Read next
Engagement
Three seed Discussions are open — feedback of any shape is welcome.
- #1 · Announcement — the v0.1.0 introduction.
- #2 · Second-implementer questions — what would make it tractable to emit
/api/ric/v1/*from your platform? - #3 · Mapping sanity-check — where does the ISAD(G) → RiC-O mapping feel wrong to you?
- #4 · Progress update — capture app live, reference impl now a consumer of its own API.
Licence
Specification: Creative Commons Attribution 4.0. Reference implementation, viewer, capture client: GNU AGPL 3.0.
Contact
Johan Pieterse — johan@theahg.co.za · The Archive and Heritage Group (Pty) Ltd.