Skip to content

fix![zarr-metadata]: define JSONValue type, and narrow object annotations to use JSONValue #4037

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
d-v-b wants to merge 6 commits into
base: main
Choose a base branch
from
+53 −26
Open

fix![zarr-metadata]: define JSONValue type, and narrow object annotations to use JSONValue #4037

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8570ed1
chore: define JSONValue type, and narrow object annotations to use JS…
d-v-b Jun 4, 2026
693571d
fix: apply JSONValue more extensively, and correct dtype data types
d-v-b Jun 4, 2026
ab2b16a
Merge branch 'main' into json-in-zarr-metadata
d-v-b Jun 5, 2026
344e4e7
Delete packages/zarr-metadata/.claude/hooks/.logs/hook-log.jsonl
d-v-b Jun 5, 2026
0beb6de
Potential fix for pull request finding
d-v-b Jun 5, 2026
8f3cb33
fix: export JSONValue
d-v-b Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/zarr-metadata/src/zarr_metadata/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
from importlib.metadata import version

from zarr_metadata._common import NamedConfig
from zarr_metadata._common import JSONValue, NamedConfig
from zarr_metadata.v2.array import (
ArrayDimensionSeparatorV2,
ArrayMetadataV2,
Expand Down Expand Up @@ -37,6 +37,7 @@
"GroupMetadataV2Partial",
"GroupMetadataV3",
"GroupMetadataV3Partial",
"JSONValue",
"MetadataFieldV3",
"NamedConfig",
"ZArrayMetadata",
Expand Down
19 changes: 15 additions & 4 deletions packages/zarr-metadata/src/zarr_metadata/_common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,28 @@
from collections.abc import Mapping
from typing import NotRequired

from typing_extensions import TypedDict
from typing_extensions import TypeAliasType, TypedDict

JSONValue = TypeAliasType(
"JSONValue",
"int | float | bool | None | str | list[JSONValue] | tuple[JSONValue, ...] | Mapping[str, JSONValue]", # type: ignore[reportInvalidTypeForm]
)
Comment thread
d-v-b marked this conversation as resolved.
"""A recursive type alias for JSON-encodable values.

Defined via `TypeAliasType` (rather than a plain `TypeAlias`) so the
self-reference is a named recursion point that pydantic can resolve when
building a `TypeAdapter`; a bare recursive `TypeAlias` raises
`PydanticUserError`/`RecursionError` at validation time.
"""
Comment thread
d-v-b marked this conversation as resolved.


class NamedConfig(TypedDict):
"""
Externally-tagged union member for a metadata field.

The `configuration` mapping holds arbitrary JSON-encodable values;
it is typed as `Mapping[str, object]` because the type system cannot
express or verify JSON-encodability.
it is typed as `Mapping[str, JSONValue]`.
"""

name: str
configuration: NotRequired[Mapping[str, object]]
configuration: NotRequired[Mapping[str, JSONValue]]
11 changes: 6 additions & 5 deletions packages/zarr-metadata/src/zarr_metadata/v2/array.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@

from typing_extensions import TypedDict

from zarr_metadata._common import JSONValue
from zarr_metadata.v2.codec import CodecMetadataV2

DataTypeMetadataV2 = str | tuple[tuple[str, str] | tuple[str, str, tuple[int, ...]], ...]
Expand Down Expand Up @@ -61,7 +62,7 @@ class ZArrayMetadata(TypedDict):
chunks: tuple[int, ...]
dtype: DataTypeMetadataV2
compressor: CodecMetadataV2 | None
fill_value: object
fill_value: JSONValue
order: ArrayOrderV2
filters: tuple[CodecMetadataV2, ...] | None
dimension_separator: NotRequired[ArrayDimensionSeparatorV2]
Expand All @@ -87,11 +88,11 @@ class ArrayMetadataV2(TypedDict):
chunks: tuple[int, ...]
dtype: DataTypeMetadataV2
compressor: CodecMetadataV2 | None
fill_value: object
fill_value: JSONValue
order: ArrayOrderV2
filters: tuple[CodecMetadataV2, ...] | None
dimension_separator: NotRequired[ArrayDimensionSeparatorV2]
attributes: NotRequired[Mapping[str, object]]
attributes: NotRequired[Mapping[str, JSONValue]]
"""User attributes from the sibling `.zattrs` file (not part of `.zarray`).

See the class docstring for the rationale behind the merged representation.
Expand Down Expand Up @@ -128,11 +129,11 @@ class ArrayMetadataV2Partial(TypedDict, total=False):
chunks: tuple[int, ...]
dtype: DataTypeMetadataV2
compressor: CodecMetadataV2 | None
fill_value: object
fill_value: JSONValue
order: ArrayOrderV2
filters: tuple[CodecMetadataV2, ...] | None
dimension_separator: NotRequired[ArrayDimensionSeparatorV2]
attributes: NotRequired[Mapping[str, object]]
attributes: NotRequired[Mapping[str, JSONValue]]
"""User attributes from the sibling `.zattrs` file (not part of `.zarray`).

See the class docstring for the rationale behind the merged representation.
Expand Down
4 changes: 3 additions & 1 deletion packages/zarr-metadata/src/zarr_metadata/v2/attributes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@

from collections.abc import Mapping

ZAttrsMetadata = Mapping[str, object]
from zarr_metadata._common import JSONValue

ZAttrsMetadata = Mapping[str, JSONValue]
"""On-disk `.zattrs` file content.

A JSON object holding user-defined attributes for a v2 array or group.
Expand Down
4 changes: 3 additions & 1 deletion packages/zarr-metadata/src/zarr_metadata/v2/codec.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@

from typing_extensions import TypedDict

from zarr_metadata._common import JSONValue

class CodecMetadataV2(TypedDict, extra_items=object): # type: ignore[call-arg]

class CodecMetadataV2(TypedDict, extra_items=JSONValue): # type: ignore[call-arg]
"""
A numcodecs configuration dict, used as a v2 compressor or filter.

Expand Down
6 changes: 4 additions & 2 deletions packages/zarr-metadata/src/zarr_metadata/v2/group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@

from typing_extensions import TypedDict

from zarr_metadata._common import JSONValue


class ZGroupMetadata(TypedDict):
"""
Expand Down Expand Up @@ -39,7 +41,7 @@ class GroupMetadataV2(TypedDict):
"""

zarr_format: Literal[2]
attributes: NotRequired[Mapping[str, object]]
attributes: NotRequired[Mapping[str, JSONValue]]


class GroupMetadataV2Partial(TypedDict, total=False):
Expand Down Expand Up @@ -69,7 +71,7 @@ class GroupMetadataV2Partial(TypedDict, total=False):
"""

zarr_format: Literal[2]
attributes: NotRequired[Mapping[str, object]]
attributes: NotRequired[Mapping[str, JSONValue]]


__all__ = [
Expand Down
11 changes: 6 additions & 5 deletions packages/zarr-metadata/src/zarr_metadata/v3/array.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,11 @@

from typing_extensions import TypedDict

from zarr_metadata._common import JSONValue
from zarr_metadata.v3._common import MetadataFieldV3


class ExtensionFieldV3(TypedDict, extra_items=object): # type: ignore[call-arg]
class ExtensionFieldV3(TypedDict, extra_items=JSONValue): # type: ignore[call-arg]
"""
Required shape of any extension field on a v3 metadata document.

Expand Down Expand Up @@ -55,9 +56,9 @@ class ArrayMetadataV3(TypedDict, extra_items=ExtensionFieldV3): # type: ignore[
shape: tuple[int, ...]
chunk_grid: MetadataFieldV3
chunk_key_encoding: MetadataFieldV3
fill_value: object
fill_value: JSONValue
codecs: tuple[MetadataFieldV3, ...]
attributes: NotRequired[Mapping[str, object]]
attributes: NotRequired[Mapping[str, JSONValue]]
storage_transformers: NotRequired[tuple[MetadataFieldV3, ...]]
dimension_names: NotRequired[tuple[str | None, ...]]

Expand Down Expand Up @@ -91,9 +92,9 @@ class ArrayMetadataV3Partial(TypedDict, total=False, extra_items=ExtensionFieldV
shape: tuple[int, ...]
chunk_grid: MetadataFieldV3
chunk_key_encoding: MetadataFieldV3
fill_value: object
fill_value: JSONValue
codecs: tuple[MetadataFieldV3, ...]
attributes: NotRequired[Mapping[str, object]]
attributes: NotRequired[Mapping[str, JSONValue]]
storage_transformers: NotRequired[tuple[MetadataFieldV3, ...]]
dimension_names: NotRequired[tuple[str | None, ...]]

Expand Down
3 changes: 2 additions & 1 deletion packages/zarr-metadata/src/zarr_metadata/v3/codec/cast_value.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@

from typing_extensions import TypedDict

from zarr_metadata._common import JSONValue
from zarr_metadata.v3._common import MetadataFieldV3

CAST_VALUE_CODEC_NAME: Final = "cast_value"
Expand Down Expand Up @@ -46,7 +47,7 @@
OUT_OF_RANGE_MODE: Final = ("clamp", "wrap")
"""Tuple of permitted values for the `out_of_range` field of the `cast_value` codec."""

ScalarMapEntry = tuple[object, object]
ScalarMapEntry = tuple[JSONValue, JSONValue]
"""A single `[input, output]` mapping in a `scalar_map` direction.

Each scalar is JSON-encoded per its data type's fill-value rules (so
Expand Down
6 changes: 4 additions & 2 deletions packages/zarr-metadata/src/zarr_metadata/v3/codec/scale_offset.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@

from typing_extensions import TypedDict

from zarr_metadata._common import JSONValue

SCALE_OFFSET_CODEC_NAME: Final = "scale_offset"
"""The `name` field value of the `scale_offset` codec."""

Expand All @@ -26,8 +28,8 @@ class ScaleOffsetCodecConfiguration(TypedDict):
permitted in addition to numbers.
"""

offset: NotRequired[object]
scale: NotRequired[object]
offset: NotRequired[JSONValue]
scale: NotRequired[JSONValue]


class ScaleOffsetCodecObject(TypedDict):
Expand Down
7 changes: 5 additions & 2 deletions packages/zarr-metadata/src/zarr_metadata/v3/data_type/struct.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@

from typing_extensions import ReadOnly, TypedDict

from zarr_metadata._common import JSONValue
from zarr_metadata.v3._common import MetadataFieldV3

STRUCT_DATA_TYPE_NAME: Final = "struct"
"""The `name` field value of the `struct` data type."""

Expand All @@ -30,7 +33,7 @@ class StructField(TypedDict):
"""

name: ReadOnly[str]
data_type: ReadOnly[object]
data_type: ReadOnly[MetadataFieldV3]


class StructConfiguration(TypedDict):
Expand All @@ -46,7 +49,7 @@ class Struct(TypedDict):
configuration: StructConfiguration


StructFillValue = Mapping[str, object]
StructFillValue = Mapping[str, JSONValue]
"""Permitted JSON shape of the `fill_value` field for `struct`.

A JSON object mapping each field name to that field's fill value. Field
Expand Down
5 changes: 3 additions & 2 deletions packages/zarr-metadata/src/zarr_metadata/v3/group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@

from typing_extensions import TypedDict

from zarr_metadata._common import JSONValue
from zarr_metadata.v3.array import ExtensionFieldV3


Expand All @@ -22,7 +23,7 @@ class GroupMetadataV3(TypedDict, extra_items=ExtensionFieldV3): # type: ignore[

zarr_format: Literal[3]
node_type: Literal["group"]
attributes: NotRequired[Mapping[str, object]]
attributes: NotRequired[Mapping[str, JSONValue]]


class GroupMetadataV3Partial(TypedDict, total=False, extra_items=ExtensionFieldV3): # type: ignore[call-arg]
Expand Down Expand Up @@ -50,7 +51,7 @@ class GroupMetadataV3Partial(TypedDict, total=False, extra_items=ExtensionFieldV

zarr_format: Literal[3]
node_type: Literal["group"]
attributes: NotRequired[Mapping[str, object]]
attributes: NotRequired[Mapping[str, JSONValue]]


__all__ = [
Expand Down
Loading