Publishing RiC-O from AtoM/Heratio - open spec + reference implementation now live
Johan Pieterse
The ICA's Records in Contexts (RiC-CM / RiC-O) model is gradually becoming the expected successor to ISAD(G) / ISAAR(CPF) / ISDF / ISDIAH. AtoM predates
RiC, and — as most of us here know — it has no native path to publish archival descriptions as rico:Record, rico:Agent, rico:Place, rico:Activity,
rico:Rule, etc.
I've spent the last year building an open, royalty-free specification that fixes exactly that gap: https://openric.org · CC-BY 4.0.
What OpenRiC is
An implementation-neutral HTTP contract for publishing, exchanging, validating, and graph-walking RiC-shaped archival data. Four short spec documents, 19
JSON Schemas, a SHACL shape set, a 27-case conformance fixture pack, and a pure-bash conformance probe. Think of it as IIIF for archival description — a
shared contract any system can implement, not a product.
The core mission is interoperability between AtoM, Heratio, aggregators, viewers, and future systems — so an archival record described once can be read,
written, validated, and visualised the same way regardless of backend.
Why I'm posting here
AtoM has the richest existing ISAD(G)/ISAAR catalogue in the open archival world. If RiC adoption is going to be gradual, AtoM is the most important place
for it to become possible. Three things in the spec are particularly aimed at AtoM:
1. Mapping document — https://openric.org/spec/mapping.html — the ISAD(G) / ISAAR / ISDF / ISDIAH → RiC-CM / RiC-O tables. Most of it comes directly from
AtoM's class hierarchy (QubitActor, QubitInformationObject, QubitRepository, etc.).
2. Conformance probe — https://openric.org/conformance/ — points at any server, returns pass/fail across the required endpoints. Useful for anyone
prototyping a RiC publishing plugin against an AtoM instance.
3. API Explorer — https://openric.org/api-explorer/ — interactive Swagger UI that hits the reference API live. Try every endpoint from a browser before
committing to implement any of them.
What already works end-to-end
One operational archival platform (Heratio — a Laravel-based GLAM platform I run as a Qubit-schema-compatible successor at https://heratio.theahg.co.za)
publishes through OpenRiC as its production contract. Real archival data behind it. OAI-PMH harvesting, JSON-LD / Turtle / RDF/XML export, self-service API
key flow, audit log — all live at https://ric.theahg.co.za/api/ric/v1/health.
Heratio exists as proof the spec is implementable against the same Qubit schema AtoM uses. An AtoM plugin author should find the mapping obvious.
What I'm asking
- Review the mapping — particularly https://github.com/openric/spec/discussions/3, where I want to know where the ISAD(G) → RiC-O mapping feels wrong.
- Run the conformance probe against any AtoM plugin work you have in progress — it'll tell you exactly which endpoints remain.
- Push back, loudly on the spec where it makes assumptions that don't hold for your AtoM deployment.
A second independent implementation — an AtoM plugin, for example — is what would move this from one-vendor proof to genuine community spec before v1.0.
Thanks,
Johan Pieterse
The Archive and Heritage Group (Pty) Ltd · South Africa
jo...@theahg.co.za
Claudio Escobar Arriagada
Hi Johan,
First of all, I would like to thank you and congratulate you on the incredible work you have done with OpenRiC. The transition toward RiC-CM and RiC-O is undoubtedly the most significant technical and conceptual challenge currently facing those of us who manage repositories based on ICA standards, and your proposal is remarkably timely.
It is highly valuable that you have framed OpenRiC as an implementation-neutral contract (IIIF-style) rather than a closed solution. For those of us administering AtoM instances with large datasets, having a clear mapping from Qubit classes (QubitInformationObject, QubitActor, etc.) to RiC entities provides a fundamental roadmap that saves months of technical analysis.
Using Heratio as a proof of concept is a brilliant move to demonstrate that the Qubit schema is compatible with this model. This provides great confidence regarding the feasibility of implementing a plugin or an API layer in existing AtoM installations.
I am very interested in supporting this project and will aim to contribute to your requests as follows:
Mapping Review: I will take a close look at the documentation on GitHub to see how the ISAD(G) / ISAAR tables behave against RiC-O, particularly regarding the hierarchy of descriptive levels.
Conformance Testing: I will try to run tests using the conformance probe in my development environments to identify potential discrepancies or edge cases.
Technical Feedback: I will join the repository discussions to report any assumptions that might not align with the AtoM deployments I manage.
Thank you again for taking this step toward true interoperability and for opening it up to the community as a free specification. It is exactly what the open-source archival software ecosystem needs to stay ahead.
Best regards,
Claudio Escobar Arriagada
Librarian / IT Professional / Digital Archives
Johan Pieterse
Hi Claudio,
Thank you, this is the engaged reply the post was hoping for, and the three commitments you've offered are exactly the work that turns a one-vendor draft into a community spec.
The hierarchy of descriptive levels is a particularly good place to start. It's the most opinionated part of the mapping, and the part most likely to need pushback from someone running real AtoM deployments.
The current draft thread is at https://github.com/openric/spec/discussions/3 - Fonds → Sub-fonds → Series → Sub-series → File → Item is modelled as ordered rico:RecordSet instances joined by rico:isOrIncludes, with an open question about whether each level should also carry a rico:hasDescriptiveLevel term independently of the hierarchy. Real-deployment input is the only thing that resolves that.
Three concrete starting points, each sized to roughly one afternoon:
1. Run the conformance probe against one of your AtoM instances. Before any plugin work, the probe surfaces every endpoint that's missing - gap analysis for free.
2. Trace one of your most-cited fonds through the hierarchy endpoint in the API Explorer. The diff against your AtoM JSON usually tells the story faster than the prose mapping does.
3. Open the conformance fixture pack and look specifically at the "level boundary" cases - let me know whether any of them don't match what you'd expect AtoM to produce.
I'm active in GitHub Discussions and happy to have a longer call if any of the mapping issues are easier to work through live than in writing. Running the probe across multiple AtoM deployments is the highest-leverage contribution anyone has offered so far - variation between real installations is exactly what tells us whether the spec is too prescriptive or too loose.
Anything you find, no matter how small, lands in the spec.
Best regards,
Johan