Review of primary phase 1 text

Author: joshmoore

draft/ZEP0009.md

@@ -62,12 +62,13 @@ This proposal has three phases.
 The [first phase](#Phase-1-Immediate-clarifications) clarifies that extensions
 can be created by the community without the ZEP process. Extensions with
 URI-based names can be created without any further coordination and extensions
-with raw names only need to get the name registered in the `zarr-developers`
-Github organization. The process for registering will be a lightweight PR-based
-process.
+with raw names only need to get the name registered in the
+[`zarr-extensions` Github repository](https://github.com/zarr-developers/zarr-extensions).
+The process for registering will be a lightweight PR-based process.
 
 The naming mechanism as well as clarifications in the core spec documented will
-be implemented by the ZSC through a PR against the zarr-specs repository for
+be implemented by the ZSC through
+[PR330](https://github.com/zarr-developers/zarr-specs/pull/330) in the zarr-specs repository for
 discussion concurrently with this ZEP. The changes we are proposing, marked
 with a "🛠️" below, are interpretations of the current Zarr v3 core spec as well
 as additions that are in-line with the spec evolution policy of the Zarr core
@@ -92,7 +93,7 @@ the adoption of extensions into the core spec.
 ## Definitions
 
 - "Core" refers to the Zarr v3 core specification as defined in the document
-  https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html and not
+  <https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html> and not
   necessarily if something is a MUST for implementations.
 - "Metadata" is the Zarr metadata as stored in `zarr.json` files for arrays and
   groups.
@@ -102,10 +103,10 @@ the adoption of extensions into the core spec.
   storage transformers.
 - "Extension points" are locations within metadata where extension-related
   metadata can be found. Current extension points are listed in the core spec,
-  e.g. `codecs`, `data_type`. As part of this proposal, we intend to add another
-  general-purpose extension point called [`extensions`](#Extension-points).
+  e.g. `codecs`, `data_type`. As part of the [second phase](#Phase-2-New-extension-points),
+  we intend to add another general-purpose extension point called [`extensions`](#Extension-points).
 - "Extension maintainers" are a person or a team that is responsible for
-  creating and maintaining an extension.## Rollout and next steps
+  creating and maintaining an extension.
 
 ## Phase 1: Immediate clarifications
 
@@ -128,9 +129,10 @@ raw names and URI-based.
    - **Acceptd regex:** `^[a-z0-9-_.]+$`
 
 2. **URI-based names** can be used by anyone without further coordination
-   though the assumption is that users reasonably "own" the URI.
+   though the assumption is that users reasonably "own" the URI. Users MAY
+   make use of a persistent redirecting URL like [PURL](https://purl.archive.org/).
    URIs have been chosen due to their potential for being self-documenting and
-   *strong recommend* that the URL SHOULD resolve to a human-readable explanation of the extension, but
+   *strongly recommend* that the URL SHOULD resolve to a human-readable explanation of the extension, but
    implementations SHOULD NOT attempt to resolve the URL during processing.
    There are no guarantees in terms of versioning or compatibility. However,
    preserving backwards-compatibility is strongly encouraged. See the
@@ -148,7 +150,7 @@ under the codecs section:
 > to codecs in array metadata documents, each codec must have a unique
 > identifier, which is a URI that dereferences to a human-readable
 > specification of the codec."
-> (https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html#specifying-codecs).
+> (<https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html#specifying-codecs>).
 
 🛠️ This proposal would drop the MUST requirement on the dereferencing of the
 URI to a SHOULD and more widely specify that implemenations MAY use URI-based
@@ -174,11 +176,13 @@ Objects have the following keys:
 ```
 
 If such an object is present, the field `must_understand` is implicitly set to
-`True` and an object can explicitly set `must_understand=False` if
+`True`. Implementations which encounter a `must_understand` extension that they
+have not implemented MUST raise an exception.
+An extension object can explicitly set `must_understand=False` if
 implementations can ignore its presence, following the current guidelines in
 the v3 specification.
 
-Instead of extension objects, short-hand names may continue to be used if no
+Instead of extension objects, short-hand names MAY continue to be used if no
 configuration metadata is required. They would be equivalent to extension
 objects with just a `name` key. This is in-line with
 [the current wording of the spec](https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html#id11).
@@ -189,8 +193,10 @@ There is no strict requirement for extensions to have a formal specification.
 However, for adoption in the community it is STRONGLY RECOMMENDED to write a
 specification.
 
-For extensions with raw names, there will be the [zarr-extensions](https://github.com/zarr-developers/zarr-extensions) repository to either publish the specifications
-directly or link to another location. For extensions with URI-based names, it
+For an extension with a raw name, the
+[zarr-extensions](https://github.com/zarr-developers/zarr-extensions)
+repository SHOULD be used to either publish the specification
+directly or link to another location which does so. For extensions with URI-based names, it
 is RECOMMENDED to publish the specification under the URI of the extension.
 
 ### Extension points
@@ -226,8 +232,7 @@ and would be declared as "core" extensions under this proposal.
  * Chunk key encoding: `default`, `v2`
  * Storage transformers: (none)
 
-
- ### Example
+### Example
 
 The following example represents an Array showing many of the proposed changes
 described above: