Apply more ZEP 1 feedback

docs/core/v3.0.rst

@@ -147,7 +147,7 @@ Stability Policy
 ----------------
 
 This core specification adheres to a ``MAJOR.MINOR`` version
-number format. A zarr implementation provides the read and write API by
+number format. A zarr implementation that provides the read and write API by
 implementing this specification can be considered compatible with all
 datasets following the specification with the same major version number.
 
@@ -169,20 +169,15 @@ For details, please see the `zarr_format`_ metadata entry.
 Questions that still need to be resolved
 ----------------------------------------
 
-We solicit feedback on the following area during the RFC period of this first
-draft.
+We solicit feedback on the following area during the review period:
 
  - Should core metadata and user attributes be stored together or separate documents?
    (See https://github.com/zarr-developers/zarr-specs/issues/72)
- - extensions and ``must_understand = True`` might be too restrictive.
-   We propose to develop a draft implementation with extensions and
-   see how far we can go. A possible list of extensions to include:
 
-    - Datetime
-    - Named dimensions
-    - Awkward arrays
-
-   See https://github.com/zarr-developers/zarr-specs/issues/89 for discussion on
+ - We want to verify if the extension mechanisms fit different use cases or if
+   they are too restrictive. See
+   https://github.com/zarr-developers/zarr-specs/issues/89 and
+   https://github.com/zarr-developers/zarr-specs/issues/169 for discussion on
    the topic.
 
   - Node name case sensitivity: The node name is now case sensitive. This may
@@ -197,6 +192,7 @@ draft.
 
   - Should named dimensions be part of the core metadata spec?
     https://github.com/zarr-developers/zarr-specs/issues/73
+    https://github.com/zarr-developers/zarr-specs/pull/162
 
 
 Document conventions
@@ -263,7 +259,7 @@ The following figure illustrates the first part of the terminology:
     Each node in a hierarchy_ has a name, which is a string of
     characters with some additional constraints defined in the section
     on `node names`_ below. Two sibling nodes cannot have the same
-    name. The root node does not have a name.
+    name. The root node does not have a name and is the empty string ``""``.
 
 .. _path:
 .. _paths:
@@ -272,7 +268,7 @@ The following figure illustrates the first part of the terminology:
 
     Each node in a hierarchy_ has a path which uniquely identifies
     that node and defines its location within the hierarchy_. The path
-    is formed by joining together the "/" character, followed by the
+    is a string, formed by joining together the "/" character, followed by the
     name_ of each ancestor node separated by the "/" character,
     followed by the name_ of the node itself. For example, the path
     "/foo/bar" identifies a node named "bar", whose parent is named
@@ -314,8 +310,7 @@ The following figure illustrates the first part of the terminology:
     identified by a tuple of integer coordinates, one for each
     dimension_ of the array_. If all dimensions_ of an array_ have
     finite length, then the number of elements in the array_ is given
-    by the product of the dimension_ lengths. An array_ may not have
-    been fully initialized.
+    by the product of the dimension_ lengths.
 
 .. _data type:
 
@@ -589,6 +584,7 @@ other type sizes in later versions of this specification.
     arrays, one with the actual variable length data and one with fixed size
     (pointer + length) to the variable size data, we do not want to commit to such
     a structure.
+    See https://github.com/zarr-developers/zarr-specs/issues/62.
 
 
 Chunk grids
@@ -691,6 +687,12 @@ arbitrary length in a "negative" direction along any dimension.
    in which case the coordinate of a chunk is the empty tuple, and the chunk key
    will consist of the string ``c``.
 
+.. note:: Chunks at the border of an array always have the full chunk size, even when
+   the array only covers parts of it. For example, having and array with ``shape=(30, 30)``,
+   ``chunks=(16, 16)``, the chunk ``0,1`` would also contain unused values for the indices
+   ``(0-16, 30-31)``. Since reading anything beyond the array shape is undefined behavior,
+   those values may be passed on, be replaced with the fill values or other undefined behavior.
+
 Chunk memory layouts
 ====================
 
@@ -934,25 +936,21 @@ containing the following names:
     version number string to help with discovery of this
     specification.
 
-``metadata_encoding``
-^^^^^^^^^^^^^^^^^^^^^
-
-    A string containing the URI pointing to a document describing the method
-    used for encoding group and array metadata documents.
-
-    For document using the default JSON encoding and format describe in this document
-    then the value must be ``"https://purl.org/zarr/spec/core/3.0``.
-
 ``metadata_key_suffix``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-    A string containing a suffix to add to the metadata keys when saving into
-    the store. By default ``".json"``.
+    A string containing a suffix to add to the array and group metadata keys
+    when saving into the store, associated with a single encoding. By default
+    only ``".json"`` is allowed and used with JSON encoding.
 
     .. note::
+      This suffix is used to allow non hierarchy browsing and editing by
+      non-zarr-aware tools.
 
-      This suffix is used to allow non hierarchy
-      browsing and editing by non-zarr-aware tools.
+    .. note::
+      This is a possible extension point, where an extension which is
+      listed in ``extensions`` (see below) may add new valid suffixes with their
+      associated encodings.
 
 ``extensions``
 ^^^^^^^^^^^^^^
@@ -980,7 +978,6 @@ JSON is being used for encoding of group and array metadata::
 
     {
         "zarr_format": "https://purl.org/zarr/spec/core/3.0",
-        "metadata_encoding": "https://purl.org/zarr/spec/core/3.0",
         "metadata_key_suffix" : ".json",
         "extensions": []
     }
@@ -991,7 +988,6 @@ ignored if not understood::
 
     {
         "zarr_format": "https://purl.org/zarr/spec/core/3.0",
-        "metadata_encoding": "https://purl.org/zarr/spec/core/3.0",
         "metadata_key_suffix" : ".json",
         "extensions": [
             {
@@ -1162,8 +1158,8 @@ The following members are optional:
     transformer is used, same for an empty list.
 
 
-All other names within the array metadata object are reserved for
-future versions of this specification.
+The array metadata object must not contain any other names.
+Those are reserved for future versions of this specification.
 
 For example, the array metadata JSON document below defines a
 two-dimensional array of 64-bit little-endian floating point numbers,
@@ -1269,9 +1265,8 @@ Metadata encoding
 -----------------
 
 The entry point metadata document must be encoded as JSON. The array (``*.array`` s) and
-group metadata documents (``*.group`` s) must be encoded as per the type given in
-the ``metadata_encoding`` field in the entry point metadata document
-(described below).
+group metadata documents (``*.group`` s) must be encoded as per the type associated with
+the ``metadata_key_suffix`` field in the entry point metadata document (described below).
 
 Stores
 ======