docs: add spec-style description of the consolidated metadata format

changes/4277.feature.md

@@ -0,0 +1,28 @@
+`zarr.registry.get_codec_class` now raises `zarr.errors.UnknownCodecError` instead of `KeyError`
+when no implementation is registered for a codec, and `zarr.core.config.BadConfigError` instead of
+`KeyError` when the implementation named in `config["codecs"][name]` is not registered.
+`zarr.registry.get_numcodec` raises `UnknownCodecError` instead of the `ValueError` numcodecs
+raises for an unregistered Zarr format 2 codec id (`numcodecs.errors.UnknownCodecError` on
+numcodecs 0.15.1 and later). All of these are subclasses of `ValueError`, so `except ValueError`
+is unaffected, but `except KeyError` and `except numcodecs.errors.UnknownCodecError` are.
+
+These errors now name Python packages known to provide the codec, so that a user who cannot read
+an array learns what to install:
+
+```
+An implementation for codec 'wavpack' is not available. Register one explicitly using the codec
+registry (see ...), or install a Python package that registers a codec implementation with
+numcodecs. Known packages supporting this codec: wavpack-numcodecs.
+```
+
+The tables covering this live in `src/zarr/registry.py`, one per Zarr format, and include the
+codecs `numcodecs` gates behind its own optional dependencies (`zfpy`, `pcodec`, `crc32c`,
+`msgpack2`). Codec authors can add their published package to them.
+
+A codec whose `from_dict` raises `KeyError` on a malformed configuration now surfaces as
+`zarr.errors.MetadataValidationError` naming the codec and the missing key. Previously it was
+reported as `UnknownCodecError: Unknown codec: '<configuration key>'`, presenting a configuration
+key as though it were a codec name, and on the `zarr.open` path a bare `KeyError` could be
+swallowed by the array-then-group fallback and reported as an unrelated group error.
+
+`zarr.errors.UnknownCodecError` is now exported from `zarr.errors`.

docs/user-guide/consolidated_metadata.md

@@ -11,6 +11,10 @@ entire hierarchy, especially when the metadata is being served over a network.
 Consolidated metadata essentially stores all the metadata for a hierarchy in the
 metadata of the root Group.
 
+This page describes how to use consolidated metadata from Python. For a precise
+description of what is written to the store, intended for other implementations,
+see [Consolidated metadata format](consolidated_metadata_format.md).
+
 ## Usage
 
 If consolidated metadata is present in a Zarr Group's metadata then it is used
@@ -84,9 +88,9 @@ print(output.getvalue())
 !!! info "Added in version 3.1.1"
     The keys in the consolidated metadata are sorted prior to writing. Keys are
     sorted in ascending order by path depth, where a path is defined as a sequence
-    of strings joined by `"/"`. For keys with the same path length, lexicographic
-    order is used to break the tie. This behavior ensures deterministic metadata
-    output for a given group.
+    of strings joined by `"/"`. For keys with the same depth, the tie is broken by
+    comparing the paths after Unicode NFKC normalization and case-folding. This
+    behavior ensures deterministic metadata output for a given group.
 
 ### Controlling the use of consolidated metadata