Why RO-Crates, not entity writes​

A single RO-Crate routinely describes many catalog entities — a collection, its items, every file they contain, and the people and organisations connected to them; the entity model is extensible, so the list doesn't end there. Entity-granular write endpoints would force depositors to decompose an RO-Crate they already hold into a sequence of per-entity calls, and force the API to referee partial failures across that sequence.

The unit a depositor actually holds is the metadata document plus its files, so that is the unit of deposit. Depositors send RO-Crates; the implementation materialises entities from them, and entities remain read-only projections. How materialisation works is implementation-defined — PARADISEC turns one item RO-Crate into an item entity plus a file entity per media file, while LDaCA may explode a whole corpus RO-Crate into collection, item, file, person, and organisation entities from a single deposit.

The deposit session​

A deposit is a staging area with an atomic publish at the end:

1. Create — POST /deposits opens a deposit for a new RO-Crate (client-proposed or server-minted ID, per the declared idMinting mode); POST /ro-crate/{id}/deposits opens an update deposit against an existing one.
2. Stage — PUT /deposit/{id}/metadata stages the metadata document (full replace) and PUT /deposit/{id}/file/{fileId} stages files, either inline or via a presigned upload target, in any order.
3. Finalise — POST /deposit/{id}/finalise validates and publishes atomically, synchronously (200) or asynchronously (202 with polling via GET /deposit/{id}). A failed finalise returns the deposit to open with the violations recorded — staged content is never lost to a metadata typo.

DELETE /deposit/{id} aborts an open deposit.

Updates use metadata-as-manifest carry-forward: stage a new metadata document plus only the changed files. Unchanged files carry forward from the pinned baseline by @id, files absent from the new metadata document drop out, and each finalise replaces the RO-Crate wholesale — the last finalise wins as a unit.

The read surface and linkage​

Deposited RO-Crates are readable: GET /ro-crates lists them, GET /ro-crate/{id} returns a lean body, and GET /ro-crate/{id}/metadata returns the deposited metadata document verbatim. The two surfaces are bidirectionally linked — entityIds on the RO-Crate answers "what did my deposit create", while roCrateIds on entities and roCrateId on files point back at the source of truth.

Deletion is DELETE /ro-crate/{id}, plus a narrow DELETE /entity/{id} valid only for entities no RO-Crate contributes to. Deleted URIs follow a single per-implementation tombstone policy — 410 with a Tombstone body, or plain 404 — declared in the new top-level tombstonePolicy capability. That one is required of every implementation, deposit or not: entities and files are mandatory core, so any catalog can hold a URI that no longer resolves.

Discovering write support​

/capabilities gains a required deposit block. Every implementation declares its position — a read-only catalog says so outright rather than leaving a key out, so clients never have to read absence as a "no":

{
  "apiVersion": "0.3.0",
  "deposit": {
    "supported": true,
    "idMinting": "both",
    "fileUpload": ["inline", "presigned"],
    "depositTtlSeconds": 604800,
    "maxFileSizeBytes": 5368709120
  }
}

A read-only catalog declares "deposit": { "supported": false } and nothing more.

Clients read the declared modes rather than probing, and write operations require the new coarse OAuth2 write scope; finer-grained authorisation is implementation-defined.

Where to go next​

• The Deposits guide covers the model in depth, with walkthroughs of depositing, updating, and deletion & lifecycle.
• The API reference documents the deposit and RO-Crate endpoints and schemas.
• The changelog records the full 0.3.0 change set.

Why​

Archives implementing this API extend it with implementation-specific response properties, but until now the specification had no rigorous way to define, discover, or evolve those extensions. Portal implementers had no way to know what a given archive supports — which extensions, or even which search facets — without per-archive configuration or probing.

The extension registry​

Extensions are now specified in the OpenAPI document itself. Every extension has a stable identifier, a schema, and semantics. Extension properties appear inline in core schemas as optional fields, each tagged with an x-extension: <id> annotation, so the boundary between core and extension is machine-readable. Anyone can propose a new extension via a pull request to the specification repository; unregistered private experiments use an x- prefixed identifier.

Implementations choose which extensions to implement — you remain conformant while implementing only the ones relevant to your corpus.

GET /capabilities​

Every conformant implementation now declares what it supports through a single endpoint:

{
  "apiVersion": "0.1.0",
  "extensions": { "segments": {} },
  "search": {
    "filters": {
      "inLanguage": { "type": "string", "label": "Language" },
      "createdAt": { "type": "date", "label": "Date created" }
    },
    "facets": { "inLanguage": { "label": "Language" }, "mediaType": {} }
  }
}

Detection is a key lookup: an archive supports an extension exactly when its identifier appears in extensions. The search object lets portals build their search UI dynamically instead of hard-coding per-archive field lists: filters declares the fields a search request may filter on, each with a type (string, date, number, or boolean) that tells the portal which UI element to render — and date and number filters accept inclusive gte/lte range objects in search requests. facets declares the fields returned with facet counts, and every facet field is guaranteed to also be filterable, so clicking a facet value always works as a filter.

This is the one conformance-affecting change in 0.1.0: existing implementations need to add the endpoint.

The segments extension​

segments is the first registered extension. It adds an optional searchExtra.segments array to search hits, carrying structured drill-down locations for full-text matches inside files — a 1-based page number for PDF matches, or an ELAN tier and time range for transcription matches — each with highlight fragments. Portals can deep-link users straight to the matching page of a PDF or the matching utterance in a media player.

Segments are a discriminated union on type, so generated client types give you precise per-variant fields. New segment types arrive by spec revision, and clients skip types they don't recognise, so deployed clients keep working as the union grows.

Where to go next​

• The Extensions guide explains the extension model, the registry, and the client rules; the segments page covers the first extension in depth, including implementation notes.
• The API reference documents /capabilities and the segment schemas.
• The specification now has a changelog recording changes from 0.1.0 onwards.