Repository navigation
Consistent versioning strategy for GeoZarr conventions #102
Description
Summary
#101 Established that the first release of GeoZarr will be comprised of a set of initial Zarr conventions (e.g., multiscales, spatial:, proj:).
To ensure a coherent ecosystem and reduce implementation burden, we should align on a consistent versioning strategy across all conventions that comprise GeoZarr.
Background
Recent discussions across the zarr-conventions organization have explored versioning approaches for specifications:
- Start at version 1 and integer versions zarr-conventions/zarr-conventions-spec#4: Established that the zarr-conventions-spec should use integer versions (rather than semantic versioning) starting at version 1, aligning with the existing
zarr_formatpattern. - How should implementations use the version number of an individual attribute? zarr-conventions/zarr-conventions-spec#7: Explored how implementations should use version numbers. The resolution allows — but does not require — versioning through schema URLs or convention attributes, leaving individual conventions to define their own strategies.
- Release v1.0.0 zarr-conventions/multiscales#24: Proposes moving multiscales from
v1tov1.0.0semantic versioning, which diverges from the integer versioning approach adopted by zarr-conventions-spec.
Key Considerations
Integer vs. Semantic Versioning
For specifications (as opposed to software libraries), semantic versioning (major.minor.patch) may create unnecessary burden on implementers.
Consistency Across Conventions
If different conventions within GeoZarr use different versioning schemes (e.g., multiscales using v1.0.0 while others use v1 and others do not use versioning), this could:
- Confuse implementers about version compatibility semantics
- Create inconsistent patterns in zarr metadata
- Complicate tooling that needs to parse and validate version strings
Implementer Burden
Large geospatial data catalogs are expensive to update. A versioning strategy should:
- Signal meaningful changes that require action
- Allow forward compatibility where possible (e.g., new optional fields)
- Avoid requiring catalog-wide updates for non-breaking changes
Proposal
GeoZarr should establish a recommendation for consistent versioning across its constituent conventions:
- Adopt integer versioning (e.g.,
v1,v2) for all Zarr Conventions comprising GeoZarr, aligning with zarr-conventions-spec andzarr_format - Start at version 1 to signal stability and production-readiness
- Increment versions only for breaking changes that require implementation updates
- Use GitHub releases for tracking non-breaking updates (documentation, clarifications, optional field additions) without incrementing the convention version
- Allow updating schemas for versions that do not include breaking changes - This would mean not using tagged release files as the published schema.
Breaking Changes (Require Version Increment)
- Removing required properties
- Changing property semantics incompatibly
- Changing JSON Schema in ways that invalidate previously valid data
- Removing conformance classes
Non-Breaking Changes (No Version Increment)
- Adding new optional properties
- Adding new conformance classes
- Extending allowed values (e.g., new transform types)
- Adding new conventions
- Documentation clarifications and bug fixes
Alternatives
- SemVer (STAC-style): Full major.minor.patch versioning
- No versioning (GeoJSON-style): Breaking changes mean the data do not actually follow the conventions
- Major + minor only (CF-style): Use only major and minor version numbers in metadata
Convention UUID Stability
- UUIDs are permanent identifiers and MUST NOT change across versions
- UUID identifies the convention, not the version
- Version is tracked separately (via schema URL, convention attribute, or other mechanism per How should implementations use the version number of an individual attribute? zarr-conventions/zarr-conventions-spec#7)
Deprecation Policy
- Features deprecated in version N
- Deprecation warning documented in version N
- Removal allowed in version N+1
- Minimum 12 months between deprecation and removal
Relationship to Convention Maturity
The Zarr Conventions Framework defines maturity levels that interact with versioning:
| Maturity | Stability Expectation |
|---|---|
| Proposal | Breaking changes expected |
| Pilot | Breaking changes not anticipated but possible |
| Candidate | Breaking changes require new version |
| Stable | All changes require new version and review process |
Version stability commitments should align with maturity level.
Questions for Discussion
- Should GeoZarr mandate a versioning approach for its constituent conventions, or provide a recommendation?
- Should each convention have independent versions, or one unified version?
- How do we version the composition of conventions?
- What is the support timeline for older versions?
Dependencies
None
References
- Release v1.0.0 zarr-conventions/multiscales#24
- How should implementations use the version number of an individual attribute? zarr-conventions/zarr-conventions-spec#7
- Start at version 1 and integer versions zarr-conventions/zarr-conventions-spec#4
- Zarr Conventions Framework
- Discussion on V1 of the Zarr Conventions Framework
- Semantic Versioning 2.0.0: https://semver.org/
- OGC standard versioning practices
Activity
[-]Consistent versioning approaches across Zarr Conventions comprising GeoZarr[/-][+]Consistent versioning strategy for GeoZarr conventions[/+]jsignell commentedon Apr 7, 2026
In case it's helpful in the discussions: When implementing STAC Extensions in tools it is really useful to be able to derive meaning from SemVer. In practice a lot of extensions start at
1.0.0, so there's not always a ton of meaning in that one, but the difference betweenv1.0.0andv1.1.0as opposed tov2.0.0is meaningful. An implementation that was written orv1.0.0would maybe not have special handling for a field onv1.1.0but it wouldn't raise an error. The same promise would not apply if you pass av2.0.0object. So I guess with SemVer it's easier to communicate expectations about what version of a STAC extension is supported by a particular tool.Also recently in pystac, we switched to having a python package per STAC extension and the version of those packages matches the version of the STAC extension itself. This is super new, but we are excited about its potential to make the relationship between spec version and implementation version way more explicit.
emmanuelmathot commentedon May 19, 2026
+1 to @jsignell's point. The graceful degradation behavior you describe ( an implementation written for
v1.0.0not erroring onv1.1.0but correctly refusingv2.0.0) is exactly what you want from a geospatial metadata convention. That contract is only expressible with semver; integer versions can't make that promise.The spec-to-package version alignment you mention in pystac is also a compelling model worth considering for GeoZarr tooling down the line.
cc @kylebarron
maxrjones commentedon May 22, 2026
I had Claude assess the changes associated with version bumps across 6 specs in https://zarr-conventions.github.io/zarr-conventions-guidance/posts/2026-survey.
A couple things stood out to me:
x.y.zrelative to justx.y.I think that the Cargo / Rust-style pre-1.0 variant matches our needs best:
I'll acknowledge the tradeoff that reaching a stable v1 under cargo-style would likely take longer because the bar for stability is higher than under EffVer (no breaking changed allowed in minor releases after v1). I think a high bar is a good thing.
Independent of that opinion, we could immediately label the multiscales, proj, and spatial conventions as v0.1 and publish a release. That is orthogonal to voting on how to do versioning long-term at a SWG meeting.
kylebarron commentedon May 22, 2026
I think starting conventions at v0.1 is a low-risk way to start publishing.