Skip to content

Document and update extension relationships #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zimeon wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Document and update extension relationships #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2a66233
Update extensions and docs
zimeon Jan 16, 2026
d1e5fed
More detail
zimeon Jan 16, 2026
8691a4a
Tidyl
zimeon Jan 16, 2026
442ad13
Tidy
zimeon Jan 16, 2026
519ad3f
Merge branch 'main' into extension-rels
zimeon Jan 16, 2026
91c149c
Add 0003-0012 related to
zimeon Jan 16, 2026
cbad978
Address @awoods comments https://github.com/OCFL/extensions/pull/95#p…
zimeon Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,24 +73,35 @@ Extensions submitted to this repository are considered community extensions and

Community extensions MUST be written as GitHub-flavored markdown files in this repository's `docs` directory. The filename of an extension is based on its *Registered Name* with a `.md` extension.

Extensions are numbered sequentially, and an extension's *Registered Name* is prefixed with this 4-digit, zero-padded decimal number. The *Registered Name* should be descriptive, use hyphens to separate words, and have a maximum of 250 characters.
Extensions are numbered sequentially, and the extension's *Registered Name* is prefixed with this 4-digit, zero-padded decimal number. The *Registered Name* should be descriptive, use hyphens to separate words, and have a maximum of 250 characters in total.

New extensions should use `NNNN` as a placeholder for the next available prefix number at the time of merging. New extension pull-requests should not update the index document (`docs/index.md`); this will be done after approval.

Once published, extensions are intended to be static. Substantial revisions of content beyond simple fixes warrant publishing a new extension and marking the old extension obsolete by updating the *Obsoletes/Obsoleted by* sections in each extension, respectively.
Once published, extensions are intended to be static. Substantial revisions of content beyond simple fixes warrant publishing a new extension and marking the old extension obsolete, extended or such by **Related to** sections in each extension (see [Headers](#headers)).

An example/template is available in this repository as "[OCFL Community Extension 0000: Example Extension](docs/0000-example-extension.md)" and is rendered via GitHub pages as https://ocfl.github.io/extensions/0000-example-extension

### Headers

Extension definitions MUST contain a header section that defines the following fields:

* **Extension Name**: The extension's unique *Registered Name*
* **Extension Name**: The extension's unique *Registered Name* (in a markdown code-span/backticks)
* **Authors**: The names of the individuals who authored the extension
* **Minimum OCFL Version**: The minimum OCFL version that the extension requires, eg. *1.0*
* **OCFL Community Extensions Version**: The version of the OCFL Extensions Specification that the extension conforms to, eg. *1.0*
* **Obsoletes**: The *Registered Name* of the extension that this extension obsoletes, or *n/a*
* **Obsoleted by**: The *Registered Name* of the extension that obsoletes this extension, or *n/a*
* **Minimum OCFL Version**: The minimum OCFL version that the extension requires, e.g. *1.0*
* **OCFL Community Extensions Version**: The version of the OCFL Extensions Specification that the extension conforms to, e.g. *1.0*
* **Related to**: A list of one or more qualified links to related extensions, or *n/a*

If present, the list of qualified links in **Related to** is a comma-plus-space separated set of links where each has the markdown form `[NNNN: Extension Name](regsistered_name.md) (relationship)` where the _relationship_ is one of:
* obsoletes - Use when a new extension SHOULD be used in preference to the prior extension. This may be because the new extensions corrects errors, or updates a canonical list, for example.
* obsoleted by - Inverse of obsoletes, the header of the existing extension that was made obsolete will be updated to record this.
* extends - Use when a new extension adds but does not remove or replace functionality compared to the prior extension, and there is nothing to suggest that use of the prior extension SHOULD be avoided.
* extended by - Inverse of extends, the header of the existing extension that was extended will be updated to record this

For an example, see [OCFL Community Extension 0001: Digest Algorithms](docs/0001-digest-algorithms.md) which includes:
* **Related to:** [0009: Digest Algorithms](docs/0009-digest-algorithms.md) (obsoleted by)

A future extension with multiple relations might have a **Related to** header such as:
* **Related to:** [NNNN: Older](#headers) (extends), [MMMM: Newer](#headers) (extended by)

### Parameters

Expand Down
5 changes: 2 additions & 3 deletions docs/0000-example-extension.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0000: Example Extension

* **Extension Name:** 0000-example-extension
* **Extension Name:** `0000-example-extension`
* **Authors:** A Person, Other Person
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

*Note: This is not a real extension, merely an example.*

Expand Down
5 changes: 2 additions & 3 deletions docs/0001-digest-algorithms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0001: Digest Algorithms

* **Extension Name:** 0001-digest-algorithms
* **Extension Name:** `0001-digest-algorithms`
* **Authors:** OCFL Editors
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** [0009-digest-algorithms](0009-digest-algorithms.md)
* **Related to:** [0009: Digest Algorithms](0009-digest-algorithms.md) (obsoleted by)

## Overview

Expand Down
6 changes: 2 additions & 4 deletions docs/0002-flat-direct-storage-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0002: Flat Direct Storage Layout

* **Extension Name:** 0002-flat-direct-storage-layout
* **Extension Name:** `0002-flat-direct-storage-layout`
* **Authors:** Peter Winckles
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

## Overview

Expand Down Expand Up @@ -66,4 +65,3 @@ This example demonstrates some mappings that produce directory names that are in
| --- | --- |
| info:fedora/object-01 | `info:fedora/object-01` |
| abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghij | `abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghij` |

5 changes: 2 additions & 3 deletions docs/0003-hash-and-id-n-tuple-storage-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0003: Hashed Truncated N-tuple Trees with Object ID Encapsulating Directory for OCFL Storage Hierarchies

* **Extension Name:** 0003-hash-and-id-n-tuple-storage-layout
* **Extension Name:** `0003-hash-and-id-n-tuple-storage-layout`
* **Authors:** Ben Cail
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** [0012: Hashed Truncated N-tuple Trees with Non-prefixed Object ID Encapsulating Directory for OCFL Storage Hierarchies](0012-hash-and-no-prefix-id-n-tuple-storage-layout.md) (extended by)

## Overview

Expand Down
5 changes: 2 additions & 3 deletions docs/0004-hashed-n-tuple-storage-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0004: Hashed N-tuple Storage Layout

* **Extension Name:** 0004-hashed-n-tuple-storage-layout
* **Extension Name:** `0004-hashed-n-tuple-storage-layout`
* **Authors:** Peter Winckles
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

## Overview

Expand Down
5 changes: 2 additions & 3 deletions docs/0005-mutable-head.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0005: Mutable HEAD

* **Extension Name:** 0005-mutable-head
* **Extension Name:** `0005-mutable-head`
* **Authors:** Peter Winckles
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

## Overview

Expand Down
5 changes: 2 additions & 3 deletions docs/0006-flat-omit-prefix-storage-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0006: Flat Omit Prefix Storage Layout

* **Extension Name:** 0006-flat-omit-prefix-storage-layout
* **Extension Name:** `0006-flat-omit-prefix-storage-layout`
* **Authors:** Andrew Woods
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

## Overview

Expand Down
14 changes: 6 additions & 8 deletions docs/0007-n-tuple-omit-prefix-storage-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,20 @@
# OCFL Community Extension 0007: N Tuple Omit Prefix Storage Layout

* **Extension Name:** 0007-n-tuple-omit-prefix-storage-layout
* **Extension Name:** `0007-n-tuple-omit-prefix-storage-layout`
* **Authors:** Michael Vandermillen and Andrew Woods
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

## Overview

This storage root extension describes an OCFL storage layout combining a pairtree-like root directory structure derived from prefix-omitted object identifiers, followed by the prefix-omitted object identifier themselves.
The OCFL object identifiers are expected to contain prefixes which are removed in the mapping to directory names.
This storage root extension describes an OCFL storage layout combining a pairtree-like root directory structure derived from prefix-omitted object identifiers, followed by the prefix-omitted object identifier themselves.
The OCFL object identifiers are expected to contain prefixes which are removed in the mapping to directory names.
The OCFL object identifier prefix is defined as all characters before and including a configurable delimiter.
Where the prefix-omitted identifier length is less than tuple size * number of tuples, the remaining object id (prefix omitted) is left or right-side, zero-padded (configurable, left default), and optionally reversed (default false).
The object id is then divided into N n-tuple segments, and used to create nested paths under the OCFL storage root, followed by the prefix-omitted object id directory.

This layout combines the advantages of 0006-flat-omit-prefix-storage-layout (directory name transparency) and the 0004-hashed-n-tuple-storage-layout (enhanced file system/bucket performance).
This layout combines the advantages of 0006-flat-omit-prefix-storage-layout (directory name transparency) and the 0004-hashed-n-tuple-storage-layout (enhanced file system/bucket performance).

The limitations of this layout are filesystem dependent (with one exception), and are generally as follows:

Expand Down Expand Up @@ -126,7 +125,7 @@ identifier, with default `zeroPadding`, modified `tupleSize` and `numberOfTuples
├── inventory.json
├── inventory.json.sha512
└── v1 [...]

```

### Example 2
Expand Down Expand Up @@ -180,4 +179,3 @@ identifier, with default `tupleSize`, `numberOfTuples`, and `reverseObjectRoot`,
├── inventory.json.sha512
└── v1 [...]
```

5 changes: 2 additions & 3 deletions docs/0008-schema-registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0008: Schema Registry

* **Extension Name:** 0008-schema-registry
* **Extension Name:** `0008-schema-registry`
* **Authors:** P. Cornwell, D. Granville
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

## Overview

Expand Down
5 changes: 2 additions & 3 deletions docs/0009-digest-algorithms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0009: Digest Algorithms

* **Extension Name:** 0009-digest-algorithms
* **Extension Name:** `0009-digest-algorithms`
* **Authors:** OCFL Editors, T. Wrobel
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** [0001-digest-algorithms](0001-digest-algorithms.md)
* **Obsoleted by:** n/a
* **Related to:** [0001: Digest Algorithms](0001-digest-algorithms.md) (obsoletes)

## Overview

Expand Down
5 changes: 2 additions & 3 deletions docs/0010-differential-n-tuple-omit-prefix-storage-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0010: Differential N-Tuple Omit Prefix Storage Layout

* **Extension Name:** 0010-differential-n-tuple-omit-prefix-storage-layout
* **Extension Name:** `0010-differential-n-tuple-omit-prefix-storage-layout`
* **Authors:** Mike Giarlo
* **Minimum OCFL Version:** 1.1
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

## Overview

Expand Down
11 changes: 5 additions & 6 deletions docs/0011-direct-clean-path-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0011: Direct Clean Path Layout

* **Extension Name:** 0011-direct-clean-path-layout
* **Authors:** Jürgen Enge (Basel)
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Extension Name:** `0011-direct-clean-path-layout`
* **Authors:** Jürgen Enge (Basel)
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Related to:** n/a

## Overview

Expand Down
5 changes: 2 additions & 3 deletions docs/0012-hash-and-no-prefix-id-n-tuple-storage-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# OCFL Community Extension 0012: Hashed Truncated N-tuple Trees with Non-prefixed Object ID Encapsulating Directory for OCFL Storage Hierarchies

* **Extension Name:** 0012-hash-and-no-prefix-id-n-tuple-storage-layout
* **Extension Name:** `0012-hash-and-no-prefix-id-n-tuple-storage-layout`
* **Authors:** Elie Roux
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** [0003: Hashed Truncated N-tuple Trees with Encapsulating Directory for OCFL Storage Hierarchies](0003-hash-and-id-n-tuple-storage-layout.md) (extends)

## Overview

Expand Down
3 changes: 1 addition & 2 deletions docs/initial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@
* **Authors:** OCFL Editors
* **Minimum OCFL Version:** 1.0
* **OCFL Community Extensions Version:** 1.0
* **Obsoletes:** n/a
* **Obsoleted by:** n/a
* **Related to:** n/a

## Overview

Expand Down