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

Core Discovery Profile

Profile id: core-discovery Profile version: 0.7.0 Last revised in spec: v0.54.0 Status: Normative Dependencies: None Last updated: 2026-10-20

1. Purpose

Core Discovery is the minimum-viable OpenRiC conformance target. A server that implements this profile can be listed, browsed, searched, and dereferenced for records, agents, and repositories - but is not required to expose graph traversal, relations, authority entities, activities, digital objects, write verbs, or OAI-PMH harvesting.

This profile answers the question: “what is the smallest thing my system can expose and still call itself OpenRiC-compliant?”

Typical use cases:

• Legacy catalogues publishing a read-only window over existing records.
• Aggregator back-ends that only need to ingest descriptions, not the full graph.
• First-stage implementations on their way to wider profile coverage.

2. Scope

2.1 Required endpoints

A server claiming Core Discovery conformance MUST implement all ten endpoints below under a single base URL:

All endpoints are unauthenticated reads. Rate limiting is allowed but MUST return RFC 6585 429 Too Many Requests with a Retry-After header when applied.

2.2 Forbidden endpoints (without additional profile claims)

A server that claims only Core Discovery MUST NOT implement or reference:

• /graph, /hierarchy/{id}, /relations, /relations-for/{id} - belong to the forthcoming Graph Traversal profile
• /activities, /places, /rules, /functions, /instantiations - Authority & Context, Provenance, Digital Object profiles
• /oai - Export-Only profile
• POST, PATCH, PUT, DELETE on any resource - Round-Trip Editing profile

A server MAY implement these if it also declares the relevant profile. Silently implementing them without declaration is a conformance failure because it misleads consumers about the capability surface.

2.3 Content types

All responses MUST support:

• application/ld+json - JSON-LD with the OpenRiC context
• application/json - same content; @context MAY be trimmed to a URL reference

Servers MUST set Vary: Accept on every response that content-negotiates.

3. Response shapes

3.1 Service description - GET /

{
  "name": "string, human-readable service name",
  "version": "string, implementation version",
  "openric_conformance": {
    "spec_version": "string, e.g. \"0.55.1\"",
    "profiles": [
      {
        "id": "core-discovery",
        "version": "0.5.0",
        "conformance": "full"
      }
    ]
  }
}

The openric_conformance object is REQUIRED. At least one profile MUST be declared; core-discovery MUST appear if this profile is claimed.

3.2 Vocabulary - GET /vocabulary

Returns an ordered array of rico:* types with labels. Minimum shape:

{
  "@context": {
    "rico": "https://www.ica.org/standards/RiC/ontology#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#"
  },
  "classes": [
    { "@id": "rico:Record", "rdfs:label": "Record" },
    { "@id": "rico:Agent", "rdfs:label": "Agent" }
  ],
  "properties": [
    { "@id": "rico:title", "rdfs:label": "Title" }
  ]
}

classes MUST be an array, and so MUST properties when it is sent. Before 0.7.0 the JSON Schema called the property list predicates while this section called it properties; properties is the name, and a server MAY send predicates beside it until it is removed (deprecated in v0.54.0, not before v0.55.0). @type is optional (the reference service sends ric:Vocabulary, the minimal server openric:Vocabulary). As for every response, the @context binds its prefixes inline (§3.3). Only classes and properties actually exposed by the server’s declared profiles need be listed. A Core-Discovery-only server lists Record, Agent, CorporateBody (for repositories), and the property set it emits.

3.3 List responses - GET /records, /agents, /repositories

Pagination envelope (profile 0.4.0):

{
  "@context": {
    "rico":     "https://www.ica.org/standards/RiC/ontology#",
    "openric":  "https://openric.org/ns/v1#",
    "openricx": "https://openric.org/ns/ext/v1#"
  },
  "@type": "openricx:RecordList",
  "openric:total": 713,
  "openric:page": 1,
  "openric:limit": 20,
  "openric:next": "https://example.org/api/ric/v1/records?page=2&limit=20",
  "openric:prev": null,
  "openric:items": [
    { "@id": "...", "@type": "rico:Record", "rico:title": "..." }
  ]
}

• Clients ask for a page with ?page= (1-based, default 1) and ?limit= (default 50, maximum 200).
• openric:total, openric:page and openric:limit MUST be present and MUST be integers; openric:items MUST be an array.
• openric:total MUST reflect the unfiltered set size when no query is supplied, or the filtered size when ?q= or equivalent is present.
• openric:next and openric:prev SHOULD give the URL of the adjacent page, or null at either end. Servers MAY also send RFC 8288 Link headers with rel="next" and rel="prev".
• Each item MUST include at minimum @id, @type, and a name-like field (rico:title for records, rico:name or rico:hasOrHadAgentName for agents and repositories).
• The @context MUST bind every prefix the response uses, inline. A context URL is allowed only where a JSON-LD context document is actually served at it.

Before 0.4.0 this section showed bare total, limit, offset and items keys under a context URL (https://openric.org/ns/v1/context.jsonld) that has never been published, and required Link headers. No implementation followed it: the reference service paged with page and used openric: keys on some lists and ric: keys on others. 0.4.0 makes the openric: keys normative. A server MAY keep sending the old ric:total, ric:page, ric:limit and ric:items keys alongside them, with ric bound to https://openric.org/ns/v1# (the ric: alias); clients SHOULD read the openric: keys. See §9 for the migration note.

3.4 Single-entity responses

3.4.1 GET /records/{key}

Required fields:

Optional fields (permitted in this profile):

Forbidden without other profile claims:

• rico:isOrWasSubjectOf, rico:hasOrHadSubject - require Graph Traversal profile
• rico:hasOrHadInstantiation - requires Digital Object Linkage profile
• rico:hasOrganicProvenance - requires Provenance & Event profile

3.4.2 GET /agents/{key}

Required fields:

Optional fields:

3.4.3 GET /repositories/{key}

Required fields:

Optional fields:

3.4.1 openricx:ContactPoint shape

The contact point is a single embedded object under openricx:contact, typed openricx:ContactPoint. Consistent with spec/mapping.md §5.2.2 (ISDIAH 5.2.2 → openricx:contact → openricx:ContactPoint). All subfields are OPTIONAL - emit only what you have; omit nulls. Implementations MUST NOT invent alternative property names.

{
  "openricx:contact": {
    "@type": "openricx:ContactPoint",
    "openricx:streetAddress": "Private Bag X236",
    "openricx:postalCode": "0001",
    "openricx:city": "Pretoria",
    "openricx:country": "ZA",
    "openricx:telephone": "+27 12 323 5300",
    "openricx:email": "info@example.org"
  }
}

Rationale for openricx:ContactPoint over schema:ContactPoint. The Core Discovery profile is RiC-native and avoids cross-vocabulary dependencies in its normative surface. schema.org/ContactPoint is a valid alternative shape in a non-normative @context alias; implementations that want schema.org interop MAY emit the same object under schema:contactPoint in addition, but a Core-Discovery-conformant response MUST emit the openricx:contact → openricx:ContactPoint form.

3.5 Autocomplete - GET /autocomplete?q=&types=&limit=

The response is an array of matches, best first (schemas/autocomplete.schema.json):

[
  { "id": "https://example.org/actor/pieterse-johan", "label": "Pieterse, Johan", "type": "Agent",
    "@id": "https://example.org/actor/pieterse-johan", "@type": "rico:Person", "score": 0.95 }
]

• Each match MUST carry id (the entity’s IRI, or the key its single-entity endpoint takes), label and type, the short class name (Record, Agent, Repository). It MAY carry @id, @type (its RiC-O class) and a score.
• q parameter REQUIRED; a request without it is a 400 bad-request. A query shorter than two characters MUST be answered 200 with an empty array: the server need not search on one character.
• types parameter OPTIONAL; accepts comma-separated record, agent, repository. Defaults to all.
• limit parameter OPTIONAL; defaults to 10, maximum 50.

Before 0.7.0 this section showed an object, {"query", "items"}, while the JSON Schema and the probe expected an array; implementations followed the schema.

4. Error handling

Errors MUST use the RFC 7807 Problem Details shape with Content-Type: application/problem+json:

{
  "type": "https://openric.org/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Record with key 'abc123' does not exist",
  "instance": "/api/ric/v1/records/abc123"
}

The five base fields (type, title, status, detail, instance) are REQUIRED. Implementations MAY emit additional fields alongside them - for example, an id of the missing entity, a code shorthand, a max_bytes upload ceiling, a validation example. Clients MUST tolerate unknown fields.

4.1 Error-type URIs

The type field is the stable identifier clients SHOULD dispatch on. Titles and details are human-readable and MAY be reworded or localised without breaking clients. The registered types, with their HTTP status codes, are:

Implementations MAY mint additional types for implementation-specific errors; such types MUST live under a URI prefix the implementer controls (NOT under https://openric.org/errors/), and the HTTP status MUST match the meaning in RFC 9110.

5. SHACL shapes

Core Discovery responses MUST validate against the profile-scoped shape file:

shapes/profiles/core-discovery.shacl.ttl

This file is a strict subset of the main shapes/openric.shacl.ttl containing only:

• :RecordShape - with forbidden-predicate rules for Graph/Authority/Provenance fields
• :AgentShape - with minimum-name constraint
• :CorporateBodyShape - for repositories
• :AgentNameShape - for canonical name resolution
• :DateRangeShape - for date fields

Shapes are open - unknown predicates do not cause failure. Implementations MAY emit private metadata.

6. Conformance testing

The conformance probe runs profile-scoped:

./probe.sh --profile core-discovery {base-url}

The probe MUST:

1. Fetch GET / and verify openric_conformance.profiles contains core-discovery
2. Hit each of the ten required endpoints
3. Validate responses against their JSON Schemas
4. Validate against shapes/profiles/core-discovery.shacl.ttl
5. Verify no forbidden predicates appear in responses
6. Verify pagination links on list endpoints
7. Verify RFC 7807 error shape on a deliberate 404
8. Emit a JSON report (--json=, schema openric-probe-result/1) with the profile, a verdict and every check

Steps 3 and 4 need a validator: the probe runs them when python3 with the jsonschema package (step 3) or pyshacl (step 4) is installed, and otherwise reports them as skipped, never as passed. Before v0.54.0 the probe did not run them at all.

A server passes Core Discovery conformance when all tests pass.

7. Fixture pack

The following existing fixtures exercise Core Discovery and ship in the profile manifest at fixtures/profiles/core-discovery/manifest.json:

1. service-description - GET /
2. vocabulary - GET /vocabulary
3. record-list - GET /records list envelope
4. fonds-minimal - GET /records/{key} minimal valid record
5. fonds-with-children - GET /records/{key} with nested structure (fields trimmed to profile)
6. record-multilingual - GET /records/{key} a record in its source culture, with scope and content (no @language tags yet; fonds-minimal carries them)
7. agent-person-simple - GET /agents/{key} minimal Person
8. agent-corporate-body - GET /agents/{key} CorporateBody
9. agent-family - GET /agents/{key} Family
10. autocomplete-egypt - GET /autocomplete cross-entity hit
11. error-not-found - RFC 7807 error envelope

The manifest declares these eleven fixtures as normative for core-discovery. Fixtures outside this list are NOT required for profile conformance.

8. Implementation checklist

A server implementer works through:

• Implement or expose the ten required endpoints under a single base URL
• Emit openric_conformance in the service description with profiles: [{id: "core-discovery", ...}]
• Ensure responses satisfy the minimum-field requirements in §3
• Remove or gate forbidden predicates (see §2.2 and §3.4)
• Return RFC 7807 errors with application/problem+json content type
• Support content negotiation; set Vary: Accept
• Enable CORS for reads: Access-Control-Allow-Origin: *
• Paginate list responses with page and limit, and the openric: envelope keys in §3.3
• Run ./probe.sh --profile core-discovery {base-url} - all tests pass
• Validate responses against shapes/profiles/core-discovery.shacl.ttl

9. Migration

From profile 0.6.0 to 0.7.0 (spec v0.54.0)

From profile 0.5.0 to 0.6.0 (spec v0.50.0)

RiC-O 1.1 separates datatype properties, which carry literals, from object properties, which point at other resources. Earlier versions of this profile and of the mapping gave literals to object properties. Each row below corrects one such case.

From profile 0.4.0 to 0.5.0 (spec v0.49.0)

From profile 0.3.0 to 0.4.0 (spec v0.44.0)

Fixture: record-list shows the 0.4.0 envelope with the ric: aliases still present.

From v0.2.0

Servers currently claiming L2-core conformance per the pre-v0.3 Viewing API §2 should transition as follows:

Servers using the Heratio-style {"success":false, "error":"..."} error envelope will need to switch to RFC 7807 to claim Core Discovery. This is the one breaking change in the v0.2 → v0.3 transition.

10. Design decisions

Seven questions were flagged during drafting. All seven are resolved in the normative Core Discovery profile (v0.3.0 profile, cut in spec v0.30.0). Rationale is retained below for the record; any resolution can be re-opened via a GitHub discussion citing the question ID.

A note on numbering: Q2 was retired during early drafting; the remaining questions keep their original IDs (Q1, Q3-Q8) so cross-document references stay stable. Any resolution below can be re-opened via a GitHub discussion citing the question ID.

Q1 - “Core Discovery” name vs IIIF Level 0/1/2 numbering

Question: Should profiles follow IIIF’s numeric Level 0/1/2 convention, or keep named profiles?

Resolution: Keep named profiles. “Core Discovery”, “Authority & Context”, etc.

Rationale: IIIF’s numeric levels assume nested supersets - Level 1 contains Level 0. OpenRiC profiles are bounded capability axes that are largely orthogonal, not layered. A server might claim Core Discovery + Digital Object Linkage without ever implementing Round-Trip Editing, and numeric levels would falsely imply a ladder. Names preserve semantic flavour and avoid misrepresenting the design.

External review welcome on: whether one profile should nonetheless be declared the “floor” in governance.

Q3 - /autocomplete in Core Discovery or a separate Search profile?

Question: Is /autocomplete discovery, or is it search?

Resolution: Stays in Core Discovery.

Rationale: A discovery profile without type-ahead reads as navigation-only, which is a weaker position than IIIF Image API Level 0 (which at least delivers full images). Users evaluating whether to adopt OpenRiC will expect /autocomplete at the first step; carving it into a separate profile would make the default conformance target look incomplete. A richer Search profile can still add faceting, filters, and relevance tuning on top.

Q4 - Repositories as first-class in Core Discovery, or behind Authority & Context?

Question: Should GET /repositories/{key} and repository inclusion in lists require an A&C profile claim?

Resolution: First-class in Core.

Rationale: rico:hasOrHadHolder is emitted inline on every record in the list and detail shapes already. If repositories were A&C-only, every Core-only implementation would have to either strip the heldBy triple (losing material context) or leak a class the profile doesn’t cover (breaking conformance). First-classing repositories matches what real archival discovery always needs - “who holds this?” is a first-order discovery question, not an authority-control detail.

Q5 - Pagination mandatory on list endpoints?

Question: Must GET /records, /agents, /repositories paginate, or is unbounded allowed?

Resolution: Mandatory pagination. Default page size 50, max 200.

Rationale: Unbounded list responses are a client footgun: a /records endpoint with 100,000 rows tanks page loads, wastes bandwidth, and exposes every client to a memory-pressure bug nobody signed up for. Every known conformant implementation paginates anyway; codifying it avoids a failure mode where one impl ships unbounded and clients hand-written against it break against everyone else.

External review welcome on: the specific default (50) and max (200) page sizes.

Q6 - Error envelope shift to RFC 7807 in v0.3?

Question: Mandate application/problem+json in v0.3 and deprecate the existing {success: false, error: …} envelope, or accept both?

Resolution: Mandate RFC 7807 in v0.3. No migration window.

Rationale: There are no external v0.2 clients to accommodate - only the reference server itself was emitting the old envelope, and the migration landed in the reference implementation at the same time as this resolution (OpenRiC service v0.8.11, packages/ahg-ric/src/Support/ProblemDetails.php). Accepting both shapes indefinitely would lock every future implementer into emitting two error formats on every 4xx/5xx, which is strictly worse than a single IETF-standard shape. A migration window buys nothing when the only affected client is the one doing the migration. The nine registered error-type URIs are in §4.1; they cover the full surface the reference implementation currently returns. Implementations MAY mint additional types under a prefix they control, as §4.1 states.

Q7 - SHACL shapes open or closed?

Question: Should Core Discovery SHACL shapes use sh:closed true (reject unknown predicates) or leave shapes open?

Resolution: Open shapes.

Rationale: Closed shapes punish harmless additions - a reference server adding an implementation-specific predicate (e.g. myimpl:someInternalMarker) for operational reasons while still satisfying every Core Discovery requirement would fail validation under closed shapes. That turns every future spec extension into a coordinated flag day for every implementation. Open shapes let the ecosystem extend forward-compatibly: new predicates don’t break old validators, and closed-shape validation can still be offered as a stricter optional profile for implementers who want it.

Q8 - Profile lifecycle: tracks spec versions, or independent?

Question: Does Core Discovery v0.3 have to move to v0.4 when the spec does?

Resolution: Independent lifecycle.

Rationale: Spec version describes the HTTP contract (paths, response shapes, auth). Profile version describes a conformance-claim scope. An implementation might sit at Core Discovery v0.3 while the spec as a whole is at v0.4; the reverse is unlikely but permitted. Independent lifecycles mean we can revise Core Discovery without forcing a spec-wide freeze, and freezing the spec doesn’t rush unpolished profiles out. Matches IIIF’s multi-API approach - Image API and Presentation API ship on separate cadences.

External review welcome on: whether profile versions should declare a minimum spec version they require (likely yes) and a maximum (likely no - forward-compatible).

Comments on any of these - including arguments to reverse a draft resolution - are welcome at https://github.com/ArchiveHeritageGroup/openric-spec/discussions.

Copyright © 2026 The Archive and Heritage Digital Commons Group (Pty) Ltd and the OpenRiC contributors. Licensed under CC BY 4.0. Editor: Dr Johan Pieterse (johan@theahg.co.za).