From 4234b3fa3ea3c225836b7e196cd007297699b45c Mon Sep 17 00:00:00 2001
From: Andrew Woods <awoods@lyrasis.org>
Date: Wed, 4 Mar 2020 09:40:49 -0500
Subject: [PATCH] Add text defining storage root and object root 'extensions'
 directories (#428)

* Initial pass at wording for extensions directory

* Add text defining storage root and object root 'extensions' directories

Resolves: https://github.com/OCFL/spec/issues/403

* code review

* code review 2

Co-authored-by: Andrew Hankinson <andrew.hankinson@bodleian.ox.ac.uk>
---
 draft/spec/index.html | 74 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 72 insertions(+), 2 deletions(-)

diff --git a/draft/spec/index.html b/draft/spec/index.html
index 57d79ac4..0961d0c3 100644
--- a/draft/spec/index.html
+++ b/draft/spec/index.html
@@ -880,7 +880,32 @@ <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="object-extensions">
+        <h2>Object Extensions</h2>
+        <p>
+            The base directory of an OCFL Object MAY contain a directory named <code>extensions</code> for the purposes
+            of extending the functionality of an OCFL Object. The <code>extensions</code> directory MUST NOT contain
+            any files, and no sub-directories other than extension sub-directories. Extension sub-directories SHOULD be
+            named according to a registered extension name. 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:
+        </p>
+        <ul>
+          <li>
+            The <a href="https://ocfl.github.io/extensions/">OCFL Extensions repository</a>
+          </li>
+          <li>
+            The Storage Root, as a plain text document directly in the Storage Root
+          </li>
+        </ul>
+        <blockquote class="informative">
+          <p>
+            Non-normative note: Extension sub-directories should use the same name as a registered extension
+            in order to both avoid the possiblity of an extension sub-directory colliding with the name of another
+            registered extension as well as to facilitate the recognition of extensions by OCFL clients.
+          </p>
+        </blockquote>
     </section>
 </section>
 
@@ -973,10 +998,18 @@ <h2>Storage Hierarchies</h2>
         </ol>
     </section>
 
-    <section id="root-extensions">
-        <h2>Extensions</h2>
+    <section id="storage-root-extensions">
+        <h2>Storage Root Extensions</h2>
         <p>
             The behavior of the storage root may be extended to support features from other specifications.
+        </p>
+        <p>
+            The base directory of an OCFL Storage Root MAY contain a directory named <code>extensions</code> for the
+            purposes of extending the functionality of an OCFL Storage Root. The storage root <code>extensions</code>
+            directory MUST conform to the same guidelines and limitations as those defined for
+            <a href="#object-extensions">object extensions</a>.
+        </p>
+        <p>
             An OCFL validator MUST ignore any files in the storage root it does not understand. Additional
             files MUST NOT appear in other directories under the storage root.
         </p>
@@ -1533,6 +1566,43 @@ <h2>Moab in an OCFL Object</h2>
 }
 </pre>
 </section>
+    <section id="example-extended-storage-root">
+        <h2>Example Extended OCFL Storage Root</h2>
+        <p>
+            The following example OCFL Storage Root has an extension containing custom content. The OCFL Storage Root
+            itself remains valid.
+        </p>
+<pre>
+[storage root]
+    ├── 0=ocfl_1.0
+    ├── extensions
+    │   └── 0000-example-extension
+    │       └── file-example.txt
+    ├── ocfl_1.0.txt
+    └── ocfl_layout.json
+</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
+    │   └── 0000-example-extension
+    │       └── file1-draft.txt
+    └── v1
+        ├── inventory.json
+        ├── inventory.json.sha512
+        └── content
+            └── file.txt
+</pre>
+    </section>
 </section>
 </body>
 </html>