From a6e5f7fe5a3cf8c338ddf0ac67ae89149e8a2c7e Mon Sep 17 00:00:00 2001 From: Jan van Mansum Date: Tue, 5 Aug 2025 12:14:50 +0200 Subject: [PATCH 1/4] This extension provides a way to record properties of an OCFL object version beyond the standard properties defined by OCFL itself (`created`, `message`, etc.). This may be useful for cases where additional information about the version is needed, which cannot conveniently be stored in the object itself in a standard way. Another use-case may be a property that is not available at the time the version content is created. --- docs/NNNN-object-version-properties.md | 103 +++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/NNNN-object-version-properties.md diff --git a/docs/NNNN-object-version-properties.md b/docs/NNNN-object-version-properties.md new file mode 100644 index 0000000..557706b --- /dev/null +++ b/docs/NNNN-object-version-properties.md @@ -0,0 +1,103 @@ +OCFL Community Extension NNNN: Object Version Properties +========================================= + +- **Extension Name:** NNNN-object-version-properties +- **Authors:** Linda Reijnhoudt, Jan van Mansum +- **Minimum OCFL Version:** 1.0 +* **OCFL Community Extensions Version:** 1.0 +* **Obsoletes:** n/a +* **Obsoleted by:** n/a + +Overview +-------- + +This extension provides a way to record properties of an OCFL object version beyond the standard properties defined by OCFL itself (`created`, `message`, etc.). +This may be useful for cases where additional information about the version is needed, which cannot conveniently be stored in the object itself in a standard +way. Another use-case may be a property that is not available at the time the version content is created. + +This extension only describes how the properties should be recorded, it does not prescribe what properties should be recorded or their semantics. One way to +define the semantics of properties is to use the [Property Registry extension](../property-registry/property-registry.md). + +The object_version_properties.json file +--------------------------------------- + +The object version properties are stored in a JSON file named `object_version_properties.json` in the extensions directory of the OCFL object. This file must +contain entries for all versions in this object. Each version entry has as key the version identifier (e.g. `v1`, `v2`, etc.) and as value a JSON object with +the properties for that version. If no properties are recorded for a version, the entry for that version must be an empty JSON object. + +The properties recorded under a version key pertain to that version only, so when a new version is created, properties that do not change must be copied from +the previous version. Otherwise, this extension does not restrict the properties that can be recorded, nor does it define their semantics. + +Implementation +-------------- + +Clients that implement this extension must validate that the `object_version_properties.json` file is well-formed JSON and that it contains an entry for each +version in the object as part of the validation of the OCFL object. + +Clients may support storing the version properties when creating a new version of an OCFL object, by passing the properties map as an extra parameter to the +version creation method. Likewise, clients may support retrieving the properties for a specific version of an OCFL object as a properties map. Other optional +features may include the ability to search for object versions based on their properties. + +Examples +-------- + +### 1. Simple property + +If the repository wants to record a simple property, for instance the User-Agent that made the request to create this version, this could be done as follows. + +```text +[storage_root] + ├── 0=ocfl_1.0 + ├── ocfl_1.0.txt + ├── ocfl_layout.json + ├── object-version-properties.md + ├── 0de + | └── 45c + | └── f24 + | └── item1 + │ └── 0=ocfl_object_1.0 + │ ├── inventory.json + │ ├── inventory.json.sha512 + | └── extensions + │ └── object-version-properties/ + │ ├── object_version_properties.json + │ └── object_version_properties.json.sha512 + └────────────────── v1/ + ├── inventory.json + ├── inventory.json.sha512 + └── content/ + └── ... files ... +``` + +The `object-version-properties.json` of the OCFL object could have the following entry: + +```json +{ + "v1": { + "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" + } +} +``` + +### 2. Complex property + +If the repository wants to record a complex object for a version, for instance that it has been deaccessioned, this could be done with a similar structure. The +`object-version-properties.json` of the OCFL object might have the following entry: + +```json +{ + "v1": { + "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" + }, + "v2": { + "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", + "deaccessioned": { + "datetime": "2025-10-15T13:19:00", + "reason": "Deaccessioned because dataset was deleted in Easy" + } + } +} +``` + +Note, that this example also demonstrates that a property that remains unchanged between versions (in this case "User-Agent") must be copied from the previous +version. From 1befbf900d73c220de140dbeb14ef2f0ed63ee53 Mon Sep 17 00:00:00 2001 From: Jan van Mansum Date: Tue, 5 Aug 2025 12:15:45 +0200 Subject: [PATCH 2/4] Ignore .idea --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index b25c15b..96e84cf 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ *~ +/.idea From cf40ee95b9b25bac76dbed72c5c6fc4e44392d23 Mon Sep 17 00:00:00 2001 From: Jan van Mansum Date: Tue, 5 Aug 2025 12:36:44 +0200 Subject: [PATCH 3/4] Improved markdown consitency --- docs/NNNN-object-version-properties.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/NNNN-object-version-properties.md b/docs/NNNN-object-version-properties.md index 557706b..6c4496e 100644 --- a/docs/NNNN-object-version-properties.md +++ b/docs/NNNN-object-version-properties.md @@ -1,9 +1,9 @@ OCFL Community Extension NNNN: Object Version Properties ========================================= -- **Extension Name:** NNNN-object-version-properties -- **Authors:** Linda Reijnhoudt, Jan van Mansum -- **Minimum OCFL Version:** 1.0 +* **Extension Name:** NNNN-object-version-properties +* **Authors:** Linda Reijnhoudt, Jan van Mansum +* **Minimum OCFL Version:** 1.0 * **OCFL Community Extensions Version:** 1.0 * **Obsoletes:** n/a * **Obsoleted by:** n/a From 93d8cfb69495892e10b660735000537689fe908e Mon Sep 17 00:00:00 2001 From: Jan van Mansum Date: Fri, 8 Aug 2025 09:43:30 +0200 Subject: [PATCH 4/4] Specify algorithm for sidecar file --- docs/NNNN-object-version-properties.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/NNNN-object-version-properties.md b/docs/NNNN-object-version-properties.md index 6c4496e..a0f1043 100644 --- a/docs/NNNN-object-version-properties.md +++ b/docs/NNNN-object-version-properties.md @@ -18,6 +18,12 @@ way. Another use-case may be a property that is not available at the time the ve This extension only describes how the properties should be recorded, it does not prescribe what properties should be recorded or their semantics. One way to define the semantics of properties is to use the [Property Registry extension](../property-registry/property-registry.md). +The object-version-properties extension is implemented by creating and maintaining the following items: + +* A `object_version_properties.json` file containing the properties for each version of the OCFL object. +* A sidecar file `object_version_properties.json.sha512` (or other configured digest) containing the digest of the `object_version_properties.json` file, in + the same manner as the OCFL inventory files. The digest algorithm must be the same as the one used for the OCFL inventory files. + The object_version_properties.json file ---------------------------------------