Contributing Guide

This guide is a draft under construction.

1. Review the roadmap

Familiarize yourself with current priorities and open work items before proposing changes:

• V1 Roadmap

The conventions themselves are developed in their own repositories:

Convention	Repo
proj	zarr-conventions/proj
spatial	zarr-conventions/spatial
multiscales	zarr-conventions/multiscales

The Editor’s Draft is the formal OGC spec document. It may lag behind the convention repos as it is updated periodically.

2. Understand GeoZarr objectives

GeoZarr does not define a new data model. The work focuses on concrete and thematic Zarr conventions that address specific community needs. Each convention provides a clear and self-contained extension for a defined topic and supports practical adoption.

3. Scope and workflow for changes

• Avoid modifying multiple sections at once.
• Propose initial changes in a focused section.
• Use GitHub issues for discussion before drafting large updates.
• Create a branch in the main repository for visible collaborative work.

4. Participation

The GeoZarr SWG allows non-OGC members to participate in the development of the Standard in this collaboration environment, per OGC TC Policy §4.13.7. As required by OGC, non-member participation does not grant OGC Portal access or SWG voting rights.

• All community members are encouraged to comment on issues, review pull requests, and propose changes.
• Monthly OGC GeoZarr SWG meetings focus on strategic discussion and topics lacking consensus.
• Example datasets can be contributed to https://github.com/developmentseed/geozarr-examples.

5. Maintenance structure

Review and merge authority

Anyone may review and comment on pull requests. Only OGC GeoZarr SWG chairs (or OGC voting members they delegate to) may merge pull requests, ensuring the collaboration environment remains under OGC control per TC Policy.

The maintenance team manages repository access. Requests to join may be made as a post on the OGC Agora General Space or at an OGC GeoZarr Monthly meeting.

Voting

For contested matters, only SWG voting members may cast formal votes. Voting membership is defined by the OGC TC Policies and Procedures (Charter Members, or members who have opted in, completed the 30-day waiting period, and requested voting status).

Pull request process

• PRs are reviewed asynchronously on GitHub and merged by SWG chairs.
• Rough consensus (per IETF RFC 7282) is required for merge; the SWG chair determines when consensus has been reached.
• If consensus cannot be reached on GitHub, the topic should be raised at the next SWG meeting for discussion.
• If consensus still cannot be reached, an OGC formal vote may be initiated per the TC voting procedures.

6. Implementation criteria for Candidate maturity

The Zarr Conventions Framework requires a minimum of 3 implementations for Candidate maturity. This section defines additional criteria to ensure those implementations represent genuine, independent validation of the conventions. These criteria are consistent with the OGC definition of evidence of implementation for Encoding Standards, which is "data sets containing content representative of the Standard, but not necessarily containing an example of every element in the Standard" (OGC TC Policies and Procedures §8.2.1).

Definitions

An implementation is a software library, tool, or application that reads or writes Zarr data conforming to one or more GeoZarr conventions (proj, spatial, multiscales).

A qualifying implementation is one that meets all of the criteria below.

Independence

Qualifying implementations MUST originate from different organizations or development teams. Two implementations that completely share development effort, funding, or leadership from the same organization count as one for maturity purposes.

Independence ensures that conventions are interpretable from the specification alone, without relying on shared institutional knowledge.

Convention coverage

Each qualifying implementation MUST support at least one complete GeoZarr convention (proj, spatial, or multiscales), including all required fields defined by the convention's JSON Schema.

Partial support does not count toward the 3-implementation threshold for that convention.

Capability level

Implementations MUST declare their capability level for each supported convention:

Level	Description
Read	Can parse and interpret convention metadata from existing Zarr stores
Write	Can produce valid convention metadata in new or existing Zarr stores
Full	Both read and write

For each convention, the 3 qualifying implementations MUST include at least two independent Write-capable (Write or Full) implementations and at least one independent Read-capable (Read or Full) implementation. Two independent writers demonstrate that the specification text — not shared implementation code — constrains the metadata that is produced, and a separate reader demonstrates that this output is interoperable. A set of implementations that is read-only, or that contains only a single writer, cannot be the basis for advancement.

Demonstrated interoperability

Each qualifying implementation MUST successfully read or write at least one dataset from the conformance test suite (once available). Collectively, the qualifying implementations for each convention MUST demonstrate at least one successful round trip: a dataset written by one implementation and read by a different, independent implementation.

Release status

Convention support MUST be included in a released version of the implementation. Unreleased support (e.g., only available on a development branch or in a pre-release) does not count toward the 3-implementation threshold.

Documentation

Each qualifying implementation MUST provide:

• Public source code or a public release
• Documentation or examples showing how convention metadata is read or written
• A link to the convention version supported

Dataset diversity (recommended)

It is RECOMMENDED that qualifying implementations collectively demonstrate support for datasets from multiple domains (e.g., earth observation, climate, oceanography) and multiple storage backends (e.g., local filesystem, S3, GCS, Azure).

Counting

The 3-implementation minimum applies per convention. A convention advances to Candidate only when it has 3 qualifying implementations for that specific convention. An implementation supporting all three conventions counts toward each.

Qualifying implementations are tracked in the implementation matrix. The SWG chair determines when an implementation qualifies, subject to the consensus process described in §5.

7. Versioning and releases

7. Versioning and releases

7.1 How conventions are versioned

Each constituent convention (proj, spatial, multiscales, and any future GeoZarr conventions) is versioned in its own repository and released via git tags, tied to its maturity level in the Zarr Conventions Framework. Every release publishes an immutable, versioned artifact: the specification text and JSON Schema for version X.Y are addressable at a URL that embeds the version and whose content never changes after release. Normative references MUST point at a versioned artifact, never at main, latest, or another mutable target. This applies to references in data, in tooling, and in the GeoZarr specification.

A convention's identity and its version are separate axes:

• The UUID identifies the convention itself. It is permanent and MUST NOT change across versions. If all URLs were lost, the UUID plus the conventions registry would still resolve data to the correct specification.
• The version identifies a specific released contract of that convention.

The semantics of the zarr_conventions attribute are framework-level policy: how versions are carried in Zarr metadata, the rule that each declaration is self-contained (one convention at one version, via the versioned spec/schema URL alongside the UUID), and how declarations compose and resolve across a hierarchy. These semantics are defined in the Zarr Conventions Framework specification, not in this document, so that it applies uniformly to all conventions, geospatial or not. The operative consequences for GeoZarr: there is no store-wide or hierarchy-wide convention version attribute, and each declaration resolves independently at the node where it applies, so different nodes may reference different conventions without conflict.

7.2 Release expectations by maturity

• A convention SHOULD tag a pre-stable release (e.g. v0.x) once it reaches Pilot maturity (examples, a JSON Schema, and at least one implementation).
• A convention SHOULD release an initial stable version once it reaches Candidate maturity, as defined by the implementation criteria in §6.

7.3 Permanence of released versions

Once released, a convention version is permanently published:

• Every released version remains resolvable at its versioned URL indefinitely, regardless of the convention's current maturity, the existence of newer versions, or whether the GeoZarr specification still recommends it.
• Deprecation is a status, never a removal. A deprecated or superseded version is marked as such, with a pointer to its successor, but its text and schema remain available so that data written against it decades ago remains interpretable.
• A later change in what the GeoZarr specification recommends affects only what newly written data should do. It has no effect on the validity or interpretability of existing data, which remains valid against the convention version it declares, permanently.

To make this durable beyond any single hosting platform, each stable release SHOULD additionally be archived in a platform-independent location (for example, a snapshot on a project-controlled domain, a Zenodo DOI, or Software Heritage), and the conventions registry maintains the permanent UUID → versions mapping as the layer of last resort.

7.4 Out of scope (tracked in #102)

• The version-numbering scheme for conventions and for GeoZarr (integer vs. major.minor vs. Semantic Versioning), including reader/writer compatibility rules such as tolerance of unrecognized members. This is framework-level policy and should be defined once in zarr-conventions-spec (see zarr-conventions-spec#29) so that validators and tooling resolve versions uniformly across all conventions, rather than per convention or in this document.
• How the GeoZarr specification references and versions against its constituent conventions (follow-up PR).
• The release gate for a stable GeoZarr release and its sequencing with the OGC process (follow-up PR).

8. Roadmap

Work should follow the priorities defined in the roadmap: https://geozarr.org/roadmap.html