OpenRiC — an open HTTP contract + conformance suite for RiC-CM / RiC-O

[Johan Pieterse]

Hello RiC community,

This is a heads-up about https://openric.org — an open, implementation-neutral  specification I've been working on for the past year that provides an HTTP
contract for publishing, exchanging, validating, and graph-walking archival data modelled in ICA's Records in Contexts.

Spec licence: CC-BY 4.0 · Tools + reference implementation: AGPL-3.0 · Current release: v0.2.0 (2026-04-18).

The gap this addresses

RiC-CM and RiC-O give us a conceptual model and an ontology, but the community hasn't yet converged on a concrete, testable HTTP expression of those models.
Each implementer picks their own endpoints, pagination, error shapes, JSON-LD vs Turtle negotiation, cross-entity traversal rules, and conformance boundaries. That makes federation, tool-reuse, and migration between platforms essentially case-by-case.

OpenRiC is an attempt to fix the HTTP layer below RiC-O, deliberately modelled after how IIIF stabilised a similar gap for digital image delivery — a shared contract, not a product, that any conformant server can speak.

What it actually contains

  Four short normative documents:

1. Mapping — https://openric.org/spec/mapping.html — ISAD(G) / ISAAR-CPF / ISDF / ISDIAH → RiC-CM / RiC-O class and property tables, with cardinality notes and cross-standard equivalences.
2. Viewing API — https://openric.org/spec/viewing-api.html — REST + JSON-LD contract. ~40 endpoints across read, write, graph traversal, OAI-PMH harvest, SHACL validation, content upload.
3. Graph primitives — https://openric.org/spec/graph-primitives.html — Node / Edge / Cluster / Drill / LayoutHint abstractions, with six invariants every conformant server must hold.
4. Conformance — https://openric.org/spec/conformance.html — four levels (L1–L4), 19 JSON Schemas, SHACL shape set (core + full-graph), 27-case fixture pack, validator CLI.

Plus three live surfaces built directly on the spec:

- https://openric.org/api-explorer/ — interactive Swagger UI over any OpenRiC-conformant server. Paste a server URL + API key, hit "Try it out" on every endpoint. Renders from each server's own /openapi.json.
- https://openric.org/demo/browse/ and https://openric.org/demo/ — live catalogue and graph walks against real archival data. Click any node to drill into its RiC-O neighbourhood.
- https://openric.org/conformance/ — probe.sh: pure bash + jq, points at any server,  returns a pass/fail report across every required endpoint. Drop it into CI as a regression guard.

Where RiC-O conformance sits

The SHACL shape set at https://github.com/openric/spec/blob/main/shapes/openric.shacl.ttl treats rico:Record, rico:Person, rico:CorporateBody, rico:Family, rico:Production, rico:Accumulation, rico:Place, rico:Instantiation, rico:Rule, rico:Function, and rico:DateRange as first-class node shapes, with cross-entity checks (hierarchy consistency, creator-class alignment) separated into a full-graph shape file that runs only against a complete triple store.

Notably — /sparql is marked experimental in v0.2.0; the reference returns a stub, and I've deferred a real triplestore-backed query layer until there is concrete demand. For single-entity and subgraph traversal the /graph?uri=…&depth=N endpoint covers most use cases without SPARQL, and it has a fixed schema.

For institutions and standards-adjacent readers

A concise executive brief is at https://openric.org/for-institutions.html — 3-minute read covering vendor independence, longevity, interoperability, RiC alignment, and the cost/risk/lock-in picture. Intended for directors and procurement, not implementers.

Governance is deliberately lightweight while the spec is single-maintainer: https://openric.org/governance.html describes the change process, compatibility policy, and the conditions for stepping up to v1.0 (a second independent implementation passing the conformance probe).

What I'm specifically asking

- Review the mapping against your own RiC-O reading — https://github.com/openric/spec/discussions/3. Where does the ISAD(G) → RiC-O table feel wrong, under-specified, or too opinionated?
- Try the conformance probe against any server you operate or are building. I want to hear about every failure mode it misses.
- Push back on the governance model — particularly the single-maintainer-for-now position — at https://openric.org/governance.html. The right time for a community steering group is before v1.0, and I don't yet have a clear signal for when that is.
- A second independent implementation — this is the thing that moves OpenRiC from "one person's proof" to "community spec". If you are building (or know someone building) a RiC-serving endpoint, the probe will tell them exactly what's left.

Feedback of any shape is welcome: https://github.com/openric/spec/discussions, or directly.

Thanks,
Johan Pieterse
The Archive and Heritage Group (Pty) Ltd · South Africa
jo...@theahg.co.za