Do we need to include a version number?

[letmaik]

Like "version": "1"? This would only increase for backwards incompatible changes to the spec (and there would have to be very good reasons for those). What happens to the media type in that case? Should that change as well then? If not, how could clients request an old version if the server wants to offer multiple versions?

[jonblower]

I don't know how this is generally handled. It might be worth looking to see, for example, whether there are different media types for GML versions, or NetCDF versions. However, my first thought would be to say that the media type shouldn't change. Version negotiation might have to happen at the API level, unless media type parameters play a role here?

CF has a strict backwards-compatibility rule, although I guess this could change for a future major upgrade. But it provides dot releases (1.5, 1.6, 1.7 etc) when new functionality is added that doesn't break backward compatibility. We could do the same. Old clients can still read the files, but may not be able to fully understand some of the metadata.

[letmaik]

I think the best way would be to include a statement in the spec saying that there is an implicit "version": 1 field if no "version" field exists, and for the version 1 case this field must not be included, but if that field is included then it must be >= 2 and clients that don't support that higher version must stop processing since it is a new major version with backwards-incompatible changes. For backwards-compatible changes, there would be no new version, just a change in the spec, and the spec could have a minor version itself, like 1.1, but this is not stored in the JSON, only the major one. This should cover all cases, right? Also the version field would be of number type, so no need for clients to do string parsing with "major.minor" for example.

[jonblower]

This sounds reasonable to me (although I don't see why we would forbid the inclusion of "version=1" - it doesn't seem to do any harm).

This must be a general issue for which there is probably a best practice - or maybe not?

[letmaik]

Generally, it is not common to include version numbers in JSON formats, the idea being that you will not break your format anyway. And if you do, then it is a new format with new media type etc. That's why I'm leaning towards omitting the version number but leaving the door open if we should need it in the future, but the aim would be to always try being backwards-compatible. Apart from that, you save some bytes, for the case that there will not actually be a version 2 with the same media type.

[jonblower]

OK, so if we made breaking changes we would probably freeze v1 and define a new CoverageJSONv2 with a new media type? Makes sense to me.

[letmaik]

Yes, I think so, gives also more confidence to people that nothing will break and they will have to worry less.