Describes the current state. Live figures are on current status.
Live endpoints. Concrete mappings. Labelled data.
OpenRiC is a contract. This page is the evidence that the contract works - a live reference implementation, concrete ISAD(G) → RiC-O mappings, and end-to-end use cases you can follow with curl. Example data is labelled with what kind of evidence it is.
Reference implementation
The OpenRiC reference API at ric.theahg.co.za runs on the database of Heratio, the archival platform of The Archive and Heritage Digital Commons Group. Much of what it holds is demonstration material rather than an institution’s holdings; the examples on this page say which is which.
How many records, agents, places and other entities it holds right now is on the current status page, read live from the service each time you open it. This page does not repeat the figures, because typed-in counts go out of date.
The list endpoints - /records, /agents, /repositories, /places, /activities, /rules, /instantiations, /relations - are content-negotiated and open to every origin for reads, with no key needed.
End-to-end use case
Scenario: a curator has a single archival record - Egyptian Boat (identifier BM-125320) - and wants it to appear in a third-party graph viewer, harvested by an OAI consumer, and validated against SHACL. Here is the path the OpenRiC contract defines for it.
Synthetic demonstration data. The catalogue record was assembled on the reference service for demonstration. Its holder in the data is the fictional Meridian Museum of Antiquities and its description was machine-generated from an image of the 3D model. It is not a British Museum catalogue record, and the British Museum has not reviewed or endorsed this demonstration.
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. The reference service does this automatically; other producers can follow the canonical mapping, §7.
Publishing - JSON-LD over HTTP
The record is live at /api/ric/v1/records/egyptian-boat, content-negotiated, with an embedded rico:hasOrHadHolder link to its holding 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. The specification requires this shape from every conformant server; so far only the reference service implements graph traversal, so that has not yet been shown on a second one.
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. Steps 3, 4 and 6 run live against the reference service with the commands shown; step 5 runs the validator from the specification repository.
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. Synthetic demonstration record - see the label above.
Gilded dining suite
Identifier OPENRIC-DEMO-3D-1. A glTF 3D model attached as an instantiation. The model and the image it was generated from are AI-generated; it depicts no real object.
Person agent
Minimal rico:Person - name, culture, stable @id. Canonical in agent-person-simple.
Meridian Museum of Antiquities
ISDIAH repository holding the demonstration record above. Holdings linked via rico:isOrWasHolderOf. A fictional institution.
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
An excerpt of the ISAD(G) rows of the mapping. The authoritative table is mapping §7.1, which also covers ISAAR(CPF), ISDIAH and ISDF; where this excerpt and the mapping differ, the mapping is right. The reference service emits a subset of these rows.
| ISAD(G) element | RiC-O predicate | Notes |
|---|---|---|
| 3.1.1 Reference code | rico:identifier | |
| 3.1.2 Title | rico:title | Language-tagged. |
| 3.1.3 Dates | openricx:hasDateRangeSet | The API shape; in RDF it expands to rico:hasCreationDate, rico:hasBeginningDate and rico:hasEndDate. |
| 3.1.4 Level of description | the class, and rico:hasRecordSetType | fonds, series, file and so on. |
| 3.1.5 Extent and medium | rico:hasExtent | A rico:RecordResourceExtent with the text on rico:textualValue. |
| 3.2.1 Name of creator | rico:hasCreator | Link to a rico:Agent. |
| 3.2.2 Administrative/biographical history | rico:history on the Agent | Not on the record itself. |
| 3.2.3 Archival history | rico:history on the record | |
| 3.2.4 Immediate source of acquisition | rico:isOrWasAffectedBy a transfer rico:Activity | With rico:hasOrHadParticipant pointing to the source Agent. |
| 3.3.1 Scope and content | rico:scopeAndContent | Servers that sent openricx:description send both until at least v0.48.0. |
| 3.3.4 System of arrangement | rico:structure | |
| 3.4.1 Conditions governing access | rico:conditionsOfAccess | |
| 3.4.3 Language | rico:hasOrHadLanguage on a record; rico:hasOrHadAllMembersWithLanguage or rico:hasOrHadSomeMembersWithLanguage on a record set | ISO 639-3 code. RiC-O 1.1 does not allow rico:hasOrHadLanguage on a record set. |
| 3.4.4 Physical characteristics | rico:physicalCharacteristicsNote | On the record's rico:Instantiation. |
| 3.5.1 Existence and location of originals | rico:hasOrHadLocation | |
| 3.5.2 Existence and location of copies | rico:hasOrHadInstantiation | Each copy or format is its own rico:Instantiation. |
| 3.5.3 Related units of description | rico:isRelatedTo | |
| 3.7.2 Rules or conventions | rico:isOrWasRegulatedBy | Link to a rico:Rule. |
| Repository | rico:hasOrHadHolder | Link to a rico:CorporateBody holding the material. |
The fixture pack at fixtures/ pins 36 concrete input/output pairs.
Example dataset - a demonstration mini-fonds you can rebuild
The Egyptian Boat above is not created by any command; it was assembled on the reference service by hand. To build a coherent example dataset on your own server, the reference implementation ships an openric:seed-demo Artisan command. It creates a small fonds about an imaginary Stellenbosch family, with every entity type the API serves:
- 1 repository - OpenRiC Demo Archive
- 1 place - Stellenbosch
- 1 agent - Johanna le Roux
- 1 rule - a family papers retention policy
- 1 function - family correspondence
- 1 fonds with 2 series - correspondence, and botanical field journals
- 1 activity - field journaling
- 1 item with 1 instantiation - a watercolour of Protea neriifolia, using a public-domain Wikimedia image
- the relations that join them
Synthetic demonstration data. Everything this command creates is invented for demonstration, and every name carries the suffix (OpenRiC demo). The one exception is the watercolour image, which is a public-domain upload from Wikimedia Commons.
Run it on your own server:
php artisan openric:seed-demo
php artisan openric:rebuild-nested-set
See it running
Browse view · Graph viewer · API Explorer (Swagger UI) · Capture client
Going further
- Read the specification;
v0.55.1is current. - Run the conformance probe against any server to check claims.
- Open the fixture pack - 36 input/output pairs across the mapped RiC-O entity types.
- 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 now on the reference service. Its database is shared with Heratio and is restored every night from a demonstration snapshot; records assembled by hand, such as the Egyptian Boat, are part of that snapshot, so the reset puts them back as they were rather than removing them.