document changes

Author: brokkoli71

changes/2866.feature.rst

@@ -0,0 +1,2 @@
+If metadata JSON contains invalid keys, or if a value object contains invalid keys, the zarr array will be rejected unless it contains the key-value-pair ``"must_understand": false``.
+New codecs are required to validate their metadata and raise an error if it is invalid.

docs/user-guide/extending.rst

@@ -50,6 +50,9 @@ Custom codecs should also implement the following methods:
 - ``evolve_from_array_spec`` (optional), which can be useful for automatically filling in
   codec configuration metadata from the array metadata.
 
+On initialization, custom codecs should reject unexpected metadata keys except for objects
+marked with ``"must_understand": false``.
+
 To use custom codecs in Zarr, they need to be registered using the
 `entrypoint mechanism <https://packaging.python.org/en/latest/specifications/entry-points/>`_.
 Commonly, entrypoints are declared in the ``pyproject.toml`` of your package under the