API reference

The package is organized to mirror the structure of the Zarr specifications:

• zarr_metadata.model — frozen-dataclass document models, structural validators, loc-aware parsers, and the UNSET sentinel
• zarr_metadata.pydantic — optional Pydantic field types over the models
• zarr_metadata.v2 — TypedDict shapes for Zarr v2 documents (.zarray, .zgroup, .zattrs, .zmetadata)
• zarr_metadata.v3 — TypedDict shapes for Zarr v3 documents, with subpackages for chunk grids, chunk key encodings, codecs, and data types

The document types, models, and spec vocabulary — including the store keys — are re-exported at the top level, so from zarr_metadata import ZarrV3ArrayMetadataJSON and from zarr_metadata.v3.array import ZarrV3ArrayMetadataJSON are equivalent. The model layer's validators, parsers, type guards, and metadata key sets are imported from zarr_metadata.model directly.

Common types

A few cross-cutting aliases are exported only from the top-level zarr_metadata namespace:

zarr_metadata.JSONValue module-attribute

JSONValue = TypeAliasType(
    "JSONValue",
    int
    | float
    | bool
    | str
    | Sequence["JSONValue"]
    | Mapping[str, "JSONValue"]
    | None,
)

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.

The array arm is the covariant Sequence rather than the invariant list["JSONValue"] | tuple["JSONValue", ...], so values typed with a narrower element type still count as JSON values: a list[str] field on a TypedDict is assignable to JSONValue under Sequence but not under list[JSONValue] (list is invariant in its element type, and pyright's diagnostic for that failure suggests exactly this change). This is what lets downstream TypedDicts give their fields precise types (Sequence[str], list[int], ...) while remaining assignable to Mapping[str, JSONValue]. The type-level cost, accepted deliberately: Sequence says nothing about the concrete container, and it admits str/bytes (str was already a union arm); runtime code narrowing a JSON array must exclude str/bytes/ bytearray regardless of how this alias is spelled.

zarr_metadata.ZarrV3NamedConfigJSON

Bases: TypedDict

Externally-tagged union member for a metadata field.

The optional configuration mapping holds arbitrary JSON-encodable values. must_understand is implicitly true when absent.

Source code in src/zarr_metadata/_common.py

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

    The optional `configuration` mapping holds arbitrary JSON-encodable
    values. `must_understand` is implicitly true when absent.
    """

    name: str
    configuration: NotRequired[Mapping[str, JSONValue]]
    must_understand: NotRequired[bool]

configuration instance-attribute

configuration: NotRequired[Mapping[str, JSONValue]]

must_understand instance-attribute

must_understand: NotRequired[bool]

name instance-attribute

name: str