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.

Sign up for GitHub

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

WIP: Extensions #404

Closed
wants to merge 2 commits into from
Closed

WIP: Extensions #404

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7bcc683
Initial pass at wording for extensions directory
ahankinson Oct 29, 2019
ec19a42
Merge branch 'master' into fixed-403-extensions
ahankinson Jan 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion draft/spec/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -860,7 +860,17 @@ <h2>Logs Directory</h2>
wrong, while others may wish to only store a log entry if an intervention was required.
</p>
</blockquote>
</section>

<section id="extensions">
<h2>Extensions directory</h2>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Capital D in directory to match section title style

<p>
The base directory of an OCFL Object MAY contain a directory named <code>extensions</code> for the purposes
zimeon marked this conversation as resolved.
Show resolved Hide resolved
of extending the functionality of an OCFL Object. Sub-directories of the extensions directory MUST be named
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Here we do not make it illegal to have files in the extension directory, I think that is the intention
  • I would also say the sub-directories SHOULD be named according to a registered name rather then MUST

Copy link
Contributor Author

@ahankinson ahankinson Nov 4, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Point 2: SHOULD would leave open the possibility of multiple things implementing the same extension but with different local names. This would make it difficult for clients to understand that it can operate on that content.

The alternative would be to use a NamAsTe file to declare an extension's identity in the root directory of that extension, e.g., extensions/versioning/0=mutable_head-1.0, which would allow us to name things differently. But this was an unpopular suggestion on the editorial call.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aren't the directories under extensions a namespace that references OCFL extentions - in that case, there should only be a single instance of any one type.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My concern is that by making it a SHOULD we leave open the possibility that people name their directories in extensions in a way that diverges from the name that is registered by the extension.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ahankinson I'm agreeing with you!

according to a registered extension name. OCFL Validators MUST ignore any content in extensions that are
not understood. The specific structure and function of the extension, as well as a declaration of the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not understood

that's a little unclear. we should be a bit more specific. i'm assuming you mean by a validator that understands the spec and/or that can validate whatever the extension asks it to validate.

Copy link
Contributor Author

@ahankinson ahankinson Nov 2, 2019 •
edited by rosy1280
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I took the language from the existing §4.4, "An OCFL validator must ignore any files in the storage root it does not understand."

We also have (in §3.4): "Optional fixity algorithms that are not supported by a client must be ignored by that client."

So would something like

Extension directories that are not supported by a client MUST be ignored by that client

make sense? Should we narrow it down specifically to validation, or just leave it open generally to "clients"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be "clients" and agree with last wording suggestion

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think stick with validators - this is the spec for objects at rest. We can discuss clients in the Implementation Notes (Client Behaviour's section) - ignoring extentions when writing is dangerous.

registered extension name MUST be defined in the OCFL Extensions Registry.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd go for SHOULD instead of MUST again, I'd also put any such language next to the sentence about the name

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SHOULD would leave open the possibility of registered and unregistered namespace collisions -- two extensions with the same name but different functions. By making it a MUST we reduce this possibility.

</p>
</section>
</section>

Expand Down Expand Up @@ -954,7 +964,7 @@ <h2>Storage Hierarchies</h2>
</section>

<section id="root-extensions">
<h2>Extensions</h2>
<h2>Root Extensions</h2>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This makes it sound like their is a difference between extensions that appear in the storage root and the object root. I thought we had agreed that Extensions would be stored at the root and then used in the objects -- but you might not use all extensions listed in the storage root.

Copy link
Contributor Author

@ahankinson ahankinson Nov 2, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are extensions, like the “layout” functionality, that will be root-only. (The demo from @birkland) In this case it does not affect the contents of objects, but only the paths to them.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change title to "Storage Root Extensions"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... which still leave the question of where descriptions of object extensions go

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Descriptions of object extensions also go in the storage root as a plain text file, on the theory that it is a single place that can describe the structure of some or all objects in that storage root.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with @ahankinson

<p>
The behavior of the storage root may be extended to support features from other specifications.
An OCFL validator MUST ignore any files in the storage root it does not understand. Additional
Expand Down Expand Up @@ -1513,6 +1523,27 @@ <h2>Moab in an OCFL Object</h2>
}
</pre>
</section>
<section id="example-extended-object">
<h2>Example Extended OCFL Object</h2>
<p>
The following example OCFL Object has an extension containing custom content. The OCFL Object itself
remains valid.
</p>
<pre>
[object root]
├── 0=ocfl_object_1.0
├── inventory.json
├── inventory.json.sha512
├── extensions
│   └── my-extension
│   └── file1-new.txt
└── v1
├── inventory.json
├── inventory.json.sha512
└── content
└── file.txt
</pre>
</section>
</section>
</body>
</html>