Versioning and relaying revision information for non breaking changes

[Hubert-Heijkers]

I'm in a situation where, like most software I suppose, we end up supporting an LTSR version (the last one of the previous major version in our case - we follow semantic versioning) and the latest and greatest generation of product. Whilst we don't like doing this we occasionally end up 'back-porting' a capability, an improvement, in our API where, if one were to think about schema version as being linear, there would be a gab in which that capability does not exist.

Looking at section 5.2 Model Versioning of our Protocol specification that by itself is allowed as whenever we add something we do update the @Core.SchemaVersion accordingly.

All our additions are safe, and we don't implement $schemaversion system query option, we merely included/updated @Core.SchemaVersion to be able to use the @Core.Revisions annotation to make them aware in which version such element got introduced.

Given the above situation my first question was, would it be allowed to have multiple revisions that specify in which version the model element got added as in:

		"CheckFeedersSelection": {
			"$Kind": "EnumType",
			"$IsFlags": true,
			"@Core.Revisions": [
				{
					"Version": "11.8.32",
					"Kind": "Added"
				},
				{
					"Version": "12.5.2",
					"Kind": "Added"
				}
			],
			"Unfed": 1,
			"Fed": 2,
			"Both": 3
		},

But having reacquainted myself with model versioning a bit I wonder if I should have gone for my own Version and Revision like annotation to relay this information in the case where I'm not, ever, breaking existing clients. We don't seem to have a way to do this in our current specification it seems as, the way I read it, @Core.SchemaVersion kind of implies you might/would be breaking existing clients, hence the requirement to support $SchemaVersion system query option.

[mikepizzo]

1. Propose rewording 5.2 of [Protocol] from "Services that version their metadata" to: "Services that make breaking changes to their metadata exposed through an existing service root..."
2. We should add (to the vocabulary term) that an element may have multiple Added/Deprecated revisions to signify adding to multiple supported major versions of the service.

[mikepizzo]

Resolved as proposed 2025/7/9.