diff --git a/README.md b/README.md index 7fd3fb4..5e1d9a9 100644 --- a/README.md +++ b/README.md @@ -73,11 +73,11 @@ 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 @@ -85,12 +85,23 @@ An example/template is available in this repository as "[OCFL Community Extensio 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 diff --git a/docs/0000-example-extension.md b/docs/0000-example-extension.md index cb21b84..ef4207f 100644 --- a/docs/0000-example-extension.md +++ b/docs/0000-example-extension.md @@ -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.* diff --git a/docs/0001-digest-algorithms.md b/docs/0001-digest-algorithms.md index 4151b36..be2e677 100644 --- a/docs/0001-digest-algorithms.md +++ b/docs/0001-digest-algorithms.md @@ -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 diff --git a/docs/0002-flat-direct-storage-layout.md b/docs/0002-flat-direct-storage-layout.md index bab894c..a0e1b1d 100644 --- a/docs/0002-flat-direct-storage-layout.md +++ b/docs/0002-flat-direct-storage-layout.md @@ -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 @@ -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` | - diff --git a/docs/0003-hash-and-id-n-tuple-storage-layout.md b/docs/0003-hash-and-id-n-tuple-storage-layout.md index c1f181c..75fc238 100644 --- a/docs/0003-hash-and-id-n-tuple-storage-layout.md +++ b/docs/0003-hash-and-id-n-tuple-storage-layout.md @@ -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 diff --git a/docs/0004-hashed-n-tuple-storage-layout.md b/docs/0004-hashed-n-tuple-storage-layout.md index 0caa0bd..5d195dd 100644 --- a/docs/0004-hashed-n-tuple-storage-layout.md +++ b/docs/0004-hashed-n-tuple-storage-layout.md @@ -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 diff --git a/docs/0005-mutable-head.md b/docs/0005-mutable-head.md index 4674581..2fc6269 100644 --- a/docs/0005-mutable-head.md +++ b/docs/0005-mutable-head.md @@ -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 diff --git a/docs/0006-flat-omit-prefix-storage-layout.md b/docs/0006-flat-omit-prefix-storage-layout.md index 0e28ba3..e60c44e 100644 --- a/docs/0006-flat-omit-prefix-storage-layout.md +++ b/docs/0006-flat-omit-prefix-storage-layout.md @@ -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 diff --git a/docs/0007-n-tuple-omit-prefix-storage-layout.md b/docs/0007-n-tuple-omit-prefix-storage-layout.md index a7a7eb3..78cc7e5 100644 --- a/docs/0007-n-tuple-omit-prefix-storage-layout.md +++ b/docs/0007-n-tuple-omit-prefix-storage-layout.md @@ -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: @@ -126,7 +125,7 @@ identifier, with default `zeroPadding`, modified `tupleSize` and `numberOfTuples ├── inventory.json ├── inventory.json.sha512 └── v1 [...] - + ``` ### Example 2 @@ -180,4 +179,3 @@ identifier, with default `tupleSize`, `numberOfTuples`, and `reverseObjectRoot`, ├── inventory.json.sha512 └── v1 [...] ``` - diff --git a/docs/0008-schema-registry.md b/docs/0008-schema-registry.md index 92fefd3..db4496f 100644 --- a/docs/0008-schema-registry.md +++ b/docs/0008-schema-registry.md @@ -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 diff --git a/docs/0009-digest-algorithms.md b/docs/0009-digest-algorithms.md index f12ca02..d968b92 100644 --- a/docs/0009-digest-algorithms.md +++ b/docs/0009-digest-algorithms.md @@ -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 diff --git a/docs/0010-differential-n-tuple-omit-prefix-storage-layout.md b/docs/0010-differential-n-tuple-omit-prefix-storage-layout.md index b0d523d..77e4ebc 100644 --- a/docs/0010-differential-n-tuple-omit-prefix-storage-layout.md +++ b/docs/0010-differential-n-tuple-omit-prefix-storage-layout.md @@ -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 diff --git a/docs/0011-direct-clean-path-layout.md b/docs/0011-direct-clean-path-layout.md index 2eadee8..3f1455a 100644 --- a/docs/0011-direct-clean-path-layout.md +++ b/docs/0011-direct-clean-path-layout.md @@ -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 diff --git a/docs/0012-hash-and-no-prefix-id-n-tuple-storage-layout.md b/docs/0012-hash-and-no-prefix-id-n-tuple-storage-layout.md index ade0d98..6804872 100644 --- a/docs/0012-hash-and-no-prefix-id-n-tuple-storage-layout.md +++ b/docs/0012-hash-and-no-prefix-id-n-tuple-storage-layout.md @@ -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 diff --git a/docs/initial.md b/docs/initial.md index 376543e..df5f2a0 100644 --- a/docs/initial.md +++ b/docs/initial.md @@ -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