Skip to content

Start convention versioning at v0, not v1, to avoid confusion with SemVer #29

Open

Description

@kylebarron

An initial version of the proj convention is being considered, and there's suggestions to make an initial version of the spatial convention. Offline @maxrjones stated

My intention of the current flurry of effort is to get them all to the candidate maturity

I'm big ➕ 💯 on this effort! I think it will be a great thing (for GeoZarr) to have a versioned release of the underlying conventions!

In relation to the GeoZarr spec (zarr-developers/geozarr-spec#102), which today is comprised of three underlying conventions: spatial, proj and multiscales, my worry is that it would cause more confusion to say "GeoZarr is comprised of these constituent conventions that you can mix together, and these three conventions are all declared to be v1, but GeoZarr is not v1".

In particular, what is the meaning of v1? To me, the badge v1 implicitly suggests that the convention is stable. It suggests that breaking changes are unlikely, or at a minimum will be infrequent. If Zarr conventions do not use semver, I think it should be very explicitly stated that Zarr conventions do not use semver.

Integer versions were decided on previously (see #4, #7, zarr-conventions/multiscales#24), and I don't necessarily have any problem with that.

#4 suggested (cc @normanrz)

To inspire a bit more confidence in the stability of this proposed conventions spec, I would suggest to start at 1.

but I would argue that confidence in a specification's stability comes from the length of time it's had without a breaking change, not just because of the number 1. I think it would be beneficial for conventions to be able to make releases that aren't associated with the implicit promise of stability.

(Personally, I think major.minor would be still useful so that there could be multiple breaking releases before one is declared to be stable, but I don't need to beat a dead horse on that)

Activity

  1. emmanuelmathot commented on May 19, 2026

    @emmanuelmathot
    Contributor

    Thanks @kylebarron for writing this up clearly.

    I've advocated for semver in these conventions before (e.g. zarr-conventions/multiscales#24) and this thread illustrates exactly the problem I was worried about. With semver, we'd have a natural solution: release 0.1.0 now (or 1.0.0-rc.1 to leave time for community feedback), signaling "this is real and usable but not yet declared stable", and reserve 1.0.0 for when we're confident in stability.

    The "start at v0" proposal is a reasonable workaround within integer versioning, but it still leaves us without minor versions and moreover without a programmatic way to manage versioning properly so a breaking change and a non-breaking addition look identical (v0 → v1). With semver, adding optional fields is a minor bump and breaking changes are major, which is exactly the signal implementations need to handle compatibility.

    I'd strongly support revisiting semver before we cut any release. The overhead is minimal, and the clarity it brings to implementers is substantial.

    STAC core spec and extensions uses semver. See @jsignell's comment in zarr-developers/geozarr-spec#102 (comment)

  2. maxrjones commented on May 22, 2026

    @maxrjones
    Contributor

    v1 of the zarr conventions spec has already been released - https://github.com/zarr-conventions/zarr-conventions-spec/releases/tag/v1. I've opened #34 to clarify the meaning of zarr-conventions-spec being v1.

    IIUC your questions here pertain to zarr-developers/geozarr-spec#102 rather than the zarr-conventions-spec.

  3. kylebarron commented on May 26, 2026

    @kylebarron
    Author

    I created the issue here because it seems like this is the common space to talk about recommended behavior across all Zarr conventions. And my issue here is shared across all Zarr conventions, not just GeoZarr-related conventions.

  4. maxrjones commented on May 26, 2026

    @maxrjones
    Contributor

    I created the issue here because it seems like this is the common space to talk about recommended behavior across all Zarr conventions. And my issue here is shared across all Zarr conventions, not just GeoZarr-related conventions.

    thanks for the explanation, I misunderstood your intention based on the reference to the geozarr-spec.

    What do you think about the clarifications in #34 and guidance in https://zarr-conventions.github.io/zarr-conventions-guidance/? The zarr conventions spec is designed to be permissive and there are people who are opposed to evolution via versioning at all (e.g., #7), so I suggested more clear guidance over mandating any one approach.

    a specification's stability comes from the length of time it's had without a breaking change

    this is a good point. it would likely be worth rolling into https://github.com/zarr-conventions#convention-maturity, which currently just mirrors the STAC extension position.

  5. kylebarron commented on May 26, 2026

    @kylebarron
    Author

    there are people who are opposed to evolution via versioning at all (e.g., #7)

    That's not necessarily my read of the discussion. I read that to say their opinion that the version shouldn't be declared in the JSON object. But that's different from saying "there is no version" (such as git tags on the corresponding convention repo)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions