Merge pull request #13 from OCFL/Versioning

Extension Naming and Versioning

README.md

@@ -1,14 +1,20 @@
 # 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 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/).
 
 See also [pending pull requests](https://github.com/OCFL/extensions/pulls) for extensions under discussion.
 
 ## 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 files in the `docs` directory of this repository. The
+filename of an extension is based on its *Registered Name* with a `.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
@@ -29,22 +35,29 @@ 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 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. 
-* 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 sidecar JSON file that
+uses the registered name with the filename extension `.json`. If using an 'extensions' directory, the JSON file MUST be 
+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:
 
     "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 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.    

docs/0000-example-extension.md

@@ -1,5 +1,6 @@
 # OCFL Community Extension 0000: Example Extension
 
+  * Extension Name: 0000-example-extension
   * Authors: A Person, Other Person
   * Minimum OCFL Version: 1.0
   * Obsoletes: n/a

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
@@ -20,4 +21,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.