Part of specification v0.55.1. Earlier versions are preserved as tagged releases.

OpenRiC Mapping Specification

Last revised in: v0.55.0 Status: Active - cross-referenced with RiC-AG (Application Guidelines) v0.1 Last updated: 2026-10-20

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: the two agree on many properties, among them rico:title, rico:scopeAndContent, rico:conditionsOfAccess, rico:conditionsOfUse, rico:hasOrHadHolder, rico:hasOrHadAgentName and rico:history, and since v0.50.0 on literal dates (rico:beginningDate, rico:endDate) and on language for record sets (rico:hasOrHadAllMembersWithLanguage or rico:hasOrHadSomeMembersWithLanguage). They differ elsewhere, and both choices are valid RiC-O 1.1: the Converter nests with rico:directlyIncludes where OpenRiC uses rico:includesOrIncluded, links origination with rico:hasOrganicProvenance where OpenRiC uses rico:hasCreator, and puts the reference code and the extent on the instantiation where OpenRiC puts them on the record. Before v0.50.0 this section said OpenRiC matched the Converter on the date and inclusion families; it did not. Per-term decisions are in the audit document.
• 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.

1.3 Versions cited, what this mapping claims, and what OpenRiC adds

Every mapping row in this document is made against these editions. A newer edition of any of them is not covered until this table names it.

What this mapping does not claim.

• No ICA endorsement. OpenRiC is independent of the ICA and EGAD, which have not reviewed or endorsed this mapping (RiC baseline). Where it disagrees with an ICA text, the ICA text is right.
• No lossless round trip from the legacy standards. Some source fields have no RiC-O 1.1 property and land in openricx: terms or in notes; a consumer that reads only rico: terms will not see them. The Portability profile’s round-trip guarantee is about OpenRiC exports, not about ISAD(G) or EAD input.
• Agreement with RiC-AG and the Converter is partial and stated. The property choices listed in §1.1 have been checked against the Converter. The tables in §7 were compared with RiC-AG’s crosswalk row by row on 15 October 2026 (comparison): of 107 elements, 55 are mapped here, and the differences found are listed there and in O-8.
• OpenRiC conformance is not RiC conformance. Passing an OpenRiC profile shows a server exposes this contract. RiC itself defines no conformance test, and nothing here should be read as certifying RiC compliance.

What OpenRiC adds on top of RiC. None of the following is part of Records in Contexts.

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#> .

API terms - list envelopes, the service description, errors, graph primitives - and three entity annotations (localType, jurisdiction, role) use the prefix below, defined by the OpenRiC API vocabulary:

@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 storage → openricx:Container in a rico:Place

RiC-O 1.1 has no container or storage class. From v0.55.0 (extension ontology 1.6.0):

• A box, folder, map drawer, crate or other container is an openricx:Container, a subclass of rico:Thing, with its kind on openricx:hasContainerType (an openricx:ContainerType, a subclass of rico:Type) and its barcode or other code as a rico:Identifier.
• What a container holds points to it with openricx:isOrWasStoredIn: a rico:RecordResource (as AtoM links a physical object to a description), a rico:Instantiation, or a smaller openricx:Container. The inverse is openricx:storesOrStored.
• Where a container is kept is a rico:Place - a building, floor, strongroom, aisle, bay, rack or shelf, typed with rico:hasOrHadPlaceType - given with RiC-O’s own rico:hasOrHadLocation. Storage places nest with rico:hasOrHadLocation like any other place, and are as public as the server makes them; storage locations are usually not published.

A server that emits a container as rico:Thing with openric:localType, as this section prescribed before v0.55.0, remains conformant: openricx:Container is a subclass of rico:Thing, and a consumer that dispatches on rico:Thing reads both.

7. Property mapping

7.1 Information Object (ISAD(G))

7.2 Date ranges

Dates are emitted as openricx:DateRange objects:

{
  "@type": "openricx:DateRange",
  "rico:beginningDate": { "@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": { "@id": "https://openric.org/vocab/date-type/existence" }
}

openricx:DateRange is a subclass of rico:Date. Literal values go on the datatype properties rico:beginningDate, rico:endDate and, for free text, rico:date; the object properties rico:hasBeginningDate, rico:hasEndDate, rico:hasCreationDate and the rest point from an entity to a rico:Date node and never carry a literal.

rico:hasDateType is an object property whose range is rico:DateType, so its value is a concept from the OpenRiC date-type vocabulary: existence, creation, accumulation, descriptive or custody. Until v0.50.0 it was sent as a plain string with those names.

7.3 Actor (ISAAR(CPF))

7.4 Repository (ISDIAH)

7.5 Control areas (ISAAR(CPF) 5.4, ISDF 5.4, ISDIAH 5.6)

Following RiC-AG §5.3.4, a description is itself a rico:Record that rico:describesOrDescribed the entity and rico:resultsOrResultedFrom the rico:Activity that produced it.

7.6 Function (ISDF)

OpenRiC serves functions as openricx:Function (§6.4). RiC-AG maps ISDF to rico:Activity; the properties below apply to either.

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:beginningDate": "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" },
  "rico:scopeAndContent": "Correspondence, diaries, speeches, 1886-1950.",
  "openricx:hasDateRangeSet": {
    "@type": "openricx:DateRange",
    "rico:beginningDate": { "@value": "1886-01-01", "@type": "xsd:date" },
    "rico:endDate":   { "@value": "1950-09-11", "@type": "xsd:date" },
    "rico:hasDateType": { "@id": "https://openric.org/vocab/date-type/creation" }
  },
  "rico:hasExtent": {
    "@type": "rico:RecordResourceExtent",
    "rico:textualValue": "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"
    }
  ]
}

12. 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. Open; no release targeted.
• 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.
• O-6 - openric: terms with no definition (resolved 2026-10-15). §4 bound openric: for viewing hints, yet the profiles, schemas, fixtures and the reference service also used it for list envelopes, errors, the service description and the localType, jurisdiction and role annotations, and no vocabulary at https://openric.org/ns/v1# defined any of them. The OpenRiC API vocabulary now defines every openric: term in use, so no response changed. The four terms only this mapping named and nothing emitted (accrualsNote, institutionType, openingHours, accessibility) moved to openricx:. openricx:jurisdiction, defined but never emitted, is deprecated in favour of openric:jurisdiction. Five fixtures that used openric: without binding it now bind it, as the service does, and bin/check-vocab.py fails CI on any undefined or unbound term.
• O-7 - Pinned RiC-O version disagreed (resolved 2026-10-15). The draft Governance profile §2 pinned RiC-O 1.0.2, carried over from the Heratio implementation; it now pins 1.1, the version this mapping and every normative profile target.
• O-8 - Differences from RiC-AG (resolved in the mapping 2026-10-15). The row-by-row comparison found extension terms used where RiC-O 1.1 has a property, four semantic mismatches and 52 elements with no row. §7 now uses rico:scopeAndContent, rico:structure, rico:generalDescription, rico:isOrWasRegulatedBy, rico:physicalCharacteristicsNote and an acquisition Activity, states the RiC-O expansion of date range sets, adds rico:hasRecordSetType, and covers the control areas (§7.5) and ISDF (§7.6). Only scope and content was emitted by the reference service; it sends both forms until at least v0.48.0 (change control’s deprecation period).

13. Change log

Back to OpenRiC