OpenRiC Mapping Specification

Version: 0.38.1 Status: Active — cross-referenced with RiC-AG (Application Guidelines) v0.1 Last updated: 2026-05-25

1. Purpose

This specification defines a deterministic mapping from the traditional archival-description standards — ISAD(G), ISAAR(CPF), ISDIAH, ISDF — to the ICA’s Records in Contexts conceptual model (RiC-CM v1.0) and its ontology (RiC-O v1.1, 2025-05-22).

Given a conforming input description, exactly one conforming RiC graph SHALL result. The mapping is total: every entity in the input has a defined target class in RiC, and every normatively-required ISAD(G)/ISAAR(CPF)/ISDIAH element has a defined target predicate.

A reference implementation exists in the Heratio ahg-ric package (AGPL-3.0) and is the empirical source of this specification.

1.1 Alignment with RiC-O Converter v3.0

This mapping is consistent with the conventions of RiC-O Converter v3.0 (Sparna + AnF Lab, March 2025) — the canonical EAD 2002 / EAC-CPF → RiC-O converter. Where this spec and the Converter make different decisions, the differences are documented:

• Source standards: OpenRiC mapping covers ISAD(G), ISAAR(CPF), ISDIAH, ISDF (the AtoM/Heratio source set). RiC-O Converter covers EAD 2002 and EAC-CPF (the international XML formats). The two source sets overlap on ISAD(G) ↔ EAD and ISAAR(CPF) ↔ EAC-CPF; the Converter does NOT cover ISDIAH or ISDF source data, OpenRiC does.
• Output RiC-O version: both target RiC-O 1.1.
• Property choices: where both standards model the same concept, this spec emits the same rico:* property the Converter emits (verified for rico:hasOrHadInstantiation, rico:hasOrHadHolder, rico:hasOrHadAgentName, rico:hasOrHadLanguage, the date-property family, the inclusion-relation family, and others — see the audit document for the per-term decisions).
• Extension namespace: where neither the Converter nor RiC-O 1.1 covers a needed concept, OpenRiC mints terms in openricx: (see /ns/ext/v1.html). The Converter does not currently use an extension namespace; OpenRiC adopters that also use the Converter can ignore the openricx terms and stay strict-RiC-O.

Institutions migrating existing EAD finding aids can reasonably use the Converter to bootstrap their corpus and an OpenRiC-conformant server (any conformant implementation, not just the reference) to expose the result over HTTP.

1.2 Cross-reference with RiC-AG (Application Guidelines)

This mapping is cross-referenced with RiC-AG v0.1 (ICA-EGAD Application Guidelines, October 2025). RiC-AG ships a crosswalk from the four legacy ICA standards — ISAD(G), ISAAR(CPF), ISDF, ISDIAH — to RiC-CM, which is exactly the source-standard set this mapping spec covers.

OpenRiC treats RiC-AG as the upstream authoritative reference for that crosswalk. Where this spec and RiC-AG agree on a class or property mapping, RiC-AG is canonical and OpenRiC defers. Where they diverge — intentionally or as drift — the divergence is documented:

• Intentional divergences: OpenRiC mints openricx: terms where neither RiC-O 1.1 nor RiC-AG covers a needed concept (e.g. openricx:containsPersonalData, openricx:hasMimeType, the openricx:hasDateRangeSet wrapper for the multi-event date pattern). These are documented in /ns/ext/v1.html and tracked as upstream-proposal candidates for eventual contribution back to RiC-O via EGAD.
• Source-set extension: OpenRiC covers ISDF and ISDIAH at the same level of detail as ISAD(G) and ISAAR(CPF). RiC-AG v0.1 covers all four; OpenRiC’s per-standard tables in §6 are intended to be consistent with RiC-AG’s crosswalk tables, not parallel definitions.
• Forthcoming EAC-CPF → RiC-O 1.1 mapping: announced under RiC-AG as “planned to be released as soon as possible.” When it lands, this spec will cross-reference it from §6.2 (Actor) alongside the existing RiC-O Converter alignment. Tracked in drift-log.

Implementations of OpenRiC profiles SHOULD treat RiC-AG as the application-pattern reference and this spec as the deployable-API contract. The two are designed to be coherent: RiC-AG answers what to model; OpenRiC answers how to expose it over HTTP.

2. Terminology & conformance

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, MAY in this document are to be interpreted as described in RFC 2119.

An implementation is any system that accepts archival-description input in a form compatible with the source schemas and emits RiC output. A conformant implementation passes all L1 test fixtures in the conformance suite.

3. Source schemas

This specification covers mapping from the following input entity types. Named after their canonical AtoM/Qubit tables; implementations MAY use different internal storage as long as the externally-visible semantics match.

4. Normative prefixes

Implementations MUST emit JSON-LD or Turtle with these prefixes bound as shown, unless otherwise indicated by content negotiation:

@prefix rico:    <https://www.ica.org/standards/RiC/ontology#> .
@prefix openricx: <https://openric.org/ns/ext/v1#> .
@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .
@prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix owl:     <http://www.w3.org/2002/07/owl#> .

OpenRiC-specific viewing hints (defined in Graph Primitives) use the prefix:

@prefix openric: <https://openric.org/ns/v1#> .

5. Identity & URI scheme

Every emitted RiC entity MUST have a stable, dereferenceable @id.

The canonical form is:

{baseUri}/{entity-path}/{slug-or-id}

Where:

• {baseUri} — the OpenRiC server’s public base URL (e.g. https://archives.example.org).
• {entity-path} — one of informationobject, actor, repository, function, event, thing.
• {slug-or-id} — the human-readable slug if available, otherwise the numeric primary key.

Example: https://archives.example.org/informationobject/AHG-A001-fonds-smuts.

A server MAY additionally mint RiC-native UUIDs (e.g. https://openric.org/id/{uuid}) for external interchange. When present, these MUST be related to the canonical identifier via owl:sameAs.

6. Class mapping

6.1 Information Object → rico:RecordSet / rico:Record / rico:RecordPart

The RiC class is selected from the ISAD(G) level of description term:

Implementations MAY extend this table for local levels but MUST preserve the RecordSet / Record / RecordPart coarse distinction.

6.2 Actor → rico:Agent hierarchy

Selected from the ISAAR(CPF) type of entity term, extended with mechanism for software systems that perform provenance-significant activities (see §10):

rico:Mechanism is a canonical RiC-O 1.1 subclass of rico:Agent, used for software systems, devices, importers, AI services, OCR pipelines, and other automated agents whose actions on records can be attributed in provenance. ICA-EGAD examples (Florence Clavaud, RiC user group #27) include scanners and digital cameras as Mechanisms participating in digitisation Activities.

6.3 Repository → rico:CorporateBody

Repositories (ISDIAH institutions) are always emitted as rico:CorporateBody. They are distinguished from other CorporateBody instances by:

• The rico:hasOrHadHolder inverse relation (records rico:hasOrHadHolder them).
• Optional openric:role "repository" annotation for viewing convenience.

6.4 Function → openricx:Function (interim) — see canonical alternatives below

RiC-O 1.1 does not define rico:Function as a class, and ICA-EGAD guidance (Florence Clavaud, RiC user group) is that an archival/business function is best modelled in canonical RiC-O as either:

1. A SKOS Concept in a function-classification ConceptScheme (when the function is a vocabulary term), with rico:Activity instances classified by it, OR
2. A rico:Activity with rico:hasActivityType <…function-type IRI…> (when the function manifests as a concrete event).

OpenRiC currently exposes ISDF function records through the /functions API surface and serializes them as openricx:Function as an interim canonical class, pending: (a) a SKOS function-type vocabulary publication, and (b) an upstream proposal to ICA-EGAD if the community converges on a canonical class. Implementations claiming the Authority & Context profile MUST NOT emit rico:Function (which is not in RiC-O 1.1).

There is no canonical “performs this function” property in RiC-O 1.1. Where the source data has an Activity that is an instance of a Function, link via the SKOS classification on the Activity’s rico:hasActivityType, not via a rico:hasActivity predicate (which is not in RiC-O 1.1).

6.5 Event → rico:Activity + rico:hasActivityType

RiC-O 1.1 does not define rico:Production, rico:Accumulation, rico:CustodyEvent, rico:Transfer, or any other concrete rico:Activity subclass — only the parent class rico:Activity is canonical. Earlier OpenRiC drafts (≤ v0.36) emitted rico:Production / rico:Accumulation as concrete classes; this was a non-conformant assumption flagged by the RiC-O 1.1 audit.

The current pattern is: every event MUST be typed as rico:Activity and MUST carry a rico:hasActivityType IRI from the OpenRiC activity-type vocabulary:

The activity-type IRIs MAY be modelled as a SKOS concept scheme in a future release; today they are dereferenceable identifiers only. Implementations MAY mint local activity-type IRIs (e.g. <https://archives.example.org/vocab/activity-type/migration>) for site-specific event kinds, but MUST also emit openric:localType so consumers without the local vocabulary can still dispatch.

6.6 Physical Object → rico:Thing

Boxes, containers, shelves, cabinets, vaults, and equipment all map to rico:Thing. The local sub-type is preserved via openric:localType:

7. Property mapping

7.1 Information Object (ISAD(G))

7.2 Date ranges

Dates are emitted as openricx:DateRange objects:

{
  "@type": "openricx:DateRange",
  "rico:hasBeginningDate": { "@value": "1899-10-11", "@type": "xsd:date" },
  "rico:endDate":   { "@value": "1902-05-31", "@type": "xsd:date" },
  "rico:normalizedDateValue": "1899-10-11/1902-05-31",
  "rico:hasDateType": "existence"
}

rico:hasDateType values: existence, creation, accumulation, descriptive, custody.

7.3 Actor (ISAAR(CPF))

7.4 Repository (ISDIAH)

8. Relationships

Relationships between actors (ISAAR(CPF) 5.3) and between records (ISAD(G) 3.5.3) are emitted as properties of the source entity pointing at the target. Where RiC-O has a directed predicate, the source is the subject and the target is the object.

The commonest ISAAR relationships map to:

Each relation MAY carry a rico:Relation reified object when date-scoping, certainty, or provenance are required:

{
  "@type": "rico:FamilyRelation",
  "rico:relationHasSource": "…/actor/smuts-jc",
  "rico:relationHasTarget": "…/actor/smuts-family",
  "openricx:hasDateRangeSet": { "@type": "openricx:DateRange", "rico:hasBeginningDate": "1870-05-24" },
  "rico:relationCertainty": "asserted"
}

9. Access, security, and privacy extensions

RiC-O 1.1 does not define AccessRestriction or SecurityClassification as classes, and does not define hasAccessRestriction / hasAccessRule / hasSecurityClassification as properties. The canonical pattern is:

• The link from a regulated resource to its governing rule is rico:isOrWasRegulatedBy (subject = the regulated RecordResource / Instantiation / etc.; object = a rico:Rule).
• The kind of rule is carried on the rico:Rule instance via rico:hasOrHadRuleType pointing at a SKOS Concept from the OpenRiC rule-type vocabulary.

OpenRiC rule-type IRIs (subset — a SKOS ConceptScheme will be published at <https://openric.org/vocab/rule-type/>):

Privacy / personal-data flag remains an OpenRiC extension property because RiC-O 1.1 does not yet model it:

Example — a record regulated by an access-restriction Rule:

<.../record/abc> rico:isOrWasRegulatedBy <.../rule/popia-2026> .
<.../rule/popia-2026> a rico:Rule ;
    rico:title "POPIA section 14 — personal data" ;
    rico:hasOrHadRuleType <https://openric.org/vocab/rule-type/access-restriction> .

Jurisdictional compliance regimes (POPIA, GDPR, CDPA, IPSAS, GRAP 103, PAIA, NAZ, NMMZ …) are out of scope for OpenRiC. They are expressed by pluggable per-jurisdiction layers on top of these base properties.

10. Systems, APIs, and Mechanisms

OpenRiC distinguishes between three layers that are sometimes conflated:

API routes such as /records, /agents, /repositories, and /functions are convenience surfaces. They do not, by themselves, define new RiC-CM classes. Where an API surface corresponds directly to a RiC-CM entity, OpenRiC serializes the resource using the canonical RiC-O class. Where a route exists for archival usability (e.g. /repositories, /functions), the canonical graph representation maps the object to the closest RiC-CM/RiC-O construct (CorporateBody for repositories per §6.3; openricx:Function interim for functions per §6.4).

10.1 Software systems are rico:Mechanism

rico:Mechanism is a canonical RiC-O 1.1 subclass of rico:Agent. It is the correct class for any software system, device, service, or automated process that performs provenance-significant activities against records. ICA-EGAD direct guidance (Florence Clavaud, RiC user group thread #27) gives scanners and digital cameras as canonical examples; the same pattern extends to:

The actions performed by these mechanisms are modelled as rico:Activity instances, linked back via rico:isOrWasPerformedBy (or its inverse rico:performsOrPerformed on the Mechanism), and to the affected records via rico:resultsOrResultedIn / rico:affectsOrAffected.

10.2 Example — OpenRiC importer converting EAD to RiC-O

@prefix rico:     <https://www.ica.org/standards/RiC/ontology#> .
@prefix openric:  <https://openric.org/id/> .
@prefix openricx: <https://openric.org/ns/ext/v1#> .

openric:mechanism/openric-importer a rico:Mechanism ;
    rico:name "OpenRiC EAD-to-RiC importer" ;
    openricx:technicalCharacteristics
        "Python/Laravel/Fuseki conversion service" .

openric:activity/conversion-2026-04-25 a rico:Activity ;
    rico:hasActivityType <https://openric.org/vocab/activity-type/transfer> ;
    rico:name "EAD to RiC-O conversion" ;
    rico:isOrWasPerformedBy openric:mechanism/openric-importer ;
    rico:resultsOrResultedIn openric:record/imported-graph-001 ;
    rico:isAssociatedWithDate [
        a openricx:DateRange ;
        rico:beginningDate "2026-04-25T08:00:00Z"^^xsd:dateTime
    ] .

This pattern keeps the OpenRiC HTTP/API layer cleanly separated from the canonical archival graph: the /import API endpoint is not a RiC entity, but the importer that the endpoint dispatches to is a rico:Mechanism whose conversions can be attributed in provenance.

11. Canonical example — fonds with subordinate series

Input (abbreviated AtoM-shape JSON)

{
  "informationObject": {
    "identifier": "AHG-A001",
    "title": "Papers of Jan Christian Smuts",
    "level_of_description": "fonds",
    "scope_and_content": "Correspondence, diaries, speeches, 1886–1950.",
    "dates": [{ "start_date": "1886-01-01", "end_date": "1950-09-11" }],
    "extent_and_medium": "3.2 linear metres, 18 boxes",
    "language": ["eng", "afr"],
    "repository_id": 14,
    "creator_id": 201,
    "children": [
      { "identifier": "AHG-A001-01", "level_of_description": "series",
        "title": "Correspondence" }
    ]
  }
}

Output (RiC-O JSON-LD)

{
  "@context": {
    "rico": "https://www.ica.org/standards/RiC/ontology#",
    "xsd":  "http://www.w3.org/2001/XMLSchema#"
  },
  "@id":   "https://archives.example.org/informationobject/AHG-A001",
  "@type": "rico:RecordSet",
  "rico:identifier": "AHG-A001",
  "rico:title": { "@value": "Papers of Jan Christian Smuts", "@language": "en" },
  "openricx:description": "Correspondence, diaries, speeches, 1886–1950.",
  "openricx:hasDateRangeSet": {
    "@type": "openricx:DateRange",
    "rico:hasBeginningDate": { "@value": "1886-01-01", "@type": "xsd:date" },
    "rico:endDate":   { "@value": "1950-09-11", "@type": "xsd:date" },
    "rico:hasDateType": "existence"
  },
  "rico:hasExtent": {
    "@type": "rico:Extent",
    "rico:hasExtentType": "3.2 linear metres, 18 boxes"
  },
  "rico:hasOrHadLanguage": [
    { "@type": "rico:Language", "openricx:languageCode": "eng" },
    { "@type": "rico:Language", "openricx:languageCode": "afr" }
  ],
  "rico:hasOrHadHolder": {
    "@id": "https://archives.example.org/repository/wits-historical-papers",
    "@type": "rico:CorporateBody",
    "rico:name": "Wits Historical Papers Research Archive"
  },
  "rico:hasCreator": {
    "@id": "https://archives.example.org/actor/smuts-jc",
    "@type": "rico:Person",
    "rico:name": "Smuts, Jan Christian"
  },
  "rico:includesOrIncluded": [
    {
      "@id": "https://archives.example.org/informationobject/AHG-A001-01",
      "@type": "rico:RecordSet",
      "rico:identifier": "AHG-A001-01",
      "rico:title": "Correspondence"
    }
  ]
}

11. Open issues

• O-1 — Level-to-class flexibility. The file level maps to rico:RecordSet, following Heratio’s implementation. Some communities prefer file → rico:Record. Under discussion.
• O-2 — Rights statements. RiC-O’s rights vocabulary is thin. A separate OpenRiC-Rights spec is likely, building on ODRL.
• O-3 — Preservation events. RiC-CM covers preservation; the predicate set in RiC-O 1.1 is incomplete for fine-grained PREMIS-equivalent events. Deferred to v0.2.
• O-4 — Multilinguality of rico:title and openricx:description. Whether to emit one triple per culture with @language, or a single JSON-LD object with @value/@language pairs. Current recommendation: array of language-tagged strings. Under review.
• O-5 — Thing / container modelling. RiC-O does not have a native Container or StorageLocation class; we map to rico:Thing with openric:localType. May warrant an OpenRiC-Storage extension.

12. Change log

Back to OpenRiC