Refine definition of registered extension name and describe local ext…

…ensions
OCFL · Apr 13, 2022 · 1831a55 · 1831a55
1 parent 77ab30d
commit 1831a55
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 17 deletions.
diff --git a/draft/spec/index.html b/draft/spec/index.html
@@ -293,7 +293,7 @@ <h2>Terminology</h2>
         <dd>
             Extensions are used to collaborate, review, and publish additional non-normative functions related to OCFL.
             Extensions are intended to be informational and cite-able, but outside the scope of the normal specification
-            process. Existing extensions may be found in the <a href="https://ocfl.github.io/extensions/">OCFL
+            process. Registered extensions may be found in the <a href="https://ocfl.github.io/extensions/">OCFL
             Extensions repository.</a>
         </dd>
         <dt>
@@ -362,7 +362,7 @@ <h2>Terminology</h2>
         </dt>
         <dd>
             The registered name of an extension is the name provided in the <i>Extension Name</i> property of the
-            extension's definition.
+            extension's definition in the <a href="https://ocfl.github.io/extensions/">OCFL Extensions repository</a>.
         </dd>
     </dl>
 </section>
@@ -975,23 +975,15 @@ <h2>Object Extensions</h2>
             of extending the functionality of an OCFL Object. The <code>extensions</code> directory
             <span id="E067">MUST NOT</span> contain any files, and no sub-directories other than extension
             sub-directories. Extension sub-directories <span id="W013">SHOULD</span> be named according to a
-            <a>registered extension name</a>. The specific structure and function of the extension, as well as a
-            declaration of the registered extension name <span id="E068">MUST</span> be defined in one of the following
-            locations:
+            <a>registered extension name</a> in the <a href="https://ocfl.github.io/extensions/">OCFL Extensions
+            repository</a>.
         </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.
+            registered extension as well as to facilitate the recognition of extensions by OCFL clients. See
+            also <a href="#documenting-local-extensions">Documenting Local Extensions</a>.
           </p>
         </blockquote>
     </section>
@@ -1011,8 +1003,8 @@ <h2>Root Structure</h2>
         </p>
         <p>
           An OCFL Storage Root MAY contain other files as direct children. These might include a human-readable
-          copy of the OCFL specification to make the storage root self-documenting, or files used by
-          <a href="#storage-root-extensions">storage root extensions</a>. An OCFL validator
+          copy of the OCFL specification to make the storage root self-documenting, or files used to
+          <a href="#documenting-local-extensions">document local extensions</a>. An OCFL validator
           <span id="E087">MUST</span> ignore any files in the storage root it does not understand.
         </p>
         <p>
@@ -1118,6 +1110,17 @@ <h2>Storage Root Extensions</h2>
         </blockquote>
     </section>
 
+    <section id="documenting-local-extensions">
+        <h2>Documenting Local Extensions</h2>
+        <p>
+            It is preferable that both <a href="#object-extensions">Object Extensions</a> and
+            <a href="#storage-root-extensions">Storage Root Extenstions</a> are documented and registered
+            in the <a href="https://ocfl.github.io/extensions/">OCFL Extensions repository</a>. However,
+            local extensions MAY be documented by including a plain text document directly in the storage root,
+            thus making the storage root self-documenting.
+        <p>
+    </section>
+
     <section id="filesystem-features">
         <h2>Filesystem features</h2>
         <p>

diff --git a/draft/spec/validation-codes.md b/draft/spec/validation-codes.md
@@ -77,7 +77,6 @@
 | E064 | 'Where an OCFL Object contains inventory.json in version directories, the inventory file in the OCFL Object Root must be the same as the file in the most recent version.' | https://ocfl.io/draft/spec/#E064
 | E066 | 'Each version block in each prior inventory file must represent the same object state as the corresponding version block in the current inventory file.' | https://ocfl.io/draft/spec/#E066
 | E067 | 'The extensions directory must not contain any files, and no sub-directories other than extension sub-directories.' | https://ocfl.io/draft/spec/#E067
-| 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 OR The Storage Root, as a plain text document directly in the Storage Root.' | https://ocfl.io/draft/spec/#E068
 | E069 | 'An OCFL Storage Root MUST contain a Root Conformance Declaration identifying it as such.' | https://ocfl.io/draft/spec/#E069
 | E070 | 'If present, [the ocfl_layout.json document] MUST include the following two keys in the root JSON object: [extension, description]' | https://ocfl.io/draft/spec/#E070
 | 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.' | https://ocfl.io/draft/spec/#E071