Slightly Amend Zarr Encoding Specification Doc #8749 (#11013)

Co-authored-by: Deepak Cherian <dcherian@users.noreply.github.com>

Author: eshort0401

doc/internals/zarr-encoding-spec.rst

@@ -43,9 +43,9 @@ When accessing arrays with zarr-python, this information is available in the arr
 metadata but not in the attributes dictionary.
 
 When reading a Zarr group, Xarray looks for dimension information in the appropriate
-location based on the format version, raising an error if it can't be found. The
+location based on the inferred format version, raising an error if it can't be found. The
 dimension information is used to define the variable dimension names and then
-(for Zarr V2) removed from the attributes dictionary returned to the user.
+(for Zarr V2) is removed from the attributes dictionary returned to the user.
 
 CF Conventions
 --------------
@@ -59,17 +59,14 @@ used to describe metadata in NetCDF and Zarr.
 Compatibility and Reading
 -------------------------
 
-Because of these encoding choices, Xarray cannot read arbitrary Zarr arrays, but only
-Zarr data with valid dimension metadata. Xarray supports:
+Because of these encoding choices, Xarray cannot read arbitrary Zarr groups, but only
+Zarr groups containing arrays with valid dimension metadata. Xarray supports:
 
-- Zarr V2 arrays with ``_ARRAY_DIMENSIONS`` attributes
-- Zarr V3 arrays with ``dimension_names`` metadata
-- `NCZarr <https://docs.unidata.ucar.edu/nug/current/nczarr_head.html>`_ format
-  (dimension names are defined in the ``.zarray`` file)
+1. Zarr V3 arrays with ``dimension_names`` metadata
+2. Zarr V2 arrays with ``_ARRAY_DIMENSIONS`` attributes
+3. `NCZarr <https://docs.unidata.ucar.edu/nug/current/nczarr_head.html>`_ format (dimension names are defined in the ``dimrefs`` field in the custom ``.zarray`` file)
 
-After decoding the dimension information and assigning the variable dimensions,
-Xarray proceeds to [optionally] decode each variable using its standard CF decoding
-machinery used for NetCDF data.
+Xarray checks each of these three conventions, in the order given above, when looking for dimension name metadata. Note that while Xarray can read NCZarr groups, it currently does not write NCZarr groups. After decoding the dimension information and assigning the variable dimensions, Xarray proceeds to [optionally] decode each variable using its standard CF decoding machinery used for NetCDF data.
 
 Finally, it's worth noting that Xarray writes (and attempts to read)
 "consolidated metadata" by default (the ``.zmetadata`` file), which is another

doc/whats-new.rst

@@ -26,6 +26,8 @@ Deprecations
 Bug Fixes
 ~~~~~~~~~
 
+- Slightly amend `Xarray's Zarr Encoding Specification doc <https://docs.xarray.dev/en/latest/internals/zarr-encoding-spec.html>`_ for clarity, and provide a code comment in ``xarray.backends.zarr._get_zarr_dims_and_attrs`` referencing the doc (:issue:`8749` :pull:`11013`).
+  By `Ewan Short <https://github.com/eshort0401>`_.
 - Fix silent data corruption when writing dask arrays to sharded Zarr stores.
   Dask chunk boundaries must now align with shard boundaries, not just internal
   Zarr chunk boundaries (:issue:`10831`).

xarray/backends/zarr.py

@@ -360,6 +360,9 @@ def _determine_zarr_chunks(enc_chunks, var_chunks, ndim, name):
 
 
 def _get_zarr_dims_and_attrs(zarr_obj, dimension_key, try_nczarr):
+    # Check for attributes and dimension name metadata as discussed in the Zarr encoding
+    # specification https://docs.xarray.dev/en/stable/internals/zarr-encoding-spec.html
+
     # Zarr V3 explicitly stores the dimension names in the metadata
     try:
         # if this exists, we are looking at a Zarr V3 array