Extension Naming and Versioning #13

neilsjefferies · 2020-06-03T08:38:12Z

Clarified versioning/maintenance text in response to issue #4 (plus a couple of formatting/language fixes)

Clarify versioning and some tidying up

Clarified wording around maintenance

pwinckles · 2020-06-03T13:04:29Z

README.md


 ## 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:


I'm a little confused by this wording:

If using an extensions directory, the JSON file MUST be named for the extension and included in the directory.

Is it acceptable to put these JSON files anywhere other than in the extensions directory?

If it is put inside the extensions directory, does it matter where? For example, extensions/0000-example-extension.json or extensions/0000-example-extension/0000-example-extension.json.

At the moment, there isn't another way of referencing extensions other than the extension directory so no.

Interesting point, the intent was the extension directory and not a subdirectory.

Clarified that it needs to be in the extension directory and not a subdirectory. Also, ocfl_layout.json is another place where a parameter sidecar file can occur.

@neilsjefferies Thanks for the updates!

The spec currently states that extensions should use a subdirectory of extensions "named according to a registered extension name". I don't necessary have a problem with the json files being directly under extensions. In fact, for extensions that do not have additional files, this makes a lot of sense. But, it is a little more awkward for extensions that have both configuration and a sub directory. For example:

extensions/ - 0000-example-extension.json - 0000-example-extension/ - ... some files ...

In those cases, it would be neater if the json file was under the extension directory. Perhaps, the json file should be at the root of extensions when the extension has no other files and under a subdirectory if it does? Not a huge deal either way.

Actually, I agree! I intended that the extension parameters should be in the "root directory of the extension" not extensions since it shouldn't contain files as per the spec. Let me reword that...

Sounds good to me too

pwinckles · 2020-06-03T13:26:52Z

docs/0001-digest-algorithms.md

-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 


I assume that this extension is no longer going to be parameterized, correct? So, there's effectively no way to reference it. Does it matter if a new version of this extension was created opposed to just updating it? If a new version was created, how would anyone know which version an object was using?

I believe it will be parameterized but the PR hasn't been merged yet. Editors discussed versioning and decided to hold with RFC behaviour and create new extension numbers for additions. A new version doesn't cause the old one to vanish. Whatever version an object references will continue to be valid.

Update post 20200602 Editorial discussion. We're not parameterizing but the versioning description remains to be consistent with how extensions are handled in in general.

neilsjefferies · 2020-06-16T14:36:49Z

Updated to define registered name.

pwinckles · 2020-06-16T14:50:47Z

README.md

-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 at the top level of the directory and not a subdirectory. Another place that an extension may be referenced is


Another place that an extension may be referenced is ocfl_layout.json where the sidecar file should be alongside it in the Storage Root.

Is this the equivalent of saying?

If ocfl_layout.json references an extension, then the extension's sidecar file must be in the Storage Root instead of the extensions directory.

Or should both locations be checked?

Yes (to your first question).

pwinckles · 2020-06-16T14:55:34Z

README.md

+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": {  


Perhaps not appropriate for this PR, but I'm not sure the parameters json file should have this key "0000-example-extension.md". Wouldn't the contents of 0000-example-extension.md (in this example) be:

{ "firstExampleParameter": 12, "secondExampleParameter": "Hello", "thirdExampleParameter": "Green" }

I can see potential value in keeping the extension name as the key in this JSON document... particularly in the case where an extension is chaining multiple other extensions together.
..or, for the chaining use case, the chained extensions may also be found in the parameter listing.

Unless there's an intention to suggest that you could define multiple extensions in the same file, I don't think there's much value in keeping the key, which makes parsing a little kludgy. I'm not sure it would even work for chaining because you can't infer an ordinal relationship.

If the reasons for keeping the key are hypothetical, at best... maybe it should be removed.

If this is the only change that is being requested in this PR, perhaps we could allow this PR to move forward and make the change in a separate PR.

@rosy1280, @neilsjefferies had expressed the intent to clarify the language around where the json file is supposed to be written: #13 (comment)

But, yes, the key doesn't necessarily need to be addressed here.

Parking this for a later pull request.

@pwinckles can you create a ticket for this issue? (or did you already?)

awoods · 2020-07-21T20:47:01Z

README.md

+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.


I would suggest the "Registered Name" to be the name provided in the header (https://github.com/OCFL/extensions/pull/16/files#diff-77315547024f9923f13fb0a37b4ecf3aR3), as opposed to the filename in the docs directory.

Agreed, but do we then need some language saying that the extension file is also named according to the registered extension name?

@zimeon : Are you suggesting wording that aligns the filename with the registered extension name? If so, that sounds reasonable.

awoods · 2020-07-21T21:12:44Z

README.md

+  * 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.


I would expect the range for string parameters to somehow define the allowable values. Would a regex or enumerated list make sense? I am not sure I see the benefit of using the range property to define string lengths.

Parking this for a later pull request.

@awoods to create an issue for discussion

awoods · 2020-07-21T21:16:59Z

README.md

+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": {  


I can see potential value in keeping the extension name as the key in this JSON document... particularly in the case where an extension is chaining multiple other extensions together.
..or, for the chaining use case, the chained extensions may also be found in the parameter listing.

Updated Registered name definition and specified parameter location more clearly.

Added name

updates made

neilsjefferies added 3 commits June 3, 2020 09:28

Update README.md

aa9c4c2

Clarify versioning and some tidying up

Update 0001-digest-algorithms.md

2a865f8

Clarified wording around maintenance

Update README.md

828c987

pwinckles reviewed Jun 3, 2020

View reviewed changes

rosy1280 requested review from awoods, zimeon, rosy1280, ahankinson and julianmorley June 9, 2020 20:44

Update README.md

2a203c5

neilsjefferies changed the title ~~Versioning~~ Extension Naming and Versioning Jun 16, 2020

Update README.md

2f147d8

Update README.md

ca52ea5

zimeon mentioned this pull request Jun 16, 2020

Referencing extensions in ocfl_layout.json OCFL/spec#477

Closed

pwinckles reviewed Jun 16, 2020

View reviewed changes

neilsjefferies mentioned this pull request Jun 17, 2020

Define extension value as registered extension name OCFL/spec#483

Merged

pwinckles mentioned this pull request Jun 17, 2020

hashed truncated n-tuple with object identifier encapsulation directory storage hierarchy spec #19

Merged

pwinckles mentioned this pull request Jul 6, 2020

hashed truncated n-tuple tree storage hierarchy spec #16

Merged

rosy1280 approved these changes Jul 21, 2020

View reviewed changes

awoods previously requested changes Jul 21, 2020

View reviewed changes

awoods mentioned this pull request Jul 22, 2020

Establish review and merge policy #21

Closed

neilsjefferies added 4 commits August 18, 2020 12:09

Update README.md

266f97a

Updated Registered name definition and specified parameter location more clearly.

Update 0000-example-extension.md

710c665

Update 0000-example-extension.md

421fdd1

Added name

Update 0001-digest-algorithms.md

c118c23

Added name

neilsjefferies requested a review from rosy1280 August 18, 2020 11:13

rosy1280 requested a review from awoods August 18, 2020 13:08

zimeon approved these changes Aug 18, 2020

View reviewed changes

rosy1280 approved these changes Aug 18, 2020

View reviewed changes

rosy1280 removed the request for review from ahankinson August 18, 2020 13:18

awoods approved these changes Aug 18, 2020

View reviewed changes

rosy1280 merged commit 25f8921 into master Aug 18, 2020

rosy1280 deleted the Versioning branch August 18, 2020 13:20

rosy1280 restored the Versioning branch August 18, 2020 13:25

rosy1280 deleted the Versioning branch August 18, 2020 13:25

neilsjefferies mentioned this pull request Aug 18, 2020

Registered extension name #14

Closed

awoods mentioned this pull request Aug 18, 2020

Reconsider 'range' for string parameters #23

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Extension Naming and Versioning #13

Extension Naming and Versioning #13

neilsjefferies commented Jun 3, 2020

pwinckles Jun 3, 2020

neilsjefferies Jun 3, 2020

neilsjefferies Jun 16, 2020

pwinckles Jun 16, 2020

neilsjefferies Jun 17, 2020

zimeon Jul 21, 2020

pwinckles Jun 3, 2020

neilsjefferies Jun 3, 2020

neilsjefferies Jun 10, 2020

neilsjefferies commented Jun 16, 2020

pwinckles Jun 16, 2020

neilsjefferies Jun 17, 2020

pwinckles Jun 16, 2020

awoods Jul 21, 2020

pwinckles Jul 21, 2020

awoods Jul 24, 2020

rosy1280 Jul 24, 2020

pwinckles Jul 24, 2020

pwinckles Jul 24, 2020

rosy1280 Aug 18, 2020

rosy1280 Aug 18, 2020

pwinckles Aug 18, 2020

awoods Jul 21, 2020

zimeon Jul 22, 2020

awoods Jul 22, 2020

awoods Jul 21, 2020

rosy1280 Aug 18, 2020 •

edited

rosy1280 Aug 18, 2020

awoods Jul 21, 2020

Extension Naming and Versioning #13

Extension Naming and Versioning #13

Conversation

neilsjefferies commented Jun 3, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neilsjefferies commented Jun 16, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rosy1280 Aug 18, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rosy1280 Aug 18, 2020 •

edited