feat:metadata package

.github/workflows/zarr-metadata.yml

@@ -0,0 +1,99 @@
+name: zarr-metadata
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'packages/zarr-metadata/**'
+      - '.github/workflows/zarr-metadata.yml'
+  pull_request:
+    paths:
+      - 'packages/zarr-metadata/**'
+      - '.github/workflows/zarr-metadata.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest py=${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-metadata
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Sync test dependency group
+        run: uv sync --group test --python ${{ matrix.python-version }}
+      - name: Run pytest
+        run: uv run --group test pytest tests
+
+  ruff:
+    name: ruff
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-metadata
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - name: Run ruff
+        run: uvx ruff check .
+
+  pyright:
+    name: pyright
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-metadata
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Sync test dependency group
+        run: uv sync --group test --python 3.11
+      - name: Run pyright
+        run: uv run --group test --with pyright pyright src
+
+  zarr-metadata-complete:
+    name: zarr-metadata complete
+    needs: [test, ruff, pyright]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check failure
+        if: |
+          contains(needs.*.result, 'failure') ||
+          contains(needs.*.result, 'cancelled')
+        run: exit 1
+      - name: Success
+        run: echo Success!

.gitignore

@@ -91,3 +91,6 @@ tests/.hypothesis
 
 zarr/version.py
 zarr.egg-info/
+
+# zarr-metadata package lockfile (a library, not an app)
+packages/zarr-metadata/uv.lock

.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
     rev: v1.19.1
     hooks:
       - id: mypy
-        files: src|tests
+        files: ^(src|tests)/
         additional_dependencies:
           # Package dependencies
           - packaging

packages/zarr-metadata/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2025 Zarr Developers <https://github.com/zarr-developers>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/zarr-metadata/README.md

@@ -0,0 +1,52 @@
+# zarr-metadata
+
+Python type definitions for Zarr v2 and v3 metadata.
+
+## What this is
+
+A typed-data package: `TypedDict` definitions and `Literal` aliases for the
+JSON shapes specified by the [Zarr v2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html)
+and [Zarr v3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html)
+specifications, plus types for [`zarr-extensions`](https://github.com/zarr-developers/zarr-extensions/)
+and a few widely-used-but-unspecified entities (e.g. consolidated metadata).
+
+## What this is for
+
+These types describe the JSON shape of Zarr metadata. They are
+intended for libraries that **read, write, validate, or transform**
+Zarr metadata. Pair them with a runtime validator like
+[pydantic](https://docs.pydantic.dev/) to check JSON loaded from disk:
+
+```python
+import json
+from pydantic import TypeAdapter
+from zarr_metadata.v3.array import ArrayMetadataV3
+
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
+
+metadata = TypeAdapter(ArrayMetadataV3).validate_python(raw)
+```
+
+## What this is *not*
+
+- Not a parser or builder. There are no `make_array_metadata(...)` factories —
+  that surface belongs to consumer libraries.
+- Not a runtime validator on its own. Pair with `pydantic`, `msgspec`, or
+  similar to enforce shapes at decode time.
+
+Even with a runtime validator, these types only describe **structural**
+shape — they will not flag *semantically* invalid metadata, like a 3D v3
+array whose `dimension_names` has 4 entries instead of 3. That's a job
+for downstream validator routines.
+
+## Scope
+
+At minimum, this library supports what Zarr-Python needs: the complete
+Zarr v2 and v3 specs, consolidated metadata, and a subset of the metadata
+defined in `zarr-extensions`. We are generally open to contributions that
+add types for Zarr metadata with a published spec.
+
+## License
+
+[MIT](./LICENSE.txt)

packages/zarr-metadata/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling>=1.29.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zarr-metadata"
+version = "0.1.0"
+description = "Spec-defined metadata types for Zarr v2 and v3."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+authors = [
+    { name = "Davis Bennett", email = "davis.v.bennett@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typing_extensions>=4.13",
+]
+
+[dependency-groups]
+test = ["pytest", "pydantic>=2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zarr_metadata"]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+target-version = "py311"
+
+[tool.pytest.ini_options]
+minversion = "7"
+testpaths = ["tests"]
+xfail_strict = true
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+filterwarnings = [
+    "error",
+    # pydantic warns about ReadOnly TypedDict items not being enforced at runtime.
+    # That's expected here — we rely on type-checker enforcement, not pydantic mutation guards.
+    "ignore::UserWarning:pydantic._internal._generate_schema",
+]
+
+[tool.numpydoc_validation]
+checks = [
+    "GL10",
+    "SS04",
+    "PR02",
+    "PR03",
+    "PR05",
+    "PR06",
+]
+
+[tool.pyright]
+include = ["src"]
+enableExperimentalFeatures = true
+typeCheckingMode = "strict"
+pythonVersion = "3.11"

packages/zarr-metadata/src/zarr_metadata/__init__.py

@@ -0,0 +1,36 @@
+from zarr_metadata._common import NamedConfig
+from zarr_metadata.v2.array import (
+    ArrayDimensionSeparatorV2,
+    ArrayMetadataV2,
+    ArrayOrderV2,
+    DataTypeMetadataV2,
+)
+from zarr_metadata.v2.codec import CodecMetadataV2
+from zarr_metadata.v2.consolidated import ConsolidatedMetadataV2
+from zarr_metadata.v2.group import GroupMetadataV2
+from zarr_metadata.v3._common import MetadataFieldV3
+from zarr_metadata.v3.array import ArrayMetadataV3, ExtensionFieldV3
+from zarr_metadata.v3.consolidated import ConsolidatedMetadataV3
+from zarr_metadata.v3.group import GroupMetadataV3
+
+__version__ = "0.1.0"
+"""Hardcoded package version. Must match the `version` field in
+`pyproject.toml`; the sync is enforced by `tests/test_version.py`."""
+
+
+__all__ = [
+    "ArrayDimensionSeparatorV2",
+    "ArrayMetadataV2",
+    "ArrayMetadataV3",
+    "ArrayOrderV2",
+    "CodecMetadataV2",
+    "ConsolidatedMetadataV2",
+    "ConsolidatedMetadataV3",
+    "DataTypeMetadataV2",
+    "ExtensionFieldV3",
+    "GroupMetadataV2",
+    "GroupMetadataV3",
+    "MetadataFieldV3",
+    "NamedConfig",
+    "__version__",
+]

packages/zarr-metadata/src/zarr_metadata/_common.py

@@ -0,0 +1,25 @@
+"""
+Top-level cross-version primitives for Zarr metadata.
+
+Version-specific types live under `zarr_metadata.v2` and `zarr_metadata.v3`.
+Codec and dtype spec types live under `zarr_metadata.v3.codec` and
+`zarr_metadata.v3.data_type`.
+"""
+
+from collections.abc import Mapping
+from typing import NotRequired
+
+from typing_extensions import TypedDict
+
+
+class NamedConfig(TypedDict):
+    """
+    Externally-tagged union member for a metadata field.
+
+    The `configuration` mapping holds arbitrary JSON-encodable values;
+    it is typed as `Mapping[str, object]` because the type system cannot
+    express or verify JSON-encodability.
+    """
+
+    name: str
+    configuration: NotRequired[Mapping[str, object]]

packages/zarr-metadata/src/zarr_metadata/v2/__init__.py

@@ -0,0 +1,21 @@
+"""Zarr v2 metadata types."""
+
+from zarr_metadata.v2.array import (
+    ArrayDimensionSeparatorV2,
+    ArrayMetadataV2,
+    ArrayOrderV2,
+    DataTypeMetadataV2,
+)
+from zarr_metadata.v2.codec import CodecMetadataV2
+from zarr_metadata.v2.consolidated import ConsolidatedMetadataV2
+from zarr_metadata.v2.group import GroupMetadataV2
+
+__all__ = [
+    "ArrayDimensionSeparatorV2",
+    "ArrayMetadataV2",
+    "ArrayOrderV2",
+    "CodecMetadataV2",
+    "ConsolidatedMetadataV2",
+    "DataTypeMetadataV2",
+    "GroupMetadataV2",
+]