Feedback is very welcome on about this framework for Zarr Conventions. Please join the discussion on V1 of the Zarr Conventions Framework.
This organisation contains documentation and tooling to help define and share Zarr Adoption Conventions.
A Zarr Adoption Convention (Zarr convention, for short) is simply a way of using Zarr to store data for a particular domain, application or purpose. For example, a Zarr Convention can define a set of attributes for storing specific metadata that helps downstream applications provide special behaviour and users interpret the data.
To define and share your own convention:
- Create a new GitHub repo using the zarr-conventions template
- Create a UUID to use as a globally-unique identifier for your convention.
- Edit the README.md in your repo to describe your usage convention for developers and users.
- Edit or remove the schema.json file in your repo to define validation constraints on your metadata.
- Commit your changes and make a GitHub release so you have a stable version of your spec and schema to point to.
- Share your convention with the community (see below).
We have adapted the maturity classification system used by the STAC ecosystem. There are many conventions being built with Zarr, but they have varying degrees of maturity. All community conventions listed here included must include a maturity classification, so that Zarr conventions users can easily get a sense of how much they can count on the convention. Currently, it's recommended that convention developers self-assess the maturity in their README. We may evolve to a more centralized maturity assignment process in the future.
| Maturity Classification | Min Impl # | Description | Stability |
|---|---|---|---|
| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. |
| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more libraries. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback. |
| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid convention. User can generally count on an convention at this maturity level. | Mostly stable, breaking changes require a new version and minor changes are unlikely. The convention has a code owner, designated in its README. |
| Stable | 6 | Highest current level of maturity. The community of convention maintainers commits to a Zarr review process for any changes, which are not made lightly. The process for this review will be established in 2026. | Completely stable, all changes require a new version number and review process. |
| Deprecated | N/A | A previous convention that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported |
Maturity mostly comes through diverse implementations, so the minimum number of implementations column is the main gating function for an convention to mature. But convention authors can also choose to hold back the maturity advancement if they don't feel they are yet ready to commit to the less breaking changes of the next level.
If you have published a Zarr convention, please add it to the table below:
| Name | Description | UUID | Repository |
|---|---|---|---|
| proj | Coordinate reference system information for geospatial data | f17cb550-5864-4468-aeb7-f3180cfb622f | https://github.com/zarr-conventions/proj |
| spatial | Spatial coordinate information | 689b58e2-cf7b-45e0-9fff-9cfc0883d6b4 | https://github.com/zarr-conventions/spatial |
| multiscales | Multiscale layout of zarr datasets | d35379db-88df-4056-af3a-620245f8e347 | https://github.com/zarr-conventions/multiscales |
| license | License specifier for Zarr data | b77365e5-2b0c-4141-b917-c03b7c68e935 | https://github.com/clbarnes/zarr-convention-license |
| uom | Units of measurement for Zarr arrays | 3bbe438d-df37-49fe-8e2b-739296d46dfb | https://github.com/clbarnes/zarr-convention-uom |
| ref | Referencing external objects from a Zarr array or group | d89b30cf-ed8c-43d5-9a16-b492f0cd8786 | https://github.com/R-CF/zarr_convention_ref |
| nz | NetCDF - Zarr Convention | d0a980b5-c644-4dcc-85a1-283799a58f40 | https://github.com/zarr-conventions/nz |
| geolocation | Convention for storing geolocation arrays | bb9ee930-8c60-4c47-ad6b-8daa558987ed | https://github.com/R-CF/zarr_convention_geolocation |
| cs | Coordinate set for n-dimensional arrays | e4dbf0b7-7a00-4ce6-b23e-484292014ab4 | https://github.com/R-CF/zarr_conventions_cs |
| coords | Index-to-coordinate mapping | 6ca4454a-658a-4348-a667-b39ced0e58cb | https://github.com/christophenoel/zarr-coords |
| cf | CF semantic metadata | 0c0a02d2-8a95-4303-8b62-16a50b439d74 | https://github.com/christophenoel/zarr-cf |
| dggs | Discrete Global Grid Systems | 7b255807-140c-42ca-97f6-7a1cfecdbc38 | https://github.com/zarr-conventions/dggs |