OpenRiC Mapping Specification

Version: 0.1.0-draft Status: Draft — open for comment Last updated: 2026-04-17

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.0).

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.

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 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 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:

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:heldBy them).
• Optional openric:role "repository" annotation for viewing convenience.

6.4 Function → rico:Function / rico:Activity

An ISDF function record with its own identifier maps to rico:Function. Individual occurrences of the function (instances of it being performed) map to rico:Activity, linked via rico:hasActivity.

6.5 Event → RiC event subclass

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 rico:DateRange objects:

{
  "@type": "rico:DateRange",
  "rico:startDate": { "@value": "1899-10-11", "@type": "xsd:date" },
  "rico:endDate":   { "@value": "1902-05-31", "@type": "xsd:date" },
  "rico:normalizedDate": "1899-10-11/1902-05-31",
  "rico:dateType": "existence"
}

rico:dateType 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:source": "…/actor/smuts-jc",
  "rico:target": "…/actor/smuts-family",
  "rico:hasDateRangeSet": { "@type": "rico:DateRange", "rico:startDate": "1870-05-24" },
  "rico:certainty": "asserted"
}

9. Access, security, and privacy extensions

RiC-O v1.0 does not fully specify security classification or personal-data flags. OpenRiC defines the following extension properties:

These are emitted inside the standard RiC namespace on the assumption that future RiC-O versions will adopt them. Implementations SHOULD treat them as authoritative and consumers SHOULD surface them in UI.

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. 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:description": "Correspondence, diaries, speeches, 1886–1950.",
  "rico:hasDateRangeSet": {
    "@type": "rico:DateRange",
    "rico:startDate": { "@value": "1886-01-01", "@type": "xsd:date" },
    "rico:endDate":   { "@value": "1950-09-11", "@type": "xsd:date" },
    "rico:dateType": "existence"
  },
  "rico:hasExtent": {
    "@type": "rico:Extent",
    "rico:extentType": "3.2 linear metres, 18 boxes"
  },
  "rico:hasLanguage": [
    { "@type": "rico:Language", "rico:languageCode": "eng" },
    { "@type": "rico:Language", "rico:languageCode": "afr" }
  ],
  "rico:heldBy": {
    "@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:hasRecordPart": [
    {
      "@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.0 is incomplete for fine-grained PREMIS-equivalent events. Deferred to v0.2.
• O-4 — Multilinguality of rico:title and rico: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