Skip to content

v3

zarr_metadata.v3

Zarr v3 metadata types.

zarr_metadata.v3.ZarrV3MetadataFieldJSON module-attribute 

ZarrV3MetadataFieldJSON = str | ZarrV3NamedConfigJSON

The JSON shape of any v3 metadata extension-point entry: either a bare short-hand name string or a {name, configuration, must_understand} envelope.

Used for data_type, chunk_grid, chunk_key_encoding, individual codec entries, and storage_transformers in v3 array metadata, and for the inner codecs / index_codecs lists of the sharding_indexed codec.

zarr_metadata.v3.array

Zarr v3 array metadata types.

ZARR_V3_ARRAY_METADATA_STORE_KEY module-attribute 

ZARR_V3_ARRAY_METADATA_STORE_KEY: Final[
    ZarrV3ArrayMetadataStoreKey
] = "zarr.json"

The store key a v3 array's metadata document is persisted under.

v3 uses one key for both node types; the document's node_type field distinguishes an array from a group.

ZarrV3ArrayMetadataStoreKey module-attribute 

ZarrV3ArrayMetadataStoreKey = Literal['zarr.json']

Literal type of the store key holding a v3 array's metadata document.

ZarrV3ExtensionField module-attribute 

ZarrV3ExtensionField: TypeAlias = JSONValue

The JSON value of an unknown top-level v3 metadata field.

An object carrying the literal member must_understand: false may be ignored. Every other JSON shape implicitly requires understanding; recognition itself belongs to the reader rather than this structural type.

__all__ module-attribute 

__all__ = [
    "ZARR_V3_ARRAY_METADATA_STORE_KEY",
    "ZarrV3ArrayMetadataJSON",
    "ZarrV3ArrayMetadataJSONPartial",
    "ZarrV3ArrayMetadataStoreKey",
    "ZarrV3ExtensionField",
]

ZarrV3ArrayMetadataJSON

Bases: TypedDict

Zarr v3 array metadata document (the zarr.json content for an array).

Extra keys may contain arbitrary JSON values.

See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#array-metadata

Source code in src/zarr_metadata/v3/array.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class ZarrV3ArrayMetadataJSON(TypedDict, extra_items=ZarrV3ExtensionField):
    """
    Zarr v3 array metadata document (the `zarr.json` content for an array).

    Extra keys may contain arbitrary JSON values.

    See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#array-metadata
    """

    zarr_format: Literal[3]
    node_type: Literal["array"]
    data_type: ZarrV3MetadataFieldJSON
    shape: tuple[int, ...]
    chunk_grid: ZarrV3MetadataFieldJSON
    chunk_key_encoding: ZarrV3MetadataFieldJSON
    fill_value: JSONValue
    codecs: tuple[ZarrV3MetadataFieldJSON, ...]
    attributes: NotRequired[Mapping[str, JSONValue]]
    storage_transformers: NotRequired[tuple[ZarrV3MetadataFieldJSON, ...]]
    dimension_names: NotRequired[tuple[str | None, ...]]

attributes instance-attribute 

attributes: NotRequired[Mapping[str, JSONValue]]

chunk_grid instance-attribute 

chunk_grid: ZarrV3MetadataFieldJSON

chunk_key_encoding instance-attribute 

chunk_key_encoding: ZarrV3MetadataFieldJSON

codecs instance-attribute 

codecs: tuple[ZarrV3MetadataFieldJSON, ...]

data_type instance-attribute 

data_type: ZarrV3MetadataFieldJSON

dimension_names instance-attribute 

dimension_names: NotRequired[tuple[str | None, ...]]

fill_value instance-attribute 

fill_value: JSONValue

node_type instance-attribute 

node_type: Literal['array']

shape instance-attribute 

shape: tuple[int, ...]

storage_transformers instance-attribute 

storage_transformers: NotRequired[
    tuple[ZarrV3MetadataFieldJSON, ...]
]

zarr_format instance-attribute 

zarr_format: Literal[3]

ZarrV3ArrayMetadataJSONPartial

Bases: TypedDict

Partial form of ZarrV3ArrayMetadataJSON: every field is NotRequired.

Field annotations and extra_items= mirror ZarrV3ArrayMetadataJSON exactly. The only difference is total=False, which makes every key optional at the type level.

Use this when typing dicts that intentionally hold a subset of a complete v3 array metadata document — e.g. test fixtures that override only a few fields of a base template, or callers that build a fragment to be merged into a complete document elsewhere.

The NotRequired[...] wrappers on attributes, storage_transformers, and dimension_names are intentional: keeping them preserves byte-identical __annotations__ with ZarrV3ArrayMetadataJSON so the == check in tests/test_partial_equivalence.py passes without special-casing those fields (PEP 655 explicitly permits NotRequired inside total=False).

Drift between this type and ZarrV3ArrayMetadataJSON is prevented by tests/test_partial_equivalence.py.

Source code in src/zarr_metadata/v3/array.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
class ZarrV3ArrayMetadataJSONPartial(TypedDict, total=False, extra_items=ZarrV3ExtensionField):
    """
    Partial form of `ZarrV3ArrayMetadataJSON`: every field is `NotRequired`.

    Field annotations and `extra_items=` mirror `ZarrV3ArrayMetadataJSON` exactly.
    The only difference is `total=False`, which makes every key optional
    at the type level.

    Use this when typing dicts that intentionally hold a subset of a complete
    v3 array metadata document — e.g. test fixtures that override only a few
    fields of a base template, or callers that build a fragment to be merged
    into a complete document elsewhere.

    The `NotRequired[...]` wrappers on `attributes`, `storage_transformers`,
    and `dimension_names` are intentional: keeping them preserves byte-identical
    `__annotations__` with `ZarrV3ArrayMetadataJSON` so the `==` check in
    `tests/test_partial_equivalence.py` passes without special-casing those
    fields (PEP 655 explicitly permits `NotRequired` inside `total=False`).

    Drift between this type and `ZarrV3ArrayMetadataJSON` is prevented by
    `tests/test_partial_equivalence.py`.
    """

    zarr_format: Literal[3]
    node_type: Literal["array"]
    data_type: ZarrV3MetadataFieldJSON
    shape: tuple[int, ...]
    chunk_grid: ZarrV3MetadataFieldJSON
    chunk_key_encoding: ZarrV3MetadataFieldJSON
    fill_value: JSONValue
    codecs: tuple[ZarrV3MetadataFieldJSON, ...]
    attributes: NotRequired[Mapping[str, JSONValue]]
    storage_transformers: NotRequired[tuple[ZarrV3MetadataFieldJSON, ...]]
    dimension_names: NotRequired[tuple[str | None, ...]]

attributes instance-attribute 

attributes: NotRequired[Mapping[str, JSONValue]]

chunk_grid instance-attribute 

chunk_grid: ZarrV3MetadataFieldJSON

chunk_key_encoding instance-attribute 

chunk_key_encoding: ZarrV3MetadataFieldJSON

codecs instance-attribute 

codecs: tuple[ZarrV3MetadataFieldJSON, ...]

data_type instance-attribute 

data_type: ZarrV3MetadataFieldJSON

dimension_names instance-attribute 

dimension_names: NotRequired[tuple[str | None, ...]]

fill_value instance-attribute 

fill_value: JSONValue

node_type instance-attribute 

node_type: Literal['array']

shape instance-attribute 

shape: tuple[int, ...]

storage_transformers instance-attribute 

storage_transformers: NotRequired[
    tuple[ZarrV3MetadataFieldJSON, ...]
]

zarr_format instance-attribute 

zarr_format: Literal[3]

zarr_metadata.v3.group

Zarr v3 group metadata types.

See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#group-metadata

ZARR_V3_GROUP_METADATA_STORE_KEY module-attribute 

ZARR_V3_GROUP_METADATA_STORE_KEY: Final[
    ZarrV3GroupMetadataStoreKey
] = "zarr.json"

The store key a v3 group's metadata document is persisted under.

v3 uses one key for both node types; the document's node_type field distinguishes a group from an array.

ZarrV3GroupMetadataStoreKey module-attribute 

ZarrV3GroupMetadataStoreKey = Literal['zarr.json']

Literal type of the store key holding a v3 group's metadata document.

__all__ module-attribute 

__all__ = [
    "ZARR_V3_GROUP_METADATA_STORE_KEY",
    "ZarrV3GroupMetadataJSON",
    "ZarrV3GroupMetadataJSONPartial",
    "ZarrV3GroupMetadataStoreKey",
]

ZarrV3GroupMetadataJSON

Bases: TypedDict

Zarr v3 group metadata document (the zarr.json content for a group).

Extra keys may contain arbitrary JSON values.

See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#group-metadata

Source code in src/zarr_metadata/v3/group.py 
15
16
17
18
19
20
21
22
23
24
25
26
class ZarrV3GroupMetadataJSON(TypedDict, extra_items=ZarrV3ExtensionField):
    """
    Zarr v3 group metadata document (the `zarr.json` content for a group).

    Extra keys may contain arbitrary JSON values.

    See https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#group-metadata
    """

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

attributes instance-attribute 

attributes: NotRequired[Mapping[str, JSONValue]]

node_type instance-attribute 

node_type: Literal['group']

zarr_format instance-attribute 

zarr_format: Literal[3]

ZarrV3GroupMetadataJSONPartial

Bases: TypedDict

Partial form of ZarrV3GroupMetadataJSON: every field is NotRequired.

Field annotations and extra_items= mirror ZarrV3GroupMetadataJSON exactly. The only difference is total=False, which makes every key optional at the type level.

Use this when typing dicts that intentionally hold a subset of a complete v3 group metadata document — e.g. test fixtures that override only a few fields of a base template, or callers that build a fragment to be merged into a complete document elsewhere.

The NotRequired[...] wrapper on attributes is intentional: keeping it preserves byte-identical __annotations__ with ZarrV3GroupMetadataJSON so the == check in tests/test_partial_equivalence.py passes without special-casing that field (PEP 655 explicitly permits NotRequired inside total=False).

Drift between this type and ZarrV3GroupMetadataJSON is prevented by tests/test_partial_equivalence.py.

Source code in src/zarr_metadata/v3/group.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
class ZarrV3GroupMetadataJSONPartial(TypedDict, total=False, extra_items=ZarrV3ExtensionField):
    """
    Partial form of `ZarrV3GroupMetadataJSON`: every field is `NotRequired`.

    Field annotations and `extra_items=` mirror `ZarrV3GroupMetadataJSON` exactly.
    The only difference is `total=False`, which makes every key optional
    at the type level.

    Use this when typing dicts that intentionally hold a subset of a complete
    v3 group metadata document — e.g. test fixtures that override only a few
    fields of a base template, or callers that build a fragment to be merged
    into a complete document elsewhere.

    The `NotRequired[...]` wrapper on `attributes` is intentional: keeping it
    preserves byte-identical `__annotations__` with `ZarrV3GroupMetadataJSON` so the
    `==` check in `tests/test_partial_equivalence.py` passes without
    special-casing that field (PEP 655 explicitly permits `NotRequired` inside
    `total=False`).

    Drift between this type and `ZarrV3GroupMetadataJSON` is prevented by
    `tests/test_partial_equivalence.py`.
    """

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

attributes instance-attribute 

attributes: NotRequired[Mapping[str, JSONValue]]

node_type instance-attribute 

node_type: Literal['group']

zarr_format instance-attribute 

zarr_format: Literal[3]

zarr_metadata.v3.consolidated

Zarr v3 consolidated metadata types.

There is no Zarr v3 specification for consolidated metadata. This module models the inline-on-group convention used by the reference Python implementation (and zarrs), where consolidated metadata is embedded as an extension field on a group's zarr.json.

This is a known non-core interoperability extension. Its {kind, must_understand, metadata} payload is an unknown top-level JSON value to the core document model; implementations that recognize the convention may interpret it through this dedicated type.

ZARR_V3_CONSOLIDATED_METADATA_KEY module-attribute 

ZARR_V3_CONSOLIDATED_METADATA_KEY: Final = (
    "consolidated_metadata"
)

The key under which consolidated metadata is embedded in a v3 group document.

Unlike the v2 .zmetadata file, this is not a store key: consolidated metadata is carried as an extension field inside the group's own zarr.json. Like its v2 counterpart it is a reference-implementation convention, not a spec artifact.

__all__ module-attribute 

__all__ = [
    "ZARR_V3_CONSOLIDATED_METADATA_KEY",
    "ZarrV3ConsolidatedMetadataJSON",
]

ZarrV3ConsolidatedMetadataJSON

Bases: TypedDict

Inline consolidated metadata embedded in a v3 group.

The metadata map contains only v3 array and group entries. V2 entries are excluded from this interoperability convention by design; the v3 core specification does not define consolidated metadata.

Source code in src/zarr_metadata/v3/consolidated.py 
23
24
25
26
27
28
29
30
31
32
33
34
class ZarrV3ConsolidatedMetadataJSON(TypedDict):
    """
    Inline consolidated metadata embedded in a v3 group.

    The `metadata` map contains only v3 array and group entries. V2 entries
    are excluded from this interoperability convention by design; the v3 core
    specification does not define consolidated metadata.
    """

    kind: Literal["inline"]
    must_understand: Literal[False]
    metadata: Mapping[str, ZarrV3ArrayMetadataJSON | ZarrV3GroupMetadataJSON]

kind instance-attribute 

kind: Literal['inline']

metadata instance-attribute 

metadata: Mapping[
    str, ZarrV3ArrayMetadataJSON | ZarrV3GroupMetadataJSON
]

must_understand instance-attribute 

must_understand: Literal[False]