Capture RiC entities from a browser
capture.openric.org is a pure-browser data-entry tool for any OpenRiC-conformant server. No install, no backend on our side - you paste a server URL + an API key and create Places, Rules, Activities, Instantiations, and relations straight into that server's database.
What you need
- A server URL. The base of an OpenRiC API - e.g.
https://ric.theahg.co.za/api/ric/v1. The reference API is pre-filled as a default. - An API key with
writescope. The server operator gives you one. See Getting a key below. - A modern browser. The tool uses
fetch(),sessionStorage,localStorageand ES6 - works everywhere current.
First use
- Visit capture.openric.org.
- Settings panel at the top - confirm the server URL, paste your API key, hit Save. The tool runs
/healthagainst the server as a sanity check. If it returns 200, you’re connected. The key is kept insessionStoragefor this tab only, is gone when the tab closes, and is sent only to the server you configured. - Pick a tile - Record, Agent, Repository, Function, Place, Rule, Activity, Instantiation, Relation, or attach a file. A form opens below.
- Fill fields and submit. Type pickers (Place Type, Carrier Type, Relation Type, etc.) are populated live from the server’s
/vocabulary/{taxonomy}endpoint - so you always pick from whatever vocabulary the target server actually publishes, not a stale bundled list.
On success, the entity appears in the Recent captures log at the bottom (last 20, localStorage-backed). Click its label to open its JSON-LD representation on the server.
Getting a key
The tool doesn’t issue keys - the server operator does. For the reference instance at ric.theahg.co.za:
- Keys for the reference instance are issued for agreed testing only, through the form at
/api/ric/v1/keys/request; say briefly what you need to test. Its data is a demonstration set, reset nightly. For practice, point Capture at your own copy of the reference implementation instead.
For your own server, see the reference implementation’s mint command:
cd /usr/share/nginx/OpenRiC
php artisan ric:mint-service-key --owner=<your-user-id> --name="openric-capture"
Keys carry scopes - write lets you create + update; delete lets you delete. Ask the operator for the scopes you need.
Creating each entity type
Place
Geographic or topographical. Name is required; everything else helps later search + linking.
| Field | Notes |
|---|---|
| Name | e.g. Gqeberha, Ain Soukhna. Required. |
| Type | From the server’s ric_place_type taxonomy. |
| Authority URI | Geonames / Getty / Wikidata IRI if you have one. Emitted as owl:sameAs in RiC-O. |
| Latitude / Longitude | Decimal degrees. |
| Address | Free-text. |
| Description | Free-text. |
Rule / Mandate
Legislation, policy, retention schedule, authorising instrument.
| Field | Notes |
|---|---|
| Title | e.g. Protection of Personal Information Act No. 4 of 2013. Required. |
| Type | From ric_rule_type. |
| Jurisdiction | Country / region / organisation the rule applies in. |
| Start / End date | Enactment + repeal. |
| Authority URI | Link to an authoritative source (government gazette, etc.). |
| Description / Legislation / Sources | Free-text context. |
Activity
A production, accumulation, custody, reproduction, or mandate event - anything that happened and shaped records.
| Field | Notes |
|---|---|
| Name | Short descriptive name of the activity. Required. |
| Type | From ric_activity_type. The class is always rico:Activity; the kind is carried in rico:hasActivityType as an IRI from <https://openric.org/vocab/activity-type/> (production, accumulation, custody, transfer, publication, reproduction). |
| Date display | Free-text for uncertain dates: c. 2400 BC, late 19th century. |
| Start / End date | Structured dates if known. |
| Place ID | Optional - numeric id of an existing Place this activity took place at. |
| Description | Free-text. |
Instantiation
A physical or digital manifestation of a record - TIFF scan, photocopy, microfilm, audio file.
| Field | Notes |
|---|---|
| Title | e.g. Baptism register vol. 3 - scanned TIFF. Required. |
| Carrier type | From ric_carrier_type (paper, microfilm, TIFF, PDF, …). |
| MIME type | Standard IANA MIME, e.g. image/tiff. |
| Extent value + unit | 12 + pages, 4.5 + MB, 22 + minutes. |
| Parent record id | Optional - numeric id of the Record this instantiation manifests. |
| Description / Technical characteristics | Equipment, resolution, colour depth, etc. |
Relation
Link two existing entities with a rico:* predicate.
| Field | Notes |
|---|---|
| Subject id | Numeric id of the “from” entity. Required. |
| Object id | Numeric id of the “to” entity. Required. |
| Relation type | From ric_relation_type. Required. |
| Start / End date | When the relation was active. |
| Certainty | How sure you are: certain, probable, possible, uncertain, unknown. |
| Evidence | Source citation, archival reference, or a note. |
The server knows each relation type’s domain and range - if you try to link (say) a Person to a MIME type, it will 422.
Errors you might hit
| Status | What it means |
|---|---|
| 401 | No API key, or key is wrong / inactive. |
| 403 | Key is valid but missing the scope the operation needs (usually write or delete). |
| 422 | Body validation failed - missing required field, or a relation between incompatible types. Inspect the response JSON for the exact error. |
| Server URL probe fails | Wrong URL, or the server’s CORS config doesn’t allow your origin. The reference server opens CORS wide; custom servers may not. |
Tips
- Search before you create. The top-bar search hits
/autocomplete- finds matching entities across all types. Avoid duplicates. - Link as you go. When you create a Place, immediately create an Activity at that Place (you’ll need the Place’s numeric id - it appears in the Recent captures log or via the search bar).
- Bulk imports via curl, not this UI. For more than ~20 entries, use the API directly with a script. This tool is optimised for careful single-entity capture, not batch.
- The key is per-tab. Paste it again in a new tab or after closing the browser. A colleague needs their own key.
Privacy
- The API key is kept in
sessionStoragefor the tab only. It is never sent anywhere except the server URL you configured. - Recent-captures log is browser-local. Clearing site data wipes it.
- The tool makes no analytics calls, no third-party requests except to the server you pointed it at and to the CDN serving the page itself.