zarr-cm

Python types and utilities for Zarr Conventions Metadata.

Overview

zarr-cm provides typed Python support for the published Zarr conventions:

Each module provides:

• TypedDict types for convention-specific metadata
• create — create convention metadata: the convention's own keys, nothing else
• create_convention_attrs — create a complete stand-alone attributes dict: that data plus the zarr_conventions entry declaring it
• insert — compose: add convention metadata to attributes that already exist
• extract — remove and return convention metadata from an attributes dict
• validate — check runtime invariants the type system cannot express
• validate_group_metadata / validate_array_metadata / validate_node_metadata — validate a whole zarr.json document, including the rules that depend on its node_type

See the docs for more information.

Installation

pip install zarr-cm

Usage

from zarr_cm import proj

# Create convention metadata
data = proj.create(code="EPSG:4326")
print(data)
#> {'proj:code': 'EPSG:4326'}

# Validate
print(proj.validate({"proj:code": "EPSG:4326"}))
#> {'proj:code': 'EPSG:4326'}

# Insert into an attributes dict
attrs = {"foo": "bar"}
result = proj.insert(attrs, data)
print(result)
"""
{
    'foo': 'bar',
    'proj:code': 'EPSG:4326',
    'zarr_conventions': [
        {
            'uuid': 'f17cb550-5864-4468-aeb7-f3180cfb622f',
            'schema_url': 'https://raw.githubusercontent.com/zarr-conventions/proj/refs/tags/v0.1/schema.json',
            'spec_url': 'https://github.com/zarr-conventions/proj/blob/v0.1/README.md',
            'name': 'proj',
            'description': 'Coordinate reference system information for geospatial data',
        }
    ],
}
"""

# Extract it back out
remaining, extracted = proj.extract(result)
print(remaining)
#> {'foo': 'bar'}
print(extracted)
#> {'proj:code': 'EPSG:4326'}

Convention revisions

Upstream Zarr conventions sometimes change their field shapes in place — keeping the same uuid but altering required keys and cardinalities. To let you both author data at the current spec and still read data written against an earlier draft, the revisioned conventions (spatial, proj, multiscales) expose package-local revision labels ordered oldest → newest. Today spatial and proj ship r2 and r3, while multiscales ships only r2; more are added as upstream conventions evolve.

Each revision pins its emitted schema_url/spec_url to an immutable upstream reference — the release tag where one exists (v0.1 for the latest revisions), otherwise the commit SHA it was snapshotted from — so a written document is self-describing: the uuid says which convention, and the pinned schema_url says which revision. Writes default to the latest revision; reads auto-detect the revision from the document's schema_url (overridable with a revision= argument).

Why there is no r1

The revision labels start at r2, not r1. Earlier drafts of spatial, proj, and multiscales did exist, but the only schema_url they could carry was upstream's refs/tags/v1/schema.json — and that tag was never published on any of these repositories (their first and only release tag is v0.1). That URL has therefore always returned 404, which is non-conformant with the Zarr Conventions spec's requirement that schema_url resolve to the convention's schema. For multiscales the draft was worse than dangling: its schema const-requires the refs/tags/v1 URL, so no schema_url value could both resolve and validate.

Rather than ship a revision whose self-describing URL is permanently broken, r1 was dropped from all three conventions. The surviving revisions keep their r2/r3 labels (labels are package-local and never appear in emitted documents, so renumbering would only churn the public type names without changing behavior).

Development

Common development tasks are defined in the justfile and run with just (they only need uv on top of that):

just            # list all the available recipes
just test       # run the test suite
just lint       # run the pre-commit hooks over all files
just typecheck  # run mypy
just docs       # serve the docs locally with live reload
just check      # everything CI runs: lint, pylint, typecheck, tests