From 2aab5479ced793297e99b6c7a01074b2a90d84f7 Mon Sep 17 00:00:00 2001 From: John Ferlito Date: Tue, 17 Nov 2026 12:28:42 +1100 Subject: [PATCH 1/2] docs: the virtual crate is normalised to ldac: and pcdm: spellings Records the decisions from #69. The virtual crate renames LDaC and PCDM properties to their prefixed forms and marks files the repository doesn't hold with display: false. The deposited crate is never changed. Adds virtual crate, metadata-only crate and shared entity to the glossary. --- GLOSSARY.md | 12 ++++++++++++ .../0004-entity-metadata-is-a-virtual-crate.md | 17 +++++++++++++++-- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 820384a..9404975 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -32,6 +32,18 @@ _Avoid_: Structural index The search documents in arocapi's search backend, one per entity that has a row. _Avoid_: OpenSearch index (one backend's storage) +**Virtual crate**: +The Metadata served for one entity: an RO-Crate with that entity as its root and everything it links to, with LDaC and PCDM properties in their prefixed spelling (ADR 0004). Never the crate as deposited. +_Avoid_: Entity crate, exploded crate + +**Metadata-only crate**: +A crate that describes files the repository doesn't hold. Its File entities are indexed and visible, but have no Content. +_Avoid_: Damaged crate (one that can't be read) + +**Shared entity**: +An entity that more than one crate describes under the same absolute IRI, indexed as one entity. +_Avoid_: Duplicate entity + ### Authentication **Upstream provider**: diff --git a/docs/adr/0004-entity-metadata-is-a-virtual-crate.md b/docs/adr/0004-entity-metadata-is-a-virtual-crate.md index 35e6a26..9477780 100644 --- a/docs/adr/0004-entity-metadata-is-a-virtual-crate.md +++ b/docs/adr/0004-entity-metadata-is-a-virtual-crate.md @@ -4,14 +4,27 @@ arocapi serves an entity's Metadata, its RO-Crate metadata document, at `/entity/:id/metadata`, through the Metadata half of the storage backend, after checking the entity's metadata licence. A crate's `ro-crate-metadata.json` describes many entities, each with its own licences, and a large collection's runs to many megabytes. Oni asks for the metadata of the entity it is showing, not of the whole crate. +Crates in the repository spell LDaC and PCDM properties two ways: through the context (`communicationMode`, `hasMember`) or with a prefix (`ldac:communicationMode`, `pcdm:hasMember`). Oni reads the prefixed forms. Some crates also describe files the repository doesn't hold. + ## Decision -Each entity's Metadata is a virtual crate: a new RO-Crate with the entity as its root, plus every entity it links to, directly or through others. The root also gets the `Dataset` type, the crate root's `conformsTo` if it has none, and the crate's content licence as its `license` if it has none. The database indexer builds it when it indexes the crate and stores it in the entity's row as `meta.rocrate`, and arocapi's `EntityMetaMetadata` serves it from there. Nothing serves a crate's `ro-crate-metadata.json` as it is. +Each entity's Metadata is a virtual crate: a new RO-Crate with the entity as its root, plus every entity it links to, directly or through others. The indexer builds it when it indexes the crate and stores it in the entity's row as `meta.rocrate`, and arocapi's `EntityMetaMetadata` serves it from there. Nothing serves a crate's `ro-crate-metadata.json` as it is, and the crate in the repository is never changed. + +The virtual crate differs from what the depositor wrote in these ways only: + +- The root gets the `Dataset` type, the crate root's `conformsTo` if it has none, and the crate's content licence as its `license` if it has none. +- On the root and every entity it links to, a property whose term resolves to an LDaC terms IRI is named `ldac:`, and one that resolves to a PCDM IRI is named `pcdm:`. Where an entity has both spellings, their values are merged. +- A bare `memberOf` on a Collection, Object or File is named `pcdm:memberOf`. The RO-Crate context maps bare `memberOf` to schema.org's, so on a Person or Organisation it is left as it is. +- The `ldac` and `pcdm` prefixes are added to the depositor's `@context` if it lacks them. +- A File entity whose content the repository doesn't hold gets `display: false`, which Oni reads to offer no preview or download. ## Consequences - A request for one entity's Metadata gets only that entity and what it links to, guarded by that entity's metadata licence, rather than every entity in its crate. +- Oni and other readers see one spelling of LDaC and PCDM properties, whichever the crate used. - Metadata is only as fresh as the last index run: importing a new version of a crate changes nothing that is served until the crate is reindexed. - Serving Metadata reads only the database, never the OCFL repository. -- The virtual crate isn't a file in the crate, so it has no checksum or version of its own, and it differs from what the depositor wrote by the properties added to its root. +- The virtual crate isn't a file in the crate, so it has no checksum or version of its own, and it is not a faithful copy of what the depositor wrote. The deposited crate is only in the repository. +- `display` is Oni's convention, not a vocabulary term; a different reader won't know it. +- Other vocabularies, values and `@type`s are served as deposited, including any mistakes in them. - Rows are larger, as each holds a copy of what its entity links to. From 60b312a620011966b0993da5274b0f56edc81298 Mon Sep 17 00:00:00 2001 From: John Ferlito Date: Tue, 17 Nov 2026 13:11:12 +1100 Subject: [PATCH 2/2] docs: assume crates use the ldac: and pcdm: spellings The virtual crate no longer renames the older context-only spellings (communicationMode, memberOf), and the indexer reads only the prefixed forms. Updating an older crate is its owner's job. --- GLOSSARY.md | 2 +- docs/adr/0004-entity-metadata-is-a-virtual-crate.md | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 9404975..e51da7d 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -33,7 +33,7 @@ The search documents in arocapi's search backend, one per entity that has a row. _Avoid_: OpenSearch index (one backend's storage) **Virtual crate**: -The Metadata served for one entity: an RO-Crate with that entity as its root and everything it links to, with LDaC and PCDM properties in their prefixed spelling (ADR 0004). Never the crate as deposited. +The Metadata served for one entity: an RO-Crate with that entity as its root and everything it links to (ADR 0004). Never the crate as deposited. _Avoid_: Entity crate, exploded crate **Metadata-only crate**: diff --git a/docs/adr/0004-entity-metadata-is-a-virtual-crate.md b/docs/adr/0004-entity-metadata-is-a-virtual-crate.md index 9477780..8e54957 100644 --- a/docs/adr/0004-entity-metadata-is-a-virtual-crate.md +++ b/docs/adr/0004-entity-metadata-is-a-virtual-crate.md @@ -4,7 +4,7 @@ arocapi serves an entity's Metadata, its RO-Crate metadata document, at `/entity/:id/metadata`, through the Metadata half of the storage backend, after checking the entity's metadata licence. A crate's `ro-crate-metadata.json` describes many entities, each with its own licences, and a large collection's runs to many megabytes. Oni asks for the metadata of the entity it is showing, not of the whole crate. -Crates in the repository spell LDaC and PCDM properties two ways: through the context (`communicationMode`, `hasMember`) or with a prefix (`ldac:communicationMode`, `pcdm:hasMember`). Oni reads the prefixed forms. Some crates also describe files the repository doesn't hold. +The LDaC profile spells LDaC and PCDM properties with a prefix (`ldac:communicationMode`, `pcdm:memberOf`), and Oni reads those forms. Older crates spelt them through the context instead (`communicationMode`, `memberOf`). Some crates also describe files the repository doesn't hold. ## Decision @@ -13,18 +13,17 @@ Each entity's Metadata is a virtual crate: a new RO-Crate with the entity as its The virtual crate differs from what the depositor wrote in these ways only: - The root gets the `Dataset` type, the crate root's `conformsTo` if it has none, and the crate's content licence as its `license` if it has none. -- On the root and every entity it links to, a property whose term resolves to an LDaC terms IRI is named `ldac:`, and one that resolves to a PCDM IRI is named `pcdm:`. Where an entity has both spellings, their values are merged. -- A bare `memberOf` on a Collection, Object or File is named `pcdm:memberOf`. The RO-Crate context maps bare `memberOf` to schema.org's, so on a Person or Organisation it is left as it is. -- The `ldac` and `pcdm` prefixes are added to the depositor's `@context` if it lacks them. - A File entity whose content the repository doesn't hold gets `display: false`, which Oni reads to offer no preview or download. +Property names are served as deposited. Crates are assumed to use the prefixed spelling: the indexer reads LDaC and PCDM properties only in that form, and the virtual crate does not rename the older one. Bringing an older crate up to date is its owner's job. + ## Consequences - A request for one entity's Metadata gets only that entity and what it links to, guarded by that entity's metadata licence, rather than every entity in its crate. -- Oni and other readers see one spelling of LDaC and PCDM properties, whichever the crate used. +- A crate that still uses the older spelling is indexed without those properties: its entities have no parent from a bare `memberOf` or `hasMember`, are missing from the matching search facets, and Oni doesn't show the values. - Metadata is only as fresh as the last index run: importing a new version of a crate changes nothing that is served until the crate is reindexed. - Serving Metadata reads only the database, never the OCFL repository. - The virtual crate isn't a file in the crate, so it has no checksum or version of its own, and it is not a faithful copy of what the depositor wrote. The deposited crate is only in the repository. - `display` is Oni's convention, not a vocabulary term; a different reader won't know it. -- Other vocabularies, values and `@type`s are served as deposited, including any mistakes in them. +- Property names, values and `@type`s are served as deposited, including any mistakes in them. - Rows are larger, as each holds a copy of what its entity links to.