Real data. Real endpoints. Real mappings.
OpenRiC is a contract. This page is the evidence that the contract works — a live reference implementation backed by real archival data, concrete ISAD(G) → RiC-O mappings, and end-to-end use cases you can follow with curl.
Reference implementation — live numbers
The OpenRiC reference API at ric.theahg.co.za is backed by a real archival service (The Archive and Heritage Group) with multi-jurisdiction holdings and live digital objects.
Every counter maps to a real endpoint: /records, /agents, /repositories, /places, /activities, /rules, /instantiations, /relations. Everything you see is live, content-negotiated, CORS-open, and unauthenticated for reads.
End-to-end use case
Scenario: a curator has a single archival record — Egyptian Boat (BM-125320, held by The British Museum) — and wants it to appear in a third-party graph viewer, harvested by an OAI consumer, and validated against SHACL. Here is the full trajectory the OpenRiC contract guarantees.
Cataloguing
A curator describes the record in Heratio (or any OpenRiC-compliant producer) using standard ISAD(G) fields — title, identifier, dates, creator, scope, extent, repository.
Inputs live in the producer. OpenRiC does not dictate the editing UI.
Mapping — ISAD(G) → RiC-O
The producer maps ISAD(G) fields into RiC-O classes and predicates (see the mapping table below) and exposes each entity at a stable HTTP URL. Heratio does this automatically; other producers can follow spec §3 — Canonical mapping.
Publishing — JSON-LD over HTTP
The record is live at /api/ric/v1/records/egyptian-boat, content-negotiated, with an embedded rico:heldBy link to the British Museum repository and a stable @id anyone can follow.
curl https://ric.theahg.co.za/api/ric/v1/records/egyptian-boatGraph traversal
A third-party viewer calls /graph?uri=...&depth=2 and receives a normalized Subgraph envelope — nodes, edges, canonical rico:* predicates on every edge. Exactly the same shape from every conformant server.
curl "https://ric.theahg.co.za/api/ric/v1/graph?uri=https://ric.theahg.co.za/informationobject/egyptian-boat&depth=2"Validation — SHACL
A validator (for example openric-validate, shipped in the spec repo) runs the published JSON-LD against the spec's SHACL shapes. Shapes catch missing identifiers, dangling references, and wrong cardinalities before they reach downstream consumers.
openric-validate --record https://ric.theahg.co.za/api/ric/v1/records/egyptian-boatHarvesting — OAI-PMH
An aggregator (think Europeana, DPLA, a national portal) harvests the record via OAI-PMH /oai, with metadata prefixes oai_dc and rico_ld. No bespoke integration — it is the same verb set every OpenRiC server speaks.
curl "https://ric.theahg.co.za/api/ric/v1/oai?verb=ListRecords&metadataPrefix=rico_ld"Embedding
A research institution drops the viewer component into their own portal and points it at ric.theahg.co.za — or at their own conformant server. Same embed, different backend; that is the interoperability dividend.
That is the contract: one record, seven touchpoints, zero bespoke adapters. Every step has a live endpoint on this site.
Example entities — one of each type
Each card links to a real JSON-LD document served by the reference API. Open any of them in your browser (or curl them) — they are unauthenticated reads.
Egyptian Boat
Identifier BM-125320, held by The British Museum. Digital object attached. Multi-language descriptions.
Person agent
Minimal rico:Person — name, culture, stable @id. Canonical in agent-person-simple.
The British Museum
ISDIAH repository. Holdings linked via rico:hasHolding. Address and contact fields preserved.
Egypt
Place with GeoNames authority URI and coordinates. Used as rico:hasOrHadSubject target for the Egyptian Boat record.
Production event
Creation event linking a record to its creator agent plus a date range. See activity-production.
Egyptian Antiquities Law
Law 117/1983 — a rico:Rule governing an activity. Demonstrates mandate + legal-context chaining.
TIFF digital object
Derivative instantiation of a physical record — MIME, byte count, checksum, IIIF manifest link where present.
ISDF function
Function / activity-context description — used to model why a record was created and by which business process.
Sample mapping — ISAD(G) → RiC-O
This is the 1:1 mapping the reference implementation applies at read time. No transformation pipeline — just predicate translation.
| ISAD(G) element | RiC-O predicate | Notes |
|---|---|---|
| 3.1.1 Reference code | rico:identifier | String, one per record; registrar-assigned. |
| 3.1.2 Title | rico:title | Multi-language via @language tags. |
| 3.1.3 Dates | rico:hasBeginningDate, rico:hasEndDate | xsd:gYear, xsd:date, or xsd:dateTime. |
| 3.1.4 Level of description | rico:hasRecordSetType | fonds / subfonds / series / file / item. |
| 3.1.5 Extent and medium | rico:hasExtent | Free-text on the record; structured extent on Instantiation. |
| 3.2.1 Name of creator | rico:hasCreator | Link to a rico:Agent; inverse rico:isCreatorOf. |
| 3.2.2 Administrative/biographical history | rico:history on the linked Agent | Not a predicate on the Record itself. |
| 3.2.3 Archival history | rico:history | Custody + transfer chain. |
| 3.2.4 Immediate source of acquisition | rico:hasAcquisitionProvenance | Link to the donor/transferor Agent. |
| 3.3.1 Scope and content | rico:description | Long-form prose. |
| 3.4.1 Conditions governing access | rico:hasAccessRule | Link to a rico:Rule when the restriction is formal. |
| 3.4.3 Language | rico:hasLanguage | ISO 639 code. |
| 3.4.4 Physical characteristics | rico:hasPhysicalCharacteristics | Condition, binding, material. |
| 3.5.1 Existence of originals | rico:hasInstantiation | Each copy / format is its own rico:Instantiation. |
| 3.5.3 Related descriptions | rico:isRelatedTo (symmetric) | Falls back to rico:isOrWasSubjectOf where typed. |
| Repository | rico:heldBy | Link to a rico:CorporateBody playing the Repository role. |
The full canonical mapping (including ISAAR-CPF, ISDIAH, and ISDF) lives in spec §3. The fixture pack at fixtures/ pins 27 concrete input/output pairs against this mapping.
Example dataset — the Egyptian Boat mini-fonds
The reference implementation ships an openric:seed-demo Artisan command that populates a coherent mini-fonds for exactly this “proof” purpose. Running it creates:
- 1 repository (The British Museum)
- 1 fonds + 3 series + items (Egyptian antiquities)
- 2 creator agents
- 1 place (Egypt, with GeoNames URI)
- 1 rule (Egyptian Antiquities Law 117/1983)
- 1 activity linking creator → fonds
- TIFF + PDF instantiations with SHA-256 checksums
All browseable at openric.org/demo/browse/. You can rebuild the same dataset on your own server in under a minute:
php artisan openric:seed-demo
php artisan openric:rebuild-nested-set
Screenshots
Browse view · Graph viewer · API Explorer (Swagger UI) · Capture client
Going further
- Read the spec — four documents,
v0.2.0is current. - Run the conformance probe against any server to check claims.
- Open the fixture pack — 27 input/output pairs covering every RiC-O type.
- Follow the 15-minute getting-started guide to point your own server at the same contract.
The strongest evidence that a spec is implementable is a spec that’s implemented. Everything on this page is running right now. Change a record in the reference impl, and the responses above change in real time.