Skip to content
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.

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

Registered extension name clarification #565

Closed
pwinckles opened this issue Oct 8, 2021 · 8 comments
Closed

Registered extension name clarification #565

pwinckles opened this issue Oct 8, 2021 · 8 comments
Assignees
Milestone

Comments

@pwinckles
Copy link

pwinckles commented Oct 8, 2021

The spec defines an registered extension name as follows:

The registered name of an extension is the name provided in the Extension Name property of the extension's definition.

It later says:

The specific structure and function of the extension, as well as a declaration of the registered extension name MUST be defined in one of the following locations:

  1. The OCFL Extensions repository
  2. The Storage Root, as a plain text document directly in the Storage Root

The later seems to indicate that all extension names, adopted or not, are "registered" so long as there is a plaintext document that describes them in the storage root.

If this is true, the following codes present an impossible problem to validators because there is no way to know what is or isn't an extension name:

  1. E071: ‘The value of the ocfl_layout.json extension key must be the registered extension name for the extension defining the arrangement under the storage root.’
  2. W013: ‘In an OCFL Object, extension sub-directories SHOULD be named according to a registered extension name.’

I had originally thought that "registered" extension names were only for extensions that were adopted into the extensions repository. In which case, validators would enforce those rules for the set of known extensions. And, I was going to file a ticket to say that I thought that E071 would be more congruous if it was a warning rather than an error.

So,

  1. Are all extension names "registered"? If so, what are validators supposed to do?
  2. If not, wouldn't it make more sense for E071 to be a warning?
@zimeon
Copy link
Contributor

zimeon commented Dec 9, 2021

I agree that "registered" should mean "in the OCFL Extensions repository". I thus think that we should refine the definition of registered extension name as follows (italic = added):

Registered Extension Name:
The registered name of an extension is the name provided in the Extension Name property of the extension's definition in the OCFL Extensions repository.

But, if we do that, how do we still leave space for unregistered extensions? At present there is an underspecified notion of putting "a plain text document directly in the Storage Root". To my mind two things are missing:

  • A rational way to link this local extension via its extension name (the current unclear definition of "registered extension name" suggests that one might have to read every plain text document in the storage root and attempt to extract the name from the markdown?!?). I think we should instead just rely on the file name (perhaps minus extension)
  • A naming convention for local extensions that avoids collision with registered extension names. That could be as simply as specifying that any local extension must have the prefix xxxx- or local- or something.

Another option would be to remove from the spec the notion of trying to tie local extensions names to files in the storage root. It could always be added later. The current "Extension sub-directories SHOULD be named according to a registered extension name" allows wiggle room for directories not associated with registered extensions, and then we simply remove the text around E068:

The specific structure and function of the extension, as well as a declaration of the registered extension name must be defined in one of the following locations:

  • The OCFL Extensions repository
    *The Storage Root, as a plain text document directly in the Storage Root

I didn't implement a test for E068, did you @pwinckles?

@pwinckles
Copy link
Author

pwinckles commented Dec 9, 2021

@zimeon I do not validate E068.

I agree with what you said, and would take it a step further. I think that validators should warn on any extension they do not recognize/support. Some examples:

  1. A new extension is added to the ocfl-extensions repo. Validators written before this extension was adopted, should warn if they encounter the extension.
  2. A local, unregistered extension is used. Validators that are not aware of this extension should warn.
  3. A local, unregistered extension is used. Validators that are aware of this extension should not warn.

I do not think the presence of an unrecognized extension should ever be an error.

[Edit] If extensions are validated as described here, then I do not think that it is necessary to formalize a naming convention for unregistered extensions.

@awoods
Copy link
Member

awoods commented Dec 9, 2021

@zimeon : I agree that your refined definition for "Registered Extension Name" is helpful:

Registered Extension Name:
The registered name of an extension is the name provided in the Extension Name property of the extension's definition in the OCFL Extensions repository.

@pwinckles : I am not sure how your response gets us around the issue raised by @zimeon ("one might have to read every plain text document in the storage root and attempt to extract the name from the markdown?!?") without a further-specified naming convention.

@pwinckles
Copy link
Author

@pwinckles : I am not sure how your response gets us around the issue raised by @zimeon ("one might have to read every plain text document in the storage root and attempt to extract the name from the markdown?!?") without a further-specified naming convention.

I was agreeing with this part:

Another option would be to remove from the spec the notion of trying to tie local extensions names to files in the storage root.

To me, it doesn't seem worthwhile for validators to enforce the documentation of local extensions. And, if this is desirable, then the spec should define a naming format.

@pwinckles
Copy link
Author

Maybe it would help to clarify the goal of validating the extensions.

My goal is simply to inform when the repository/object is using an extension that the client does not understand, which may be different from others' goals.

If the primary goal is to ensure documentation, then why not warn on missing copies of the the OCFL and registered extensions specs too?

@zimeon zimeon self-assigned this Dec 21, 2021
@zimeon
Copy link
Contributor

zimeon commented Dec 21, 2021

2021-12-21 Editors agree refining definition of registered extension name, need to refine language about local extensions without trying to tie the "local extension name" to anything. Will not try to distinguish between a local extension and a registered extension that a validator doesn't know about -- either would generate a warning

@zimeon
Copy link
Contributor

zimeon commented Apr 14, 2022

Will close this when corresponding Storage Root Extension clarification made in #583

@rosy1280
Copy link
Contributor

closed with #607

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants