Storage Root Feature Flags

[zimeon]

We plan to add a set of feature flags to declare use of v2 features and enable validation based on that. See also:

• Content Linking (spec) #668 - Content Linking
• Tombstones Spec changes #669 - Tombstones
• ??? - Version Packaging

[zimeon]

Summary of proposed specification changes based on 2025-08-18 Extended Editors Meeting. This would be part of the Storage Root description.

Storage Root Feature Flags

The ocfl_features.json file at the Storage Root level provides OCFL tooling an indication of what OCFL version 2 and higher features are used in the Storage Root. The ocfl_features.json file MUST be present for OCFLv2.0 or higher storage roots. It MAY be present in storage roots declaring OCFL v1.0 or v1.1 compliance but SHOULD be ignored because it might have other locally-defined purposes.

If present, ocfl_features.json MUST be a JSON (defined by [RFC8259]) document encoded in UTF-8 with a root JSON object.

• The root JSON object MUST contain only keys corresponding to the features: links, tombstone, version_packaging (additional keys may be added in later OCFL versions)
  • If the key is not present, then it indicates that the feature is not used in the Storage Root.
• The value for any of the keys MUST be a JSON Object which MAY contain the key used and MUST NOT contain any other key (additional keys may be added in later OCFL versions)
  • The value of the used key MUST be boolean (true or false)
  • Absence of the used key is the same as having value false.
  • A value used=true indicates that the feature may be used within the storage root

The features are as follows:

• links - indicates whether Objects may include a links block to refer to content from other objects in the Storage Root.
• tombstones - indicates whether Objects may include a tombstones block to record deleted, lost or corrupted content files.
• version_packaging - indicates whether Objects may include a packages.json file at the version level to record how version content has been packaged.

A Storage Root validator encountering use of the feature MUST flag an error unless use of the feature was declared in ocfl_features.json.

Example ocfl_features.json

The following indicates that tombstones are used, links and version packaging are not used.

{
  "tombstones" : { "used": true },
  "links" : { },
  "version_packaging":{ "used": false }
}

The following has the same meaning because absence of the feature key implies that the feature is not used (same as empty or { "used": false } ).

{
  "tombstones" : { "used": true }
}

[awoods]

This looks great, @zimeon.