Skip to content

API reference

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

  • zarr_metadata.json_schema — JSON Schema output for any TypedDict, one v3 field, or a whole v3 zarr.json
  • zarr_metadata.model — document models (each one a document and the scope it was read in), the readers that return problems instead of raising them, and the UNSET sentinel
  • zarr_metadata.problems — ValidationProblem, ProblemKind, Problems and MetadataValidationError, which every reader reports, and shown, which formats a value for a message
  • zarr_metadata.pydantic — optional Pydantic field types over the models
  • zarr_metadata.typed_json — check, which type-checks a JSON value against any of the package's TypedDicts, read as the typing spec defines them, with every problem located
  • zarr_metadata.v2 — TypedDict shapes for Zarr v2 documents (.zarray, .zgroup, .zattrs, .zmetadata), and zarr_metadata.v2.definition: the v2 kinds of metadata, the scope CORE_V2, and the readers of one dtype or codec. Each dtype family's definition is in zarr_metadata.v2.data_type, and each codec's in zarr_metadata.v2.codec
  • zarr_metadata.v3 — TypedDict shapes for Zarr v3 documents, with subpackages for chunk grids, chunk key encodings, codecs, and data types
  • zarr_metadata.definition — what both formats share for reading a field: Definition, resolve, the three results of a reading (AcceptedField, UnclaimedField, RefusedField), and the scope type Context. Its module docstring is the guide
  • zarr_metadata.v3.definition — the five v3 kinds of metadata (CodecDefinition, DataTypeDefinition, ...), the codec pipeline types, and the v3 scopes CORE and CORE_AND_EXTENSIONS

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 readers are imported from zarr_metadata.model directly, and the problem types every reader reports from zarr_metadata.problems.

Common types

Two cross-cutting types are also exported from the top-level zarr_metadata namespace: JSONValue, documented in zarr_metadata.typed_json, and ZarrV3NamedConfigJSON, documented in zarr_metadata.v3.