schema version for documentation updates

[crotwell]

Current schema is 1.1. If the recommendation to the WG is a "documentation only" update, what should the version be?

Because we do not want to overwrite the existing schema file, it will need to be different from 1.1.

Options include:
1.2
1.1.1

[crotwell]

Comment from @chad-iris

Definitely think there should be a version bump. It's a new release and we can't re-release a version.

More rationale: for a schema, the inline documentation is a key part of the definition of the fields. So major changes to the documentation, as we have here, deserve a new version and therefore separation. At a minimum we need to be able to point at a release and say the fields mean "this" without confusion of which description it is. Plus also comparison with older versions as you write.

I vote for 1.2. Mostly for simplicity, but I would argue the documentation are relatively significant, more so than with software, as they can change how creators/consumers interpret the values, and this is a big update.

[rcasey-earthscope]

If we go this direction, bringing the Docs plus schema to v1.2, does this couple the releases together? I haven't seen yet whether the changes to the documentation have structurally changed anything, but if it has, then I guess the answer is yes. As I pointed out to Philip during our call, we went through three or four editions of the SEED Manual for v2.4 and never changed the specification version. In hindsight, we it have been better that we had released a v2.5...2.6....etc, with each edition?

…

On Jan 20, 2022, at 7:48 AM, Philip Crotwell ***@***.***> wrote: Comment from @chad-iris <https://github.com/chad-iris> Definitely think there should be a version bump. It's a new release and we can't re-release a version. More rationale: for a schema, the inline documentation is a key part of the definition of the fields. So major changes to the documentation, as we have here, deserve a new version and therefore separation. At a minimum we need to be able to point at a release and say the fields mean "this" without confusion of which description it is. Plus also comparison with older versions as you write. I vote for 1.2. Mostly for simplicity, but I would argue the documentation are relatively significant, more so than with software, as they can change how creators/consumers interpret the values, and this is a big update. — Reply to this email directly, view it on GitHub <#112 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFL4VNYAJL6E3BGGCATO57TUXAVGVANCNFSM5MNDMUEA>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you are subscribed to this thread.

[crotwell]

To answer your question, @rcasey-iris , current changes to docs, (ie the current doc_issues branch) make no structural changes to schema "as a schema" but the file itself has changed. See the script in auditDocUpdate directory on the doc_issues branch that verifies this by stripping out all annotations and comparing the current and previous schema files.

Just to be clear by stating the obvious, the documentation changes do change the actual schema file. They are not contained only in separate documentation files.

We should not overwrite the current file on the FDSN website:
http://www.fdsn.org/xml/station/fdsn-station-1.1.xsd
It should remain at a minimum so that others can verify that there were no structural changes.

There is also a potential for software that uses the current 1.1 schema file to break on the new <xs:annotation> elements within the file. That shouldn't happen for a properly written code, but I don't think we can be 100% positive about it, so again don't overwrite that link.

One other point to consider is that we must adhere to the existing compatibility requirement, see
http://www.fdsn.org/xml/station/
where it says:

The targetNamespace of the document identifies the major version of the schema and document, version 1.x of the schema uses a target namespace of http://www.fdsn.org/xml/station/1. All minor versions of a will be backwards compatible with previous minor releases. For example, all 1.x schemas are backwards compatible with and will validate documents for 1.0. Major changes to the schema that would break backwards compatibility will increment the major version number, e.g. 2.0, and the namespace, e.g. http://www.fdsn.org/xml/station/2.

My take on this is that "1" defines compatibility, so it doesn't matter much what we call it as long as it is "1 dot something".

Lastly, while I don't really have strong feelings about a 1.1.1 vs. 1.2, we are unlikely to run out of numbers. I don't foresee there ever being another revision of the 1.x branch if we create a 2.0 branch.

[crotwell]

Useful reference:
https://semver.org/

[crotwell]

I have updated the version in the schema and doc conf.py to be 1.1.1-alpha on the doc_issues branch just as a placeholder until this issue is decided.

[PetrColinSky]

As discussed already, I think there should be a version change. Based on the link by @crotwell at semver.org it looks like 1.1.1 is our case for documentation-changes only. Even I like 1.2 more for simplicity. However, there was also an opinion by @javiquinte not to change anything.

[crotwell]

In thinking more, there are two issues here:

1. What to name the documentation release?
2. What should go into the schemaVersion attribute on the top level FDSNStationXML element?

Normally, those would be the same, but since we are making no structural schema changes, just adding documentation and annotations, maybe the answer to 1) is to give the new release a new version number, but for 2) recommend that all services generating stationxml continue to use schemaVersion="1.1".

That way the update has a different name, the docs are available, but no software that produces or consumes stationxml needs to change. And as the schema structure is the same, validating against either version yields the same result.

[chad-earthscope]

maybe the answer to 1) is to give the new release a new version number, but for 2) recommend that all services generating stationxml continue to use schemaVersion="1.1".

(I use 1.2 as the "next" doc version, could be 1.1.1 also)

I wouldn't go so far as to recommend to continue generating "1.1", instead how about recommending that usage be updated to generate "1.2" at a time of next opportunity, which producers should be able to do easily with the knowledge that the structure hasn't changed. Software readers that break on a change from 1.1 to 1.2 need to be addressed anyway, as they are then not forwards compatible as intended with minor versions.

We'll have two published schemas, with different definitions for some fields. For the same field, the older definition might be vague or non-existent, where the newer should hopefully be much more clear. One could create a 1.1 document and claim it is valid according to the documentation, even though it does not follow the 1.2 definition. It's a precarious position to say create 1.1 but the definition of the fields is in 1.2; I recommend avoiding this, allowing it to be minimized in a transition period.

[chad-earthscope]

Also, not radically different than SemVer for this purpose, but subtly different is schema versioning, Schema Versioning: https://snowplowanalytics.com/blog/2014/05/13/introducing-schemaver-for-semantic-versioning-of-schemas/#schemaver

[crotwell]

Discussion in meeting, consensus was to go with 1.1.1

[crotwell]

Problem, the schema defines the schemaVersion attribute as "decimal", so if you try:

<FDSNStationXML xmlns="http://www.fdsn.org/xml/station/1" schemaVersion="1.1.1">

you get a validation error:

ERROR : Ln 2,Col 81 : cvc-datatype-valid.1.2.1: '1.1.1' is not a valid value for 'decimal'.
ERROR : Ln 2,Col 81 : cvc-attribute.3: The value '1.1.1' of attribute 'schemaVersion' on element 'FDSNStationXML' is not valid with respect to its type, 'decimal'.

So 1.1.1 will break the schema file. Shall we go with 1.2?

[PetrColinSky]

I am on to go with 1.2.

[rcasey-earthscope]

There is a sort of meta-irony to this schema limitation to how we can specify an upgrade to this same schema, but 1.2 is fine, given the current constraints. -Rob

…

On Feb 22, 2022, at 12:47 AM, Petr Kolínský ***@***.***> wrote: I am on to go with 1.2. — Reply to this email directly, view it on GitHub <#112 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFL4VN7GYADOYP57FVNJTADU4NERBANCNFSM5MNDMUEA>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.

[jschaeff]

OK for 1.2 then. I hope it will not bring too much confusion in the community.

And let's file a bug for the XSD attribute on schemaVersion :)

[crotwell]

I think I have updated all version references to be 1.2 in PR #148