Zarr coords Convention

The coords Zarr convention provides a lightweight, domain-agnostic way to map array dimensions to coordinate descriptions. The convention does not try to replace existing models such as CF, spatial metadata, CRS definitions, or multiscale pyramids. Instead, it focuses on one clear responsibility: describing where coordinate values come from and how each array axis should be routed to them.

This makes coords useful beyond geospatial data. The same mechanism can describe temporal, spectral, vertical, categorical, image, signal-processing, scientific, or domain-specific coordinates. It can also compose with other conventions when richer semantics are needed.

Reference: https://github.com/christophenoel/zarr-coords

In this post, we introduce the main ideas behind the coords convention, explain how coords:coordinates works, and show how it fits with group-level metadata, coordinate descriptor types, spatial references, and multiscale datasets.

Domain-Agnostic Coordinate Semantics

Coordinates are not inherently spatial. Time stamps, wavelengths, pressure levels, manufacturing positions, financial maturities, image pixels, and many other concepts are all examples of coordinates. The goal of the coords convention is to provide a single, consistent mechanism for describing the meaning of array dimensions, regardless of domain. Rather than defining new metadata structures for every discipline, coords maps array axes to coordinate descriptions using a common, domain-agnostic model.

Composable with Other Conventions

The convention is intentionally lightweight and focused on a single responsibility: connecting dimensions to coordinate descriptions. It does not attempt to replace existing conventions. Instead, it complements them by acting as a routing layer. Coordinate descriptors may reference conventions such as spatial, while semantic metadata can still come from CF and multi-resolution structures from multiscales. This composable approach keeps conventions independent while allowing them to work together seamlessly.

The coords:coordinates Property

At the core of the convention is the coords:coordinates property. It provides a mapping between Zarr v3 dimension_names and coordinate descriptors. Keys correspond to dimension names, or to tuples of dimensions for multi-dimensional coordinates, while values describe how coordinates should be interpreted. This simple structure makes coordinate discovery predictable for readers while remaining flexible enough to support many coordinate representations.

Coordinate Inheritance

Many datasets contain multiple variables that share the same coordinate system. To avoid duplication, coordinate definitions can be declared once at the group level and inherited by child arrays. Individual arrays may still override inherited definitions when necessary. This inheritance model reduces metadata repetition while preserving flexibility for specialised cases.

Coordinate Descriptor Types

Different coordinate representations require different levels of complexity. The convention therefore defines a small set of descriptor shapes covering common use cases, from explicit coordinate arrays and inline values to regularly spaced coordinates and references to external conventions. Together, these descriptor types provide a uniform framework capable of describing both simple and advanced coordinate systems.

A Complete Array Node

This example shows how the different pieces fit together within a Zarr array. The array declares its dimensions through dimension_names, while coords:coordinates links each dimension to a coordinate descriptor. Some coordinates may be represented explicitly as arrays, while others may delegate their interpretation to another convention such as spatial. The result is a clear separation between array structure and coordinate semantics.

Relationship with the Multiscales Convention

The coords and multiscales conventions solve different problems and therefore compose naturally. multiscales describes how data is resampled between pyramid levels, while coords describes how coordinates are interpreted within each level. Because both conventions are domain-agnostic, a pyramid can downsample temporal, spectral, vertical, or spatial dimensions, and each level can independently describe its coordinates using the same coords mechanisms.

And Now for the Sales Pitch…

The design of coords is intentionally pragmatic. It is simple to implement, independent of any particular scientific domain, compatible with existing conventions, and flexible enough to cover the majority of real-world coordinate use cases. By focusing on interoperability rather than reinvention, it provides a lightweight foundation that can evolve alongside the broader Zarr ecosystem.