Frequently asked questions

Orientation

What is OpenRiC?

An open specification for how archival descriptions map to RiC-CM / RiC-O, how that data is served over HTTP, and how graph-based interfaces can render it consistently across any conformant server. It's a contract, not a product — roughly "IIIF, but for archival description". See the home page for the full picture.

How is OpenRiC different from RiC-O?

RiC-O is the ontology — the OWL vocabulary of classes and properties published by ICA EGAD. OpenRiC is a service contract that says how a server should expose RiC-O data over HTTP: endpoint shapes, JSON-LD responses, SHACL validation, conformance declarations. You can implement RiC-O without OpenRiC (by publishing static Turtle files, say) and you can consume OpenRiC without knowing much RiC-O (the JSON-LD is client-friendly). Both layers are deliberately separable.

Is OpenRiC a product?

No. There's a reference implementation at ric.theahg.co.za that runs the Laravel service in openric/service — anyone can clone and run it — but the spec itself is deliberately implementation-neutral. A second, independent implementation in a different language is one of the v1.0 freeze criteria.

What state is OpenRiC in today?

Specification at v0.2.0 frozen (April 2026); reference API at v0.8+ with 46 endpoints and full 8-entity CRUD. Six conformance profiles are defined, each with probe coverage, SHACL shapes, and fixtures. A Core Discovery Profile v0.3-draft is open for review. See proof of implementation for the evidence version.

Can I browse the RiC-CM model in OpenRiC?

Yes — the RiC-CM reference browser is at ric.theahg.co.za/reference/ric-cm/. It's a live, SPARQL-backed view of RiC-CM 1.0's 19 entities, 42 attributes, 151 relations, and 6 relation-attributes, served directly from the authoritative RiC-O v1.1 OWL (ICA EGAD, CC BY 4.0). Distinguishing features:

• Live SPARQL — the browser reflects whatever RiC-O revision is loaded. When ICA EGAD releases a new version, a single reload brings it in; no static JSON export to drift out of date.
• Declared vs. inherited separation on every page, CIDOC-CRM style. A relation whose declared domain is Agent is rendered as Agent — never flattened into Agent + Person + Group + Mechanism + Family. Members inherited from ancestor classes carry a provenance tag linking back to where they were declared.
• Versioned URLs — /reference/ric-cm/1.0/… is citation-stable; unversioned URLs redirect to the current latest, so bookmarks survive when RiC-CM 2.x ships.
• Public, unauthenticated, no setup. Click and browse.

Similar, independent efforts in this space that are worth knowing about:

• RiC-CM NavTool — a Vue SPA by Matthew Damigos (DLIB, Ionian University) that browses a curated static JSON export of RiC-CM, with an interactive modeling playground. If you're arriving from NavTool, the URL patterns of the two browsers map as below — different backings, similar coverage. OpenRiC's modeling-playground equivalent is on the roadmap but not yet shipped.

Attribution: OpenRiC's browser bundles and queries RiC-O v1.1, published by the International Council on Archives, Expert Group on Archival Description (ICA EGAD) under CC BY 4.0. Every page renders the credit per the licence.

Adoption

Do I have to replace my existing system to adopt OpenRiC?

No. OpenRiC is designed to be adopted incrementally. The most common path — the strangler pattern — is documented in the data-management guide: you run OpenRiC as a read-only projection over your existing database first, add write endpoints for new material next, and migrate legacy data last. No flag-day cutover.

How does OpenRiC work alongside AtoM?

See Topology B in the data-management guide. Three phases: (1) OpenRiC reads AtoM's MySQL and serialises as RiC over HTTP — AtoM unchanged; (2) new catalogues land in OpenRiC, back-synced to AtoM for continuity; (3) AtoM retired once historical data is migrated. Timeline varies by institution — typically 6 to 18 months.

What about ArchivesSpace, ArchivesHub, Access, or a custom platform?

Same pattern as AtoM. OpenRiC doesn't care what the legacy system is — if its data can be queried via SQL, a file system, a REST API, or SPARQL, a thin adapter on the OpenRiC side reads it and emits RiC JSON-LD. The consumer-with-own-UI topology covers the case where you want to keep your admin UI and just route RiC data through OpenRiC.

Can I just use OpenRiC for read-only federated discovery?

Yes — claim only the core-discovery profile. You expose the minimum viable surface (/records, /agents, /repositories, /vocabulary, /autocomplete) and clients targeting that profile work against your server with nothing else required. Useful for aggregators, discovery portals, or pilots that don't want to take on the full edit surface yet.

Data & architecture

Where does RiC data live?

Wherever you want. The OpenRiC spec describes the HTTP contract only; the backing store is an engineering choice. The data-management guide covers the three common shapes — triplestore, normalised relational, hybrid — and which fits each deployment.

Do I need to run a triplestore?

Not strictly, but it's the cleanest way to serve /graph and /sparql. The reference implementation uses Apache Jena Fuseki as a projection of its relational store — the triplestore isn't authoritative; it's a materialised view for graph queries. If you're not serving graph endpoints, a relational store alone is enough.

Can I use PostgreSQL instead of MySQL / Fuseki?

Yes. The reference API's current MySQL backing is a historical inheritance from Heratio; nothing in the spec mandates it. PostgreSQL with a normalised RiC-shaped schema is a better fit for greenfield deployments (ACID writes, JSON-B support, mature migration tooling). See Topology A.

What happens if Fuseki (or my triplestore) goes down?

Graph endpoints (/graph, /sparql, hierarchy walks) return 503 with the not-configured partial. All other endpoints — list, detail, autocomplete, writes — continue to work because they hit the relational store. Graph queries recover automatically once the triplestore is reachable again; no data is lost (the relational store is authoritative).

Conformance & profiles

What's a conformance profile?

A named, bounded subset of OpenRiC's endpoint surface. A server claiming core-discovery promises to serve those ten read endpoints correctly; claiming round-trip-editing additionally promises full CRUD. Profiles let implementers commit to what they can actually deliver without pretending to cover the whole spec. See profiles.

Do I have to implement all seven profiles?

No. Implement the subset that matches your server's actual capabilities. The minimum useful claim is core-discovery; you add profiles (Authority & Context, Graph Traversal, Digital Object Linkage, Round-Trip Editing, Export-Only) as you implement their endpoint surfaces. A conformance probe run against your server with --profile=<id> verifies you deliver what you claim.

How do I claim a profile on my server?

Declare it in your service description. GET / must return openric_conformance.profiles[] with an entry per claimed profile — see core-discovery.md §3.1 for the shape. The conformance probe reads this declaration and cross-checks it against your actual endpoint surface.

What does the conformance badge mean?

A live, shields.io-compatible badge showing whether your server declares a given profile. Green means declared and claimed full; grey means not declared. See badge docs for the embed pattern. Because it reads your server's live declaration, it updates automatically — no manual version bumps or stale badges.

Licensing & ownership

Why CC BY 4.0 for the spec but AGPL for the implementations?

Different goals. The spec wants maximum reuse — attribute, remix, embed, build derivative standards — so CC BY 4.0. The reference implementation wants fixes and improvements to flow back into the commons — so AGPL-3.0. You can build any commercial product you want against the HTTP contract; you can't take the reference implementation's code, close it, and ship a proprietary fork.

Can I build a commercial product on OpenRiC?

Yes. The contract is open; any client or server that speaks /api/ric/v1/* is fine. If you fork the reference implementation, AGPL applies — your modifications must be available to your users. If you write your own implementation from scratch, you pick your own licence.

Who owns the data in a federated deployment?

Whoever runs the server. OpenRiC doesn't aggregate or centralise anything — each institution runs its own conformant endpoint, and clients (viewers, aggregators, researchers) federate across them as they choose. Data ownership, privacy, and access control stay local. The spec defines X-API-Key for write auth; read auth is implementation-defined.

Contributing

How do I propose a spec change?

Open a discussion with the shape of the change first — what surface, what shape, what's driving it. Substantive changes then become PRs against openric/spec with a short rationale in the commit message. See governance for the review process.

Where do open design questions live?

Each profile document has an "Open design questions" section at the end — see core-discovery.md §10 for the current list. Questions marked "draft resolution" have our take; questions marked open are actively seeking external input. Q6 (error-envelope migration) is the one currently open.

I want to write a second implementation. Where do I start?

Start with the getting-started guide as a client to understand the shapes, then the four spec documents for the contract, then run the conformance probe against your server as you build. The fixture manifest tells you which of the 27 fixtures exercise each profile — useful as unit tests. A second, independent implementation passing conformance on any profile is the v1.0 freeze criterion.

Something missing?

This FAQ grows from questions that actually come up. If yours isn’t here, ask on Discussions or email Johan directly. Answers that come up more than twice get added back here.