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 additional field inside the group's own zarr.json. The core spec names the field and its envelope ("For historical reasons, group metadata documents may contain an additional field named consolidated_metadata"); the entry format, like the v2 counterpart, is a reference-implementation convention. https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816

__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 acknowledges consolidated_metadata as a historical additional field and fixes this envelope, but leaves the entries to the reference implementation: https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816

Source code in src/zarr_metadata/v3/consolidated.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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 acknowledges `consolidated_metadata` as a historical
    additional field and fixes this envelope, but leaves the entries to the
    reference implementation:
      https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816
    """

    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]