From aa9c4c2e6e1de94c048bb8ad574138c2b7d448c9 Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Wed, 3 Jun 2020 09:28:22 +0100 Subject: [PATCH 01/10] Update README.md Clarify versioning and some tidying up --- README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b670b10..2a508b0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # OCFL Community Extensions -This repository is intended as a place for community extensions to the [OCFL Specification and Implementation Notes](https://ocfl.io/). Community extensions are intended as a way to share and collaborate outside of the specification process. They are intended to be citable and mostly static once published. Substantial revisions of content beyond simple fixes warrants publishing a new extension, perhaps marking the old one deprecated. Anybody may propose a community extension via a pull-request (PR) against this repository. The community will review and discuss it before it is merged in. +This repository is intended as a place for community extensions to the [OCFL Specification and Implementation Notes](https://ocfl.io/). Community extensions are intended as a way to share and collaborate outside of the specification process. They are intended to be citable and mostly static once published. Substantial revisions of content beyond simple fixes warrants publishing a new extension, marking the old one obsoleted by updating the *Obsoletes/Obsoleted by* sections in the old and new extension documents respectively. Anybody may propose a community extension via a pull-request (PR) against this repository. The community will review and discuss it before it is merged in. The current set of extensions can be read on [GitHub Pages](https://ocfl.github.io/extensions/). @@ -8,7 +8,7 @@ See also [pending pull requests](https://github.com/OCFL/extensions/pulls) for e ## Organization of this repository -Community extensions should be written as GitHub flavored markdown in the `docs` directory of this repository. They should be numbered sequentially using a 4-digit, zero-padded prefix; should use hyphens to separate words; and have the `.md` extension. +Community extensions should be written as GitHub flavored markdown in the `docs` directory of this repository. They should be numbered sequentially using a 4-digit, zero-padded decimal prefix; should use hyphens to separate words; and have the `.md` extension. New, or substantially revised, extensions MUST use the next available number based on extensions current at the time of merging. An example/template is available in this repository as [OCFL Community Extension](docs/0000-example-extension) and is rendered via GitHub pages as https://ocfl.github.io/extensions/0000-example-extension @@ -29,22 +29,24 @@ length limit is based on a survey of the defaults for various JSON parsers. extension which MUST reference all the parameters. * Type: Data type for the parameter. In order to allow validation and limit the scope for implementation specific variations, parameters are typed. - * integer - may be signed or not as specified in the range parameter. + * integer - may be signed or not as specified in the range property. * string - aligned with JSON strings, these should be UTF-8 encoded and avoid control characters. * enumerated - one of an ordered set of labels which MUST conform to the same limitations as parameter names. - * boolean - may have the values false or true (lower case and unquoted as in JSON) - * For integer parameters the range specifies minimum and maximum values, separated by a comma, which MUST be integers themselves. - * For string parameters, the range specifies the maximum length of the string as an integer number of characters, not bytes. Again, based on a survey of parsers, try to keep strings shorter than 4095 characters. + * boolean - MUST have the value *false* or *true* (lower case and unquoted as in JSON) +* Range: Further qualifies the valid values for a paramater depending on its type. + * For integer parameters, the range specifies minimum and maximum values, separated by a comma, which MUST be integers themselves. + * For string parameters, the range specifies the maximum length of the string as an integer number of characters, not bytes. Again, based on a survey of parsers, strings SHOULD be shorter than 4095 characters. * For enumerated parameters, the range is a comma separated ordered list of labels that are valid for the parameter. Enumerated parameters are case sensitive and MUST always be quoted, so they are JSON strings. -* Default: Default value for parameter, which MUST be consistent with the range limitations. If this is left blank then the parameter is mandatory +* Default: Default value for parameter, which MUST be consistent with the range limitations. If this is left blank then the parameter is mandatory (if parameters are defined) ## Referencing Parameters -Wherever a parameterised extension is referenced, include any parameters in an accompanying JSON file. If using an extensions directory, the JSON file MUST be named for the extension and included in the directory. For example, the example extension above would have an accompanying file *0000-example-extension.json* which might contain: +Wherever a parameterised extension is referenced, any parameters MAY be included in an accompanying JSON file. If using an extensions directory, the JSON file MUST be named for the extension and included in the directory. For example, the example extension above would have an accompanying file *0000-example-extension.json* which might contain: "0000-example-extension.md": { "firstExampleParameter": 12, "secondExampleParameter": "Hello", "thirdExampleParameter": "Green" } -There MUST only be one parameter set defined for each extension. + +An extension MAY be referenced without providing any paramaters, even if they are defined for that extension. However, if parameters are defined they MUST be complete, with valid values specified for all parameters that do not have a default. There MUST only be one parameter set defined for each extension reference. From 2a865f83c0f556e39602e36473de1a5ee5f48946 Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Wed, 3 Jun 2020 09:34:44 +0100 Subject: [PATCH 02/10] Update 0001-digest-algorithms.md Clarified wording around maintenance --- docs/0001-digest-algorithms.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/0001-digest-algorithms.md b/docs/0001-digest-algorithms.md index 02fb802..7fc1e8d 100644 --- a/docs/0001-digest-algorithms.md +++ b/docs/0001-digest-algorithms.md @@ -20,4 +20,7 @@ This extension is an index of additional digest algorithms. It provides a contro ## Maintenance -In order to have an additional digest algorithm listed here, please submit a pull request on this extension that adds it to the table. New entries should have a name that does not conflict with those defined in the [OCFL Specification](https://ocfl.io/latest/spec/) or this community extension, and is preferably in common use for the given algorithm. In the case that long description is required it may be appropriate to submit a new extension describing the algorithm along with an update to this extension that links to it. +In order to have an additional digest algorithm listed here, please submit a pull request on this extension that: +* Adds the algorithm to the table. New entries should have a name that does not conflict with those defined in the [OCFL Specification](https://ocfl.io/latest/spec/) or this community extension, and is preferably in common use for the given algorithm. +* Creates a new version of this extension with the next available extension number, obsoleting the current one +* If a long algorithm description is required it may be appropriate to submit an additional new extension describing the algorithm along with an update to this extension that links to it. From 828c987464554dbf581f69f7f2c269d9b1906bed Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Wed, 3 Jun 2020 09:36:23 +0100 Subject: [PATCH 03/10] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2a508b0..f8e3c50 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # OCFL Community Extensions -This repository is intended as a place for community extensions to the [OCFL Specification and Implementation Notes](https://ocfl.io/). Community extensions are intended as a way to share and collaborate outside of the specification process. They are intended to be citable and mostly static once published. Substantial revisions of content beyond simple fixes warrants publishing a new extension, marking the old one obsoleted by updating the *Obsoletes/Obsoleted by* sections in the old and new extension documents respectively. Anybody may propose a community extension via a pull-request (PR) against this repository. The community will review and discuss it before it is merged in. +This repository is intended as a place for community extensions to the [OCFL Specification and Implementation Notes](https://ocfl.io/). Community extensions are intended as a way to share and collaborate outside of the specification process. They are intended to be citable and mostly static once published. Substantial revisions of content beyond simple fixes warrants publishing a new extension, marking the old one obsoleted by updating the *Obsoletes/Obsoleted by* sections in the new and old extension documents respectively. Anybody may propose a community extension via a pull-request (PR) against this repository. The community will review and discuss it before it is merged in. The current set of extensions can be read on [GitHub Pages](https://ocfl.github.io/extensions/). From 2a203c59a0d4ae3bc4fb2d396deaff64be2c00dd Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Tue, 16 Jun 2020 15:18:48 +0100 Subject: [PATCH 04/10] Update README.md --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f8e3c50..0e75701 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,12 @@ See also [pending pull requests](https://github.com/OCFL/extensions/pulls) for e ## Organization of this repository -Community extensions should be written as GitHub flavored markdown in the `docs` directory of this repository. They should be numbered sequentially using a 4-digit, zero-padded decimal prefix; should use hyphens to separate words; and have the `.md` extension. New, or substantially revised, extensions MUST use the next available number based on extensions current at the time of merging. +Community extensions should be written as GitHub flavored markdown files in the `docs` directory of this repository. The +filenames should be numbered sequentially using a 4-digit, zero-padded decimal prefix; should use hyphens to separate words; +have the `.md` extension; and have a maximum of 255 characters. New, or substantially revised, extensions MUST use the next +available number based on extensions current at the time of merging. + +The *Registered Name* of an extension is the name of the extension file in the `docs` directory, excluding the `.md` extension. An example/template is available in this repository as [OCFL Community Extension](docs/0000-example-extension) and is rendered via GitHub pages as https://ocfl.github.io/extensions/0000-example-extension @@ -33,7 +38,7 @@ parameters are typed. * string - aligned with JSON strings, these should be UTF-8 encoded and avoid control characters. * enumerated - one of an ordered set of labels which MUST conform to the same limitations as parameter names. * boolean - MUST have the value *false* or *true* (lower case and unquoted as in JSON) -* Range: Further qualifies the valid values for a paramater depending on its type. +* Range: Further qualifies the valid values for a parameter depending on its type. * For integer parameters, the range specifies minimum and maximum values, separated by a comma, which MUST be integers themselves. * For string parameters, the range specifies the maximum length of the string as an integer number of characters, not bytes. Again, based on a survey of parsers, strings SHOULD be shorter than 4095 characters. * For enumerated parameters, the range is a comma separated ordered list of labels that are valid for the parameter. Enumerated parameters are case sensitive and MUST always be quoted, so they are JSON strings. @@ -41,7 +46,9 @@ parameters are typed. ## Referencing Parameters -Wherever a parameterised extension is referenced, any parameters MAY be included in an accompanying JSON file. If using an extensions directory, the JSON file MUST be named for the extension and included in the directory. For example, the example extension above would have an accompanying file *0000-example-extension.json* which might contain: +Wherever a parameterised extension is referenced, any parameters MAY be included in an accompanying JSON file. If using an +extensions directory, the JSON file MUST be named for the extension and included in the directory (not a subdirectory). +For example, the example extension above would have an accompanying file *0000-example-extension.json* which might contain: "0000-example-extension.md": { "firstExampleParameter": 12, @@ -49,4 +56,4 @@ Wherever a parameterised extension is referenced, any parameters MAY be included "thirdExampleParameter": "Green" } -An extension MAY be referenced without providing any paramaters, even if they are defined for that extension. However, if parameters are defined they MUST be complete, with valid values specified for all parameters that do not have a default. There MUST only be one parameter set defined for each extension reference. +An extension MAY be referenced without providing any parameters, even if they are defined for that extension. However, if parameters are defined they MUST be complete, with valid values specified for all parameters that do not have a default. There MUST only be one parameter set defined for each extension reference. From 2f147d812e384d08ff71f949c65bc94110d44c79 Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Tue, 16 Jun 2020 15:31:24 +0100 Subject: [PATCH 05/10] Update README.md --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0e75701..1f950bc 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ See also [pending pull requests](https://github.com/OCFL/extensions/pulls) for e Community extensions should be written as GitHub flavored markdown files in the `docs` directory of this repository. The filenames should be numbered sequentially using a 4-digit, zero-padded decimal prefix; should use hyphens to separate words; -have the `.md` extension; and have a maximum of 255 characters. New, or substantially revised, extensions MUST use the next +have the `.md` extension; and have a maximum of 250 characters. New, or substantially revised, extensions MUST use the next available number based on extensions current at the time of merging. The *Registered Name* of an extension is the name of the extension file in the `docs` directory, excluding the `.md` extension. @@ -46,8 +46,11 @@ parameters are typed. ## Referencing Parameters -Wherever a parameterised extension is referenced, any parameters MAY be included in an accompanying JSON file. If using an -extensions directory, the JSON file MUST be named for the extension and included in the directory (not a subdirectory). +Wherever a parameterised extension is referenced, any parameters MAY be included in an accompanying sidecar JSON file that +uses the registered name with the filename extension `.json`. If using an 'extensions' directory, the JSON file MUST be +included at the top level of the directory and not a subdirectory. Another place that an extension may be referenced is +`OCFL_layout.json` where the sidecar file should be alongside it in the Storage Root. + For example, the example extension above would have an accompanying file *0000-example-extension.json* which might contain: "0000-example-extension.md": { From ca52ea53d4b97e7e12dac6fd5f485919e3d9c679 Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Tue, 16 Jun 2020 15:39:02 +0100 Subject: [PATCH 06/10] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1f950bc..4a30fda 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ parameters are typed. Wherever a parameterised extension is referenced, any parameters MAY be included in an accompanying sidecar JSON file that uses the registered name with the filename extension `.json`. If using an 'extensions' directory, the JSON file MUST be included at the top level of the directory and not a subdirectory. Another place that an extension may be referenced is -`OCFL_layout.json` where the sidecar file should be alongside it in the Storage Root. +`ocfl_layout.json` where the sidecar file should be alongside it in the Storage Root. For example, the example extension above would have an accompanying file *0000-example-extension.json* which might contain: From 266f97a59f5f94d09acde371bc8d44fae463ebd3 Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Tue, 18 Aug 2020 12:09:36 +0100 Subject: [PATCH 07/10] Update README.md Updated Registered name definition and specified parameter location more clearly. --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4a30fda..9556224 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,12 @@ See also [pending pull requests](https://github.com/OCFL/extensions/pulls) for e ## Organization of this repository Community extensions should be written as GitHub flavored markdown files in the `docs` directory of this repository. The -filenames should be numbered sequentially using a 4-digit, zero-padded decimal prefix; should use hyphens to separate words; -have the `.md` extension; and have a maximum of 250 characters. New, or substantially revised, extensions MUST use the next -available number based on extensions current at the time of merging. +filename of an extension is based on its *Registered Name* with a `.md` extension. -The *Registered Name* of an extension is the name of the extension file in the `docs` directory, excluding the `.md` extension. +Extensions are numbered sequentially, and the *Registered Name* of an extension 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, or substantially revised, extensions MUST use the next available number based on extensions current +at the time of merging. The *Registered Name* MUST be listed in the header of the extension file. An example/template is available in this repository as [OCFL Community Extension](docs/0000-example-extension) and is rendered via GitHub pages as https://ocfl.github.io/extensions/0000-example-extension @@ -48,8 +49,8 @@ parameters are typed. Wherever a parameterised extension is referenced, any parameters MAY be included in an accompanying sidecar JSON file that uses the registered name with the filename extension `.json`. If using an 'extensions' directory, the JSON file MUST be -included at the top level of the directory and not a subdirectory. Another place that an extension may be referenced is -`ocfl_layout.json` where the sidecar file should be alongside it in the Storage Root. +included in the root directory of the extension and not a subdirectory. Another place that an extension may be +referenced is `ocfl_layout.json` where the sidecar file should be alongside it in the Storage Root. For example, the example extension above would have an accompanying file *0000-example-extension.json* which might contain: From 710c66527a4dc777c8c65e34da49b38d1df2a3c3 Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Tue, 18 Aug 2020 12:10:54 +0100 Subject: [PATCH 08/10] Update 0000-example-extension.md --- docs/0000-example-extension.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/0000-example-extension.md b/docs/0000-example-extension.md index 25fe4a7..225e1ad 100644 --- a/docs/0000-example-extension.md +++ b/docs/0000-example-extension.md @@ -1,5 +1,6 @@ # OCFL Community Extension 0000: Example Extension + * Extension Name: 0000-example-extnesion * Authors: A Person, Other Person * Minimum OCFL Version: 1.0 * Obsoletes: n/a From 421fdd1a2179eadac8f81f25454c4b343eb0c7a2 Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Tue, 18 Aug 2020 12:11:19 +0100 Subject: [PATCH 09/10] Update 0000-example-extension.md Added name --- docs/0000-example-extension.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/0000-example-extension.md b/docs/0000-example-extension.md index 225e1ad..0f7f1d8 100644 --- a/docs/0000-example-extension.md +++ b/docs/0000-example-extension.md @@ -1,6 +1,6 @@ # OCFL Community Extension 0000: Example Extension - * Extension Name: 0000-example-extnesion + * Extension Name: 0000-example-extension * Authors: A Person, Other Person * Minimum OCFL Version: 1.0 * Obsoletes: n/a From c118c232c4665dec2b596a791e59751a6723f3aa Mon Sep 17 00:00:00 2001 From: neilsjefferies <37909475+neilsjefferies@users.noreply.github.com> Date: Tue, 18 Aug 2020 12:12:27 +0100 Subject: [PATCH 10/10] Update 0001-digest-algorithms.md Added name --- docs/0001-digest-algorithms.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/0001-digest-algorithms.md b/docs/0001-digest-algorithms.md index 7fc1e8d..36da31c 100644 --- a/docs/0001-digest-algorithms.md +++ b/docs/0001-digest-algorithms.md @@ -1,5 +1,6 @@ # OCFL Community Extension 0001: Digest Algorithms + * Extension Name: 0001-digest-algorithms * Authors: OCFL Editors * Minimum OCFL Version: 1.0 * Obsoletes: n/a