OARepo ARK
ARK (Archival Resource Key) minting and resolution for OARepo / InvenioRDM repositories.
Overview
- every RDM record published as public (InvenioRDM and every oarepo-rdm model) gets an ARK
ark:NAAN/<shoulder><record id without hyphens><check char>inpids.ark, minted by an RDM PID provider on publish https://<site>/ark:NAAN/...(alsoark:/NAAN/...andARK:) resolves to the landing page, REST API (Accept: application/json), exports (.json,.datacite-json, ...) and files (/files/<key>); deleted records go to RDM's tombstone page, ARKs of other NAANs to N2T?inforeturns ERC metadata and the persistence statement (ANVL or JSON)- per-model handlers customize blades, URLs and
?infometadata invenio ark check|show|mintcommands
Installation
pip install oarepo-ark
Requires Python 3.14 and InvenioRDM 14 (invenio-app-rdm).
# invenio.cfg
ARK_NAAN = "12345" # from arks.org; "99999" for tests
ARK_DEFAULT_SHOULDER = "r1" # required; per-service overrides: ARK_SHOULDERS = {"ccmm-dataset": "d1"}
Without ARK_NAAN the extension is installed but inert. Register the NAAN at arks.org with
https://<site>/ark:${content} as the redirect target so that https://n2t.net/ark:12345/...
reaches the resolver.
How ARKs are minted
At finalize_app the extension adds ARKPIDProvider to RDM_PERSISTENT_IDENTIFIER_PROVIDERS and a
required ark scheme to RDM_PERSISTENT_IDENTIFIERS, so RDM creates the ARK on publish - exactly
like DOIs and OAI ids. Users cannot choose ARKs: a draft carrying any other pids.ark than the
record's own fails to publish.
The scheme is global: every service using the RDM PID machinery mints ARKs, so every service needs
a shoulder - hence ARK_DEFAULT_SHOULDER is required, and ARK_SHOULDERS only overrides it per
service. invenio ark check lists the services and their shoulders (with oarepo-rdm also the
global records service, which only delegates to the model services and never mints anything).
RDM's DataCite serializer sends every non-DOI PID as an alternate identifier, so DOI registrations and updates carry the ARK too.
Like DOIs, ARKs are not created for records published as restricted; they get one when published as
public. A new version gets a new ARK; there are no concept ARKs for all versions, so an ARK -
including its /files/... - always means the same content. Records published before oarepo-ark was
installed get their ARK with invenio ark mint (see below). To wire the provider differently,
define an ark provider in RDM_PERSISTENT_IDENTIFIER_PROVIDERS and/or an ark scheme in
RDM_PERSISTENT_IDENTIFIERS yourself; oarepo-ark then keeps yours.
Handlers
Each service has a handler: ARK_HANDLERS[service_id], else ARK_DEFAULT_HANDLER
(RDMRecordHandler: URLs from the result item's links, so it works for any model; ?info metadata
from RDM-shaped creators, title and publication_date, (:unav) where a model's metadata differs).
Both take a handler class or its import string; the handler is created with the service id.
from oarepo_ark.api import ERC
from oarepo_ark.handlers.rdm import RDMRecordHandler
class ThesisHandler(RDMRecordHandler):
def erc(self, item):
md = item.data["metadata"]
return ERC(who=md["author"], what=md["title"], when=md["defense_date"][:4])
ARK_HANDLERS = {"theses": ThesisHandler}
| Need | Override |
|---|---|
metadata of ?info |
erc |
| record id -> blade | get_blade (the check character is always appended) |
| exports / files | variant_url / component_url |
| landing page / API URLs | landing_url / api_url |
| ARK's object -> result item (e.g. a record PID type the record class does not declare) | read |
oarepo (oarepo-model / oarepo-rdm) repositories: see the NRP-CZ documentation.
Landing page
Add the ARK box to the detail page sidebar (InvenioRDM and oarepo-ui),
APP_RDM_DETAIL_SIDE_BAR_TEMPLATES = [..., "oarepo_ark/ark_identifier.html"]. It shows
- an "ARK | ark:NAAN/name" badge (served at
/ark-badge/<ark>.svg) and a copy button, like RDM's DOI; - a dropdown of the ARK URLs of the export formats (
<ark>.<code>; oarepo-ui: the model's displayed exports, InvenioRDM:APP_RDM_RECORD_EXPORTERS) and one of the files (<ark>/files/<key>), each with a copy button. These are React components of theoarepo_ark_linkswebpack bundle: rebuild the repository's assets after installing oarepo-ark (e.g.invenio webpack buildall).
For your own templates there are the globals ark_identifier(record) (ark:NAAN/name) and
ark_url(record) (citable URL); they accept a record, its UI dict or a service result item.
The templates, messages and React components are translated into Czech and English.
Commands
| Command | |
|---|---|
invenio ark check |
print the effective configuration (NAAN, shoulders, handlers, resolver, erc-support), validate it (exit 1 if invalid) and list the services minting ARKs with their shoulder and handler |
invenio ark show <ark> |
what an ARK resolves to: stored ARK, qualifier, status, object, handler, citable URL |
invenio ark mint [--service ID]... |
give existing published records their ARK (default: all services minting ARKs); skips records that are restricted, deleted or already have an ARK |
invenio ark mint --service ID [RECORD_ID]... |
the same for the given records |
invenio ark mint --service ID --pid-type T |
when the PID type of the service's records cannot be read from its record class |
mint updates each record in place (PID, pids.ark, reindex) in its own transaction - no new
draft, revision via publish or DataCite call; a failed record is reported and retried by the next run.
Configuration
| Key | Default | |
|---|---|---|
ARK_NAAN |
None |
NAAN: 5 digits or consonants (bcdfghjkmnpqrstvwxz) |
ARK_DEFAULT_SHOULDER |
None |
primordinal shoulder of all services; required with ARK_NAAN |
ARK_SHOULDERS |
{} |
per-service overrides: service_id -> shoulder |
ARK_HANDLERS |
{} |
service_id -> handler |
ARK_DEFAULT_HANDLER |
RDMRecordHandler |
handler of the other services |
ARK_PUBLIC_RESOLVER |
https://n2t.net/ |
NMA of citable URLs |
ARK_SUPPORT |
who: THEME_SITENAME, what: Permanent: Stable Content:, where: SITE_UI_URL |
erc-support of ?info |
Development
./run.sh venv
./run.sh test # starts PostgreSQL/OpenSearch/... in docker, runs the tests on a real InvenioRDM app, stops them
./run.sh lint
./run.sh jslint # ESLint / Prettier for the React components
./run.sh translations # extract and compile translations (oarepo.yaml, babel.ini)
To run pytest directly (e.g. with -k), keep the services running:
./run.sh start
set -a; . ./.env-services; set +a
.venv/bin/python -m pytest -k resolver
./run.sh stop
Terminology
A short guide to the ARK vocabulary used above, for readers who know ARKs as persistent identifiers
but not the details. Source: arks.org and the ARK specification
(IETF draft draft-kunze-ark).
An ARK as minted by this library, taken apart:
https://n2t.net/ark:12345/r1abcde12345p/files/data.csv?info
└──────┬───────┘└┬─┘└─┬─┘ └─────┬─────┘└──────┬──────┘└─┬─┘
NMA │ NAAN name qualifier │
label inflection
r1abcde12345p
│ │ └ check character
│ └ blade (record id abcde-12345 without hyphens)
└ shoulder
| Term | Meaning | In this library |
|---|---|---|
| ARK | Archival Resource Key: a persistent identifier that, unlike a DOI, needs no paid registration agency - an organization gets a NAAN once and mints ARKs itself. | One ARK per record version published as public, stored in the record's pids.ark. |
| NMA (Name Mapping Authority) | The host part in front of ark: (https://n2t.net/, https://repo.example.org/). It only says where the ARK is resolved, it is not part of the identity: the same ARK with another NMA is the same identifier. |
Citable links use ARK_PUBLIC_RESOLVER (N2T); the repository itself resolves https://<site>/ark:.... |
ark: label |
Marks the start of the ARK. The older form ark:/ (with a slash) must still be accepted, in any letter case. |
Both forms are resolved, also as ARK:; ARKs are written as ark:. |
| NAAN (Name Assigning Authority Number) | The organization's number, assigned for free by arks.org, usually 5 digits. Everything after it is managed by the organization. 99999 is reserved for tests and examples. |
ARK_NAAN; ARKs of other NAANs are redirected to N2T. |
| Name | The part after NAAN/ that identifies the object: shoulder + blade (+ check character). |
r1abcde12345p. |
| Shoulder | A prefix of the name that splits a NAAN into sub-namespaces (per department, collection, record type). A primordinal shoulder is zero or more consonants followed by one digit, e.g. r1, x6, bc2: it ends at its first digit, so no shoulder is a prefix of another. |
ARK_DEFAULT_SHOULDER for all services, overrides per service in ARK_SHOULDERS. |
| Blade | The rest of the name after the shoulder; ideally opaque (no meaning that could become wrong later). | The record id without hyphens (abcde-12345 → abcde12345). |
| Check character | One character computed from NAAN/shoulder+blade with the NOID algorithm. NOID works over 29 characters (0-9 and the consonants bcdfghjkmnpqrstvwxz); any other character counts as 0. For names made only of those 29 it detects every single wrong character and every swap of two neighbouring characters. |
Always appended; a wrong one gets a "probably a typo" 404. Blades are RDM record ids, which may also contain a, e and y (outside the 29): typos that only involve these go unnoticed - measured on RDM ids, about 1 % of single wrong characters and of neighbour swaps. Such an ARK then simply gets a plain "Not found". |
| Qualifier | Text after the name addressing a part or form of the object: /xyz for a component (hierarchy), .xyz for a variant (format, language, version). |
/files/<key> → the file, .<format> (e.g. .json) → an export. |
| Inflection | A query appended to the ARK asking about the object instead of for the object itself. ?info is the standard one; ? and ?? are older forms. |
All three return the ERC metadata and the persistence statement; for other NAANs they are passed on to N2T as ?info. |
| ERC (Electronic Resource Citation) | Minimal "kernel" metadata returned by ?info: who (creator), what (title), when (date), where (the ARK). |
Taken from the record by the handler's erc(); restricted/withdrawn records reveal nothing. |
Persistence statement (erc-support) |
What the organization commits to for the object, e.g. Permanent: Stable Content:, plus who supports it and since when. |
ARK_SUPPORT. |
| ANVL | "A Name-Value Language": the simple name: value text format of ?info responses. |
Default ?info format; JSON on Accept: application/json. |
| N2T (Name-to-Thing) | The global ARK resolver at https://n2t.net/. It knows every NAAN's target and forwards https://n2t.net/ark:NAAN/... (with the rest of the ARK) to the organization. |
Register https://<site>/ark:${content} as your NAAN's target at arks.org. |
| Normalization | ARKs that differ only in the NMA, ark: vs ark:/, the letter case of the label and the NAAN, hyphens, or a trailing / or . are the same ARK. Everything else is case sensitive. |
Applied before storing and looking up ARKs; r1abcde-12345p finds r1abcde12345p. |
License
MIT, see LICENSE.
Metadata
Release files for oarepo-ark 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oarepo_ark-1.0.0.tar.gz | 38.0 kB | Without provenance | Details for oarepo_ark-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oarepo_ark-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for oarepo_ark-1.0.0-py3-none-any.whl |
Total release size: 87.5 kB
Release files / oarepo_ark-1.0.0.tar.gz
| Download URL | oarepo_ark-1.0.0.tar.gz |
|---|---|
| Size | 38.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ecbef0393488c2da2dd320796aa39d498f822ed65b0846dafa77e0031574f7a0
|
|
BLAKE2b-256 checksum How to use checksums |
d070a086ca25fd6da60045b3d7f57ce7595c75ef23f1829faa5c10fe95cc85eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / oarepo_ark-1.0.0-py3-none-any.whl
| Download URL | oarepo_ark-1.0.0-py3-none-any.whl |
|---|---|
| Size | 49.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
72fc1412434a87dae6ba53f54b3b180597a30a1e3df9ed60d6398bca6bc5e6e9
|
|
BLAKE2b-256 checksum How to use checksums |
7bedea0074c2d25b358f6da6734944aba3128d77325a2fe9ecc8965807a87008
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for oarepo-ark 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.