fix(zarr-metadata): a v2 array's other members are JSON with string keys

The v2 array validator tolerates members outside the `.zarray`
definition, as the spec asks readers to ignore them, but never looked at
them: `parse_array_metadata_v2` returned a document with an integer key,
or with a set or NaN as a member, typed as `ZarrV2ArrayMetadataJSON`,
where `is_array_metadata_v2` said no. The members are now checked as v3
checks its extension fields, by the same helper, renamed for both.

Assisted-by: ClaudeCode:claude-opus-5-5

Author: d-v-b

packages/zarr-metadata/changes/365.bugfix.1.md

@@ -0,0 +1,7 @@
+A v2 array document's members outside the `.zarray` definition are still
+tolerated, and dropped on read, but one that is not a JSON value, or whose
+key is not a string, is now a problem, as it is in a v3 document.
+`parse_array_metadata_v2` returned such members in a document its type
+says holds string keys, which `is_array_metadata_v2` refused.
+`ZarrV2ArrayMetadataJSON` declares its other members as JSON values
+(`extra_items`), as its pydantic schema already did.

packages/zarr-metadata/src/zarr_metadata/model/_validation.py

@@ -221,13 +221,17 @@ def _check_literal(
     return ()
 
 
-def _validate_extension_fields_v3(
+def _validate_other_members(
     doc: Mapping[object, object],
     standard_keys: frozenset[str],
     *,
     additional_reserved_keys: frozenset[str] = frozenset(),
 ) -> tuple[ValidationProblem, ...]:
-    """Validate v3 top-level key types and unknown-field JSON payloads."""
+    """Every key a string, and every member outside `standard_keys` a JSON value.
+
+    For a document open to other members: v3 extension fields, and the
+    members a v2 array's readers ignore.
+    """
     problems: list[ValidationProblem] = []
     reserved_keys = standard_keys | additional_reserved_keys
     for key, value in doc.items():
@@ -500,7 +504,7 @@ def validate_array_metadata_v3(value: object) -> tuple[ValidationProblem, ...]:
     doc = cast("Mapping[str, object]", value)
     problems: list[ValidationProblem] = list(_missing_keys(ARRAY_METADATA_REQUIRED_KEYS_V3, doc))
     problems.extend(
-        _validate_extension_fields_v3(
+        _validate_other_members(
             cast("Mapping[object, object]", value), ARRAY_METADATA_STANDARD_KEYS_V3
         )
     )
@@ -595,9 +599,15 @@ def validate_array_metadata_v2(value: object) -> tuple[ValidationProblem, ...]:
     # Unlike the group document ("Other keys MUST NOT be present",
     # https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L313), the v2 array document is open: other keys "SHOULD NOT be
     # present within the metadata object and SHOULD be ignored by
-    # implementations" (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L91-L92), so members outside
-    # ARRAY_METADATA_STANDARD_KEYS_V2 are not problems.
+    # implementations" (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L91-L92), so a member outside
+    # ARRAY_METADATA_STANDARD_KEYS_V2 is not a problem for being there. Ignored
+    # is not unchecked: it is JSON, and its key a string, as in v3.
     problems: list[ValidationProblem] = list(_missing_keys(ARRAY_METADATA_REQUIRED_KEYS_V2, doc))
+    problems.extend(
+        _validate_other_members(
+            cast("Mapping[object, object]", value), ARRAY_METADATA_STANDARD_KEYS_V2
+        )
+    )
     problems.extend(_check_literal(doc, "zarr_format", 2))
     shape_problems = _validate_dim_sequence(doc, "shape")
     chunks_problems = _validate_dim_sequence(doc, "chunks")
@@ -761,7 +771,7 @@ def validate_group_metadata_v3(value: object) -> tuple[ValidationProblem, ...]:
     doc = cast("Mapping[str, object]", value)
     problems: list[ValidationProblem] = list(_missing_keys(GROUP_METADATA_REQUIRED_KEYS_V3, doc))
     problems.extend(
-        _validate_extension_fields_v3(
+        _validate_other_members(
             cast("Mapping[object, object]", value),
             GROUP_METADATA_STANDARD_KEYS_V3,
             additional_reserved_keys=frozenset({"consolidated_metadata"}),

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

@@ -77,7 +77,7 @@ class ZarrV2ZArrayJSON(TypedDict):
     dimension_separator: NotRequired[ZarrV2ArrayDimensionSeparator]
 
 
-class ZarrV2ArrayMetadataJSON(TypedDict):
+class ZarrV2ArrayMetadataJSON(TypedDict, extra_items=JSONValue):
     """
     Zarr v2 array metadata document, in-memory merged form.
 
@@ -89,6 +89,10 @@ class ZarrV2ArrayMetadataJSON(TypedDict):
     real `.zarray` file should split / merge `attributes` accordingly,
     or use `ZarrV2ZArrayJSON` (strict on-disk) plus `ZarrV2ZAttrsJSON` directly.
 
+    Open: other keys "SHOULD NOT be present ... and SHOULD be ignored by
+    implementations" (https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v2/v2.0.rst#L91-L92), and each
+    other member is a JSON value.
+
     See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
     """
 
@@ -108,7 +112,7 @@ class ZarrV2ArrayMetadataJSON(TypedDict):
     """
 
 
-class ZarrV2ArrayMetadataJSONPartial(TypedDict, total=False):
+class ZarrV2ArrayMetadataJSONPartial(TypedDict, total=False, extra_items=JSONValue):
     """
     Partial form of `ZarrV2ArrayMetadataJSON`: every field is `NotRequired`.
 

packages/zarr-metadata/tests/model/test_array.py

@@ -3,6 +3,7 @@
 import copy
 import dataclasses
 import json
+import math
 from collections import UserDict
 from collections.abc import Callable
 from typing import TYPE_CHECKING, get_args
@@ -1403,6 +1404,31 @@ def test_array_v2_ignores_unknown_document_member() -> None:
     assert "unexpected" not in ZarrV2ArrayMetadata.from_json(doc).to_json()
 
 
+@pytest.mark.parametrize(
+    ("member", "kind"),
+    [
+        (object(), "invalid_type"),
+        ({1, 2}, "invalid_type"),
+        (b"\x00", "invalid_type"),
+        (math.nan, "invalid_value"),
+    ],
+    ids=["object", "set", "bytes", "nan"],
+)
+def test_error_array_v2_unknown_member_that_is_not_json(member: object, kind: str) -> None:
+    """Ignored is not unchecked: an unknown member is a JSON value, as in v3."""
+    doc = dict(ZarrV2ArrayMetadata.create_default().to_json()) | {"unexpected": member}
+
+    assert [(p.loc, p.kind) for p in validate_array_metadata_v2(doc)] == [(("unexpected",), kind)]
+
+
+@pytest.mark.parametrize("key", [7, None, True, (1, 2)], ids=["int", "none", "bool", "tuple"])
+def test_error_array_v2_key_that_is_not_a_string(key: object) -> None:
+    """A document's keys are strings: `parse_array_metadata_v2` returned this one."""
+    doc: dict[object, object] = {**ZarrV2ArrayMetadata.create_default().to_json(), key: "x"}
+
+    assert [(p.loc, p.kind) for p in validate_array_metadata_v2(doc)] == [((), "invalid_type")]
+
+
 def test_array_v3_from_json_materializes_abstract_containers() -> None:
     """A flexible input mapping becomes the canonical dict/tuple model shape."""
     doc = UserDict(dict(ZarrV3ArrayMetadata.create_default(shape=(2,)).to_json()))