chore: clarify extension fields and rename type

Author: d-v-b

packages/zarr-metadata/src/zarr_metadata/__init__.py

@@ -6,9 +6,11 @@
     DataTypeMetadataV2,
 )
 from zarr_metadata.v2.codec import CodecMetadataV2
+from zarr_metadata.v2.consolidated import ConsolidatedMetadataV2
 from zarr_metadata.v2.group import GroupMetadataV2
 from zarr_metadata.v3._common import MetadataFieldV3
-from zarr_metadata.v3.array import ArrayMetadataV3, ExtraFieldV3
+from zarr_metadata.v3.array import ArrayMetadataV3, ExtensionFieldV3
+from zarr_metadata.v3.consolidated import ConsolidatedMetadataV3
 from zarr_metadata.v3.group import GroupMetadataV3
 
 __version__ = "0.1.0"
@@ -22,8 +24,10 @@
     "ArrayMetadataV3",
     "ArrayOrderV2",
     "CodecMetadataV2",
+    "ConsolidatedMetadataV2",
+    "ConsolidatedMetadataV3",
     "DataTypeMetadataV2",
-    "ExtraFieldV3",
+    "ExtensionFieldV3",
     "GroupMetadataV2",
     "GroupMetadataV3",
     "MetadataFieldV3",

packages/zarr-metadata/src/zarr_metadata/v3/__init__.py

@@ -1,14 +1,14 @@
 """Zarr v3 metadata types."""
 
 from zarr_metadata.v3._common import MetadataFieldV3
-from zarr_metadata.v3.array import ArrayMetadataV3, ExtraFieldV3
+from zarr_metadata.v3.array import ArrayMetadataV3, ExtensionFieldV3
 from zarr_metadata.v3.consolidated import ConsolidatedMetadataV3
 from zarr_metadata.v3.group import GroupMetadataV3
 
 __all__ = [
     "ArrayMetadataV3",
     "ConsolidatedMetadataV3",
-    "ExtraFieldV3",
+    "ExtensionFieldV3",
     "GroupMetadataV3",
     "MetadataFieldV3",
 ]

packages/zarr-metadata/src/zarr_metadata/v3/array.py

@@ -8,22 +8,36 @@
 from zarr_metadata.v3._common import MetadataFieldV3
 
 
-class ExtraFieldV3(TypedDict, extra_items=object):  # type: ignore[call-arg]
+class ExtensionFieldV3(TypedDict, extra_items=object):  # type: ignore[call-arg]
     """
-    Extra field on a v3 array metadata document.
-
-    Extras must include `must_understand: false` and may carry arbitrary
-    additional JSON data.
+    Required shape of any extension field on a v3 metadata document.
+
+    The Zarr v3 spec permits extra keys on array and group metadata
+    documents, provided each value is an object with `must_understand`
+    set to `False`. This TypedDict captures that constraint and is used
+    as the `extra_items=` parameter on `ArrayMetadataV3` and `GroupMetadataV3`.
+
+    Spec interpretation: this type follows the original Zarr v3.0 reading
+    of the spec, under which any object with `must_understand: false` is a
+    valid extension field. The v3.1 spec rewrite added language requiring
+    extension fields to also include a `name: str` key (the "Extension
+    definition" form). Under the strict v3.1 reading, real-world extension
+    fields written by zarr-python and zarrs (notably `consolidated_metadata`,
+    which has no `name` field) are out of spec. The community consensus at
+    the time of writing is that this is a regression to be reverted; this
+    package models the v3.0 / pre-revert interpretation. See
+    https://github.com/zarr-developers/zarr-specs/issues/371 for the
+    ongoing discussion.
     """
 
     must_understand: Literal[False]
 
 
-class ArrayMetadataV3(TypedDict, extra_items=ExtraFieldV3):  # type: ignore[call-arg]
+class ArrayMetadataV3(TypedDict, extra_items=ExtensionFieldV3):  # type: ignore[call-arg]
     """
     Zarr v3 array metadata document (the `zarr.json` content for an array).
 
-    Extra keys are permitted if they conform to `ExtraFieldV3`.
+    Extra keys are permitted if they conform to `ExtensionFieldV3`.
 
     See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#array-metadata
     """
@@ -43,5 +57,5 @@ class ArrayMetadataV3(TypedDict, extra_items=ExtraFieldV3):  # type: ignore[call
 
 __all__ = [
     "ArrayMetadataV3",
-    "ExtraFieldV3",
+    "ExtensionFieldV3",
 ]

packages/zarr-metadata/src/zarr_metadata/v3/consolidated.py

@@ -2,8 +2,17 @@
 
 There is no Zarr v3 specification for consolidated metadata. This module
 models the inline-on-group convention used by the reference Python
-implementation, where consolidated metadata is embedded as an extra field
-on a group's `zarr.json`.
+implementation (and zarrs), where consolidated metadata is embedded as
+an extension field on a group's `zarr.json`.
+
+The shape modeled here (`{kind, must_understand, metadata}` with no `name`
+field) reflects the original Zarr v3.0 reading of the extension-field
+rules. Under the strict Zarr v3.1 reading, every extension field must
+also include a `name: str` key, which would make this shape — and every
+real-world consolidated metadata document in the wild — out of spec.
+See `ExtensionFieldV3` and
+https://github.com/zarr-developers/zarr-specs/issues/371 for the
+ongoing discussion.
 """
 
 from collections.abc import Mapping

packages/zarr-metadata/src/zarr_metadata/v3/group.py

@@ -8,14 +8,14 @@
 
 from typing_extensions import TypedDict
 
-from zarr_metadata.v3.array import ExtraFieldV3
+from zarr_metadata.v3.array import ExtensionFieldV3
 
 
-class GroupMetadataV3(TypedDict, extra_items=ExtraFieldV3):  # type: ignore[call-arg]
+class GroupMetadataV3(TypedDict, extra_items=ExtensionFieldV3):  # type: ignore[call-arg]
     """
     Zarr v3 group metadata document (the `zarr.json` content for a group).
 
-    Extra keys are permitted if they conform to `ExtraFieldV3`.
+    Extra keys are permitted if they conform to `ExtensionFieldV3`.
 
     See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#group-metadata
     """

packages/zarr-metadata/tests/v3/array/with_extra_field.json

@@ -16,6 +16,6 @@
   ],
   "my_custom_extension": {
     "must_understand": false,
-    "purpose": "exercise the extra_items=ExtraFieldV3 path"
+    "purpose": "exercise the extra_items=ExtensionFieldV3 path"
   }
 }