Skip to content

zarr_metadata.v2

zarr_metadata.v2

Zarr v2 metadata types.

zarr_metadata.v2.array

Zarr v2 array metadata types.

ZARR_V2_ARRAY_DIMENSION_SEPARATOR module-attribute 

ZARR_V2_ARRAY_DIMENSION_SEPARATOR: Final = ('.', '/')

Tuple of permitted values for the dimension_separator field of v2 array metadata.

ZARR_V2_ARRAY_METADATA_STORE_KEY module-attribute 

ZARR_V2_ARRAY_METADATA_STORE_KEY: Final[
    ZarrV2ArrayMetadataStoreKey
] = ".zarray"

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

ZARR_V2_ARRAY_ORDER module-attribute 

ZARR_V2_ARRAY_ORDER: Final = ('C', 'F')

Tuple of permitted values for the order field of v2 array metadata.

ZarrV2ArrayDimensionSeparator module-attribute 

ZarrV2ArrayDimensionSeparator = Literal['.', '/']

Literal type of permitted values for the dimension_separator field of v2 array metadata.

"." (legacy default) joins chunk grid coordinates as 0.0, 0.1, ... "/" joins them as 0/0, 0/1, ... yielding nested directories.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

ZarrV2ArrayMetadataStoreKey module-attribute 

ZarrV2ArrayMetadataStoreKey = Literal['.zarray']

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

ZarrV2ArrayOrder module-attribute 

ZarrV2ArrayOrder = Literal['C', 'F']

Literal type of permitted values for the order field of v2 array metadata.

"C" (row-major) or "F" (column-major) — the in-chunk byte layout.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

ZarrV2DataTypeMetadata module-attribute 

ZarrV2DataTypeMetadata = TypeAliasType(
    "ZarrV2DataTypeMetadata",
    str
    | tuple[
        tuple[str, "ZarrV2DataTypeMetadata"]
        | tuple[
            str, "ZarrV2DataTypeMetadata", tuple[int, ...]
        ],
        ...,
    ],
)

The v2 dtype representation.

Either a numpy-style dtype string (e.g. "<f8", "|S10") or a tuple of field records describing a structured dtype. Each field record is either a 2-tuple (name, datatype) or a 3-tuple (name, datatype, shape) (the 3-tuple form indicates a subarray field). A field datatype may itself be another structured dtype.

Endianness is encoded in the prefix character of the dtype string; parsing it out is a caller concern, not part of this type.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#data-type-encoding

__all__ module-attribute 

__all__ = [
    "ZARR_V2_ARRAY_DIMENSION_SEPARATOR",
    "ZARR_V2_ARRAY_METADATA_STORE_KEY",
    "ZARR_V2_ARRAY_ORDER",
    "ZarrV2ArrayDimensionSeparator",
    "ZarrV2ArrayMetadataJSON",
    "ZarrV2ArrayMetadataJSONPartial",
    "ZarrV2ArrayMetadataStoreKey",
    "ZarrV2ArrayOrder",
    "ZarrV2DataTypeMetadata",
    "ZarrV2ZArrayJSON",
]

ZarrV2ArrayMetadataJSON

Bases: TypedDict

Zarr v2 array metadata document, in-memory merged form.

Models the union of .zarray (the spec-defined fields) and .zattrs (user attributes). On disk, attributes live in a sibling .zattrs file and are not part of .zarray; this type folds them in as the attributes field so a single TypedDict represents the complete in-memory state of a v2 array node. Consumers that read or write a real .zarray file should split / merge attributes accordingly, or use ZarrV2ZArrayJSON (strict on-disk) plus ZarrV2ZAttrsJSON directly.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

Source code in src/zarr_metadata/v2/array.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class ZarrV2ArrayMetadataJSON(TypedDict):
    """
    Zarr v2 array metadata document, in-memory merged form.

    Models the union of `.zarray` (the spec-defined fields) and `.zattrs`
    (user attributes). On disk, attributes live in a sibling `.zattrs` file
    and are not part of `.zarray`; this type folds them in as the
    `attributes` field so a single TypedDict represents the complete
    in-memory state of a v2 array node. Consumers that read or write a
    real `.zarray` file should split / merge `attributes` accordingly,
    or use `ZarrV2ZArrayJSON` (strict on-disk) plus `ZarrV2ZAttrsJSON` directly.

    See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
    """

    zarr_format: Literal[2]
    shape: tuple[int, ...]
    chunks: tuple[int, ...]
    dtype: ZarrV2DataTypeMetadata
    compressor: ZarrV2CodecMetadata | None
    fill_value: JSONValue
    order: ZarrV2ArrayOrder
    filters: tuple[ZarrV2CodecMetadata, ...] | None
    dimension_separator: NotRequired[ZarrV2ArrayDimensionSeparator]
    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.
    """

attributes instance-attribute 

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.

chunks instance-attribute 

chunks: tuple[int, ...]

compressor instance-attribute 

compressor: ZarrV2CodecMetadata | None

dimension_separator instance-attribute 

dimension_separator: NotRequired[
    ZarrV2ArrayDimensionSeparator
]

dtype instance-attribute 

dtype: ZarrV2DataTypeMetadata

fill_value instance-attribute 

fill_value: JSONValue

filters instance-attribute 

filters: tuple[ZarrV2CodecMetadata, ...] | None

order instance-attribute 

order: ZarrV2ArrayOrder

shape instance-attribute 

shape: tuple[int, ...]

zarr_format instance-attribute 

zarr_format: Literal[2]

ZarrV2ArrayMetadataJSONPartial

Bases: TypedDict

Partial form of ZarrV2ArrayMetadataJSON: every field is NotRequired.

Field annotations mirror ZarrV2ArrayMetadataJSON 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 v2 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 dimension_separator and attributes are intentional: keeping them preserves byte-identical __annotations__ with ZarrV2ArrayMetadataJSON so the == check in tests/test_partial_equivalence.py passes without special-casing those fields (PEP 655 explicitly permits NotRequired inside total=False).

Note: v2 array metadata has no extra_items setting (the v2 spec has no extension-field concept), so this partial inherits the same closed shape.

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

Source code in src/zarr_metadata/v2/array.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
class ZarrV2ArrayMetadataJSONPartial(TypedDict, total=False):
    """
    Partial form of `ZarrV2ArrayMetadataJSON`: every field is `NotRequired`.

    Field annotations mirror `ZarrV2ArrayMetadataJSON` 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
    v2 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 `dimension_separator` and `attributes`
    are intentional: keeping them preserves byte-identical `__annotations__`
    with `ZarrV2ArrayMetadataJSON` so the `==` check in
    `tests/test_partial_equivalence.py` passes without special-casing those
    fields (PEP 655 explicitly permits `NotRequired` inside `total=False`).

    Note: v2 array metadata has no `extra_items` setting (the v2 spec has no
    extension-field concept), so this partial inherits the same closed shape.

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

    zarr_format: Literal[2]
    shape: tuple[int, ...]
    chunks: tuple[int, ...]
    dtype: ZarrV2DataTypeMetadata
    compressor: ZarrV2CodecMetadata | None
    fill_value: JSONValue
    order: ZarrV2ArrayOrder
    filters: tuple[ZarrV2CodecMetadata, ...] | None
    dimension_separator: NotRequired[ZarrV2ArrayDimensionSeparator]
    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.
    """

attributes instance-attribute 

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.

chunks instance-attribute 

chunks: tuple[int, ...]

compressor instance-attribute 

compressor: ZarrV2CodecMetadata | None

dimension_separator instance-attribute 

dimension_separator: NotRequired[
    ZarrV2ArrayDimensionSeparator
]

dtype instance-attribute 

dtype: ZarrV2DataTypeMetadata

fill_value instance-attribute 

fill_value: JSONValue

filters instance-attribute 

filters: tuple[ZarrV2CodecMetadata, ...] | None

order instance-attribute 

order: ZarrV2ArrayOrder

shape instance-attribute 

shape: tuple[int, ...]

zarr_format instance-attribute 

zarr_format: Literal[2]

ZarrV2ZArrayJSON

Bases: TypedDict

On-disk .zarray file content.

Strict shape of the JSON document persisted at <path>/.zarray for a v2 array. User attributes live in a sibling .zattrs file and are NOT part of this type; see ZarrV2ZAttrsJSON.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

Source code in src/zarr_metadata/v2/array.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
class ZarrV2ZArrayJSON(TypedDict):
    """
    On-disk `.zarray` file content.

    Strict shape of the JSON document persisted at `<path>/.zarray` for
    a v2 array. User attributes live in a sibling `.zattrs` file and are
    NOT part of this type; see `ZarrV2ZAttrsJSON`.

    See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
    """

    zarr_format: Literal[2]
    shape: tuple[int, ...]
    chunks: tuple[int, ...]
    dtype: ZarrV2DataTypeMetadata
    compressor: ZarrV2CodecMetadata | None
    fill_value: JSONValue
    order: ZarrV2ArrayOrder
    filters: tuple[ZarrV2CodecMetadata, ...] | None
    dimension_separator: NotRequired[ZarrV2ArrayDimensionSeparator]

chunks instance-attribute 

chunks: tuple[int, ...]

compressor instance-attribute 

compressor: ZarrV2CodecMetadata | None

dimension_separator instance-attribute 

dimension_separator: NotRequired[
    ZarrV2ArrayDimensionSeparator
]

dtype instance-attribute 

dtype: ZarrV2DataTypeMetadata

fill_value instance-attribute 

fill_value: JSONValue

filters instance-attribute 

filters: tuple[ZarrV2CodecMetadata, ...] | None

order instance-attribute 

order: ZarrV2ArrayOrder

shape instance-attribute 

shape: tuple[int, ...]

zarr_format instance-attribute 

zarr_format: Literal[2]

zarr_metadata.v2.group

Zarr v2 group metadata types.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

ZARR_V2_GROUP_METADATA_STORE_KEY module-attribute 

ZARR_V2_GROUP_METADATA_STORE_KEY: Final[
    ZarrV2GroupMetadataStoreKey
] = ".zgroup"

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

ZarrV2GroupMetadataStoreKey module-attribute 

ZarrV2GroupMetadataStoreKey = Literal['.zgroup']

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

__all__ module-attribute 

__all__ = [
    "ZARR_V2_GROUP_METADATA_STORE_KEY",
    "ZarrV2GroupMetadataJSON",
    "ZarrV2GroupMetadataJSONPartial",
    "ZarrV2GroupMetadataStoreKey",
    "ZarrV2ZGroupJSON",
]

ZarrV2GroupMetadataJSON

Bases: TypedDict

Zarr v2 group metadata document, in-memory merged form.

Models the union of .zgroup (the spec-defined zarr_format field) and .zattrs (user attributes). On disk these are persisted as two separate files; this type folds them so a single TypedDict represents the complete in-memory state of a v2 group node. Consumers that read or write the real on-disk files should use ZarrV2ZGroupJSON (strict .zgroup) plus ZarrV2ZAttrsJSON directly.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

Source code in src/zarr_metadata/v2/group.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class ZarrV2GroupMetadataJSON(TypedDict):
    """
    Zarr v2 group metadata document, in-memory merged form.

    Models the union of `.zgroup` (the spec-defined `zarr_format` field)
    and `.zattrs` (user attributes). On disk these are persisted as two
    separate files; this type folds them so a single TypedDict represents
    the complete in-memory state of a v2 group node. Consumers that read
    or write the real on-disk files should use `ZarrV2ZGroupJSON` (strict
    `.zgroup`) plus `ZarrV2ZAttrsJSON` directly.

    See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
    """

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

attributes instance-attribute 

attributes: NotRequired[Mapping[str, JSONValue]]

zarr_format instance-attribute 

zarr_format: Literal[2]

ZarrV2GroupMetadataJSONPartial

Bases: TypedDict

Partial form of ZarrV2GroupMetadataJSON: every field is NotRequired.

Field annotations mirror ZarrV2GroupMetadataJSON 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 v2 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. Provided for symmetry with the other *Partial types; the practical effect is that zarr_format becomes optional.

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

Note: v2 group metadata has no extra_items setting (the v2 spec has no extension-field concept), so this partial inherits the same closed shape.

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

Source code in src/zarr_metadata/v2/group.py 
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
class ZarrV2GroupMetadataJSONPartial(TypedDict, total=False):
    """
    Partial form of `ZarrV2GroupMetadataJSON`: every field is `NotRequired`.

    Field annotations mirror `ZarrV2GroupMetadataJSON` 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
    v2 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. Provided for symmetry with the other
    `*Partial` types; the practical effect is that `zarr_format` becomes optional.

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

    Note: v2 group metadata has no `extra_items` setting (the v2 spec has no
    extension-field concept), so this partial inherits the same closed shape.

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

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

attributes instance-attribute 

attributes: NotRequired[Mapping[str, JSONValue]]

zarr_format instance-attribute 

zarr_format: Literal[2]

ZarrV2ZGroupJSON

Bases: TypedDict

On-disk .zgroup file content.

Strict shape of the JSON document persisted at <path>/.zgroup for a v2 group. The spec defines exactly one field. User attributes live in a sibling .zattrs file and are NOT part of this type; see ZarrV2ZAttrsJSON.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

Source code in src/zarr_metadata/v2/group.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
class ZarrV2ZGroupJSON(TypedDict):
    """
    On-disk `.zgroup` file content.

    Strict shape of the JSON document persisted at `<path>/.zgroup` for
    a v2 group. The spec defines exactly one field. User attributes live
    in a sibling `.zattrs` file and are NOT part of this type; see
    `ZarrV2ZAttrsJSON`.

    See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
    """

    zarr_format: Literal[2]

zarr_format instance-attribute 

zarr_format: Literal[2]

zarr_metadata.v2.attributes

Zarr v2 user-attributes file content.

See https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

ZARR_V2_ATTRIBUTES_STORE_KEY module-attribute 

ZARR_V2_ATTRIBUTES_STORE_KEY: Final[
    ZarrV2AttributesStoreKey
] = ".zattrs"

The store key a v2 node's user attributes are persisted under.

Shared by arrays and groups: both node types keep their attributes in a sibling .zattrs file.

ZarrV2AttributesStoreKey module-attribute 

ZarrV2AttributesStoreKey = Literal['.zattrs']

Literal type of the store key holding a v2 node's user attributes.

ZarrV2ZAttrsJSON module-attribute 

ZarrV2ZAttrsJSON = Mapping[str, JSONValue]

On-disk .zattrs file content.

A JSON object holding user-defined attributes for a v2 array or group. Spec-defined keys for arrays / groups live in sibling .zarray / .zgroup files (modeled by ZarrV2ZArrayJSON / ZarrV2ZGroupJSON). This type does not constrain the keys or values of the attributes mapping.

__all__ module-attribute 

__all__ = [
    "ZARR_V2_ATTRIBUTES_STORE_KEY",
    "ZarrV2AttributesStoreKey",
    "ZarrV2ZAttrsJSON",
]

zarr_metadata.v2.codec

Zarr v2 codec configuration shape.

In v2, compressors and filters are numcodecs configuration dicts: a required id field naming the codec, plus arbitrary codec-specific extra fields.

__all__ module-attribute 

__all__ = ['ZarrV2CodecMetadata']

ZarrV2CodecMetadata

Bases: TypedDict

A numcodecs configuration dict, used as a v2 compressor or filter.

The required id field names the codec; codec-specific parameters (e.g. cname, clevel for blosc) appear as extra fields.

See the "compressor" and "filters" sections of https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html

Source code in src/zarr_metadata/v2/codec.py 
13
14
15
16
17
18
19
20
21
22
23
24
class ZarrV2CodecMetadata(TypedDict, extra_items=JSONValue):
    """
    A numcodecs configuration dict, used as a v2 compressor or filter.

    The required `id` field names the codec; codec-specific parameters
    (e.g. `cname`, `clevel` for blosc) appear as extra fields.

    See the "compressor" and "filters" sections of
    https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html
    """

    id: str

id instance-attribute 

id: str

zarr_metadata.v2.consolidated

Zarr v2 consolidated metadata (.zmetadata file).

This module models the de-facto .zmetadata file used by the reference Python implementation of Zarr v2. This is NOT a spec artifact. There is no Zarr v2 specification that defines .zmetadata; it is a canonical-implementation convention.

ZARR_V2_CONSOLIDATED_METADATA_STORE_KEY module-attribute 

ZARR_V2_CONSOLIDATED_METADATA_STORE_KEY: Final[
    ZarrV2ConsolidatedMetadataStoreKey
] = ".zmetadata"

The store key a v2 hierarchy's consolidated metadata is persisted under.

Like the document it names, this is a reference-implementation convention rather than a spec artifact; see the module docstring.

ZarrV2ConsolidatedMetadataStoreKey module-attribute 

ZarrV2ConsolidatedMetadataStoreKey = Literal['.zmetadata']

Literal type of the store key holding a v2 hierarchy's consolidated metadata.

__all__ module-attribute 

__all__ = [
    "ZARR_V2_CONSOLIDATED_METADATA_STORE_KEY",
    "ZarrV2ConsolidatedMetadataJSON",
    "ZarrV2ConsolidatedMetadataStoreKey",
]

ZarrV2ConsolidatedMetadataJSON

Bases: TypedDict

.zmetadata file contents.

The metadata map uses flat path keys ("foo/bar/.zarray", "foo/.zattrs", etc.) pointing to the JSON contents of the file at that path. The keys include the filename suffix, not just the node path; the value's shape is determined by which file the key points at:

  • <path>/.zarray -> ZarrV2ZArrayJSON
  • <path>/.zgroup -> ZarrV2ZGroupJSON
  • <path>/.zattrs -> ZarrV2ZAttrsJSON

The TypedDict cannot discriminate the value shape on the key suffix at the type level; consumers should narrow at runtime by inspecting key.endswith(".zarray") etc.

Source code in src/zarr_metadata/v2/consolidated.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
class ZarrV2ConsolidatedMetadataJSON(TypedDict):
    """
    `.zmetadata` file contents.

    The `metadata` map uses flat path keys (`"foo/bar/.zarray"`,
    `"foo/.zattrs"`, etc.) pointing to the JSON contents of the file at
    that path. The keys include the filename suffix, not just the node
    path; the value's shape is determined by which file the key points at:

    - `<path>/.zarray` -> `ZarrV2ZArrayJSON`
    - `<path>/.zgroup` -> `ZarrV2ZGroupJSON`
    - `<path>/.zattrs` -> `ZarrV2ZAttrsJSON`

    The TypedDict cannot discriminate the value shape on the key suffix
    at the type level; consumers should narrow at runtime by inspecting
    `key.endswith(".zarray")` etc.
    """

    zarr_consolidated_format: int
    metadata: Mapping[str, ZarrV2ZArrayJSON | ZarrV2ZGroupJSON | ZarrV2ZAttrsJSON]

metadata instance-attribute 

metadata: Mapping[
    str,
    ZarrV2ZArrayJSON | ZarrV2ZGroupJSON | ZarrV2ZAttrsJSON,
]

zarr_consolidated_format instance-attribute 

zarr_consolidated_format: int