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

OpenRiC Conformance

Last revised in: v0.54.0

1. Purpose

This page says what it means for an implementation to conform to OpenRiC, what defines each requirement, and how a claim is tested. Conformance is checkable by machine: the conformance probe runs against a live server and reports, profile by profile, which checks pass, fail or were skipped.

2. Conformance is claimed per profile

A server conforms to one or more profiles. Each profile is a bounded set of endpoints and response requirements with its own version. The specification has 12 profiles; the profile index lists them with their status and version. Only a profile with status normative is a stable conformance target; a draft profile may change.

A server declares what it claims in its service description, GET /:

{
  "openric_conformance": {
    "spec_version": "0.55.1",
    "profiles": [
      { "id": "core-discovery", "version": "0.7.0", "conformance": "full" }
    ]
  }
}

That declaration is the authoritative claim. A claim is only as good as its test: the status page shows, for the reference service, what is declared next to what the probe found and when.

Earlier versions of this page defined four conformance levels, L1 to L4. They are kept in the appendix for readers of old material, and no current server or tool should report them.

3. What defines each requirement

Where these disagree, the profile text wins, and the disagreement is a defect to report.

JSON-LD framing order, property order within a node and prefix choice are not significant. Two RDF outputs are equal when their graphs are isomorphic under blank-node bijection.

4. Testing an implementation

4.1 The conformance probe

The probe is the conformance test. It is a shell script in the specification repository, conformance/probe.sh, and needs only bash, curl and jq:

# Every profile the server declares
BASE=https://archives.example.org/api/ric/v1 bash conformance/probe.sh

# One profile, with a machine-readable result
BASE=https://archives.example.org/api/ric/v1 bash conformance/probe.sh --profile=core-discovery --json=result.json

Public servers limit how fast they may be called; the reference service allows 60 requests a minute per address and answers more with 429. The probe waits between profiles; for your own full checks against a public server, pace them at about one request a second, and send a User-Agent that names your client, since some servers refuse library defaults. Without a key the probe is read-only and skips every check that would write; a profile with skipped checks is never reported as a plain pass. With KEY=... it also runs the write, update and delete cycle. Only run the write checks against a server whose data you may change. On the reference service that means a disposable copy, never ric.theahg.co.za itself.

CI proves on every change that the minimal server, a standard-library Python server with no connection to Heratio, passes Core Discovery.

4.2 What a pass means

A pass means the server’s responses have the shapes a profile requires, for the checks the probe could run. It says nothing about checks it skipped: run without a key, the probe skips every write, so a Round-Trip Editing result without a key verifies nothing about writing, and is reported as “not verified”. A pass also does not show that the data is good archival description, or that two servers can exchange data: two independent implementations passing the same profile is necessary for that, not proof of it. Current status reports what was tested, what was skipped and what failed, profile by profile.

4.2 The validator

openric-validate checks responses and files against the JSON Schemas and SHACL shapes:

openric-validate --record https://archives.example.org/api/ric/v1/records/my-fonds
openric-validate --file my-record.jsonld --output=json

It still accepts a legacy --level option; profile-based testing is the probe’s job.

5. Badge

A server MAY expose GET {base}/conformance/badge?profile=<id>, which returns a shields.io endpoint badge for a declared profile. The badge page describes it. The reference service exposes it.

6. Certification

There is no certification authority. Conformance is self-declared and independently checkable with the probe, as with IIIF. Third-party implementations that pass the probe for the profiles they declare can be listed on related implementations.

7. Versioning

A claim names the specification version and the profile versions it was tested against. How each kind of change is versioned, and when a release may break a passing server, is set by change control.

Appendix - legacy conformance levels

Before profiles (v0.30.0 onwards), conformance was stated as four levels. They are recorded here only so older material can be read:

Back to OpenRiC