revise compatibility requirements

[crotwell]

See: http://www.fdsn.org/xml/station/

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.

It is not clear to me if this is sufficient for what is actually needed for "backwards compatibility". Validation across versions may be less important than if software written to use a 1.x version can be expected to parse a 1.y document without breaking. If that is important, then removing elements is ok, but adding them is not. This is opposite of the statement that

all 1.x schemas ... will validate documents for 1.0.

and so perhaps should be

the 1.0 schema ... will validate documents for 1.x.

I am not sure I am clear on how best to handle this, but I feel like schema backwards compatibility and document backwards compatibility kind of point in opposite directions.

Whatever is decided, should add a section to documentation overview.rst stating this, so it lives with the schema and not just only on the fdsn web site.

[PetrColinSky]

I see your concern and agree with it. It looks like a more general issue probably expected in other code development as well. Once there is any schema change applied, there needs to be a clear statement, what schema can validate which document (whatever we call it). To me, it is not that important what happens, but more important is to have a clear message about it directly in the schema, as you @crotwell suggest.

[crotwell]

@chad-iris in #112 pointed to https://snowplowanalytics.com/blog/2014/05/13/introducing-schemaver-for-semantic-versioning-of-schemas/#schemaver

which might be useful for how to make the documentation more clear.

[jschaeff]

From this interesting post pointed by @chad-iris , we could derive some rule in order to clarify the schema evolution/incompatibilities:

The schema format is M-R-A. 3 digits strictly > 0.

• A stands for ADDITION. Increment when the model changes should not break any compatibility with historical stationxML files (having the same M and R, and inferior A)
• R stands for REVISION. Increment when the model changes may break interaction with historical stationXML files (same M and inferior R)
• M stands for MODEL. Increment when changes in the model will break interaction with any historical stationXML file.

We could start our versionning on 2-0-0 Some examples here:

• Documentation changes increment the A
• Addition of a new child element would increment the A
• Changing the type of an element would increment the R
• Removing an optional element would increment the R
• Removing a required element would increment the M

Some ideas I like here :

• versioning format change between model (dash separated) and software (dot separated). This avoids confusions.
• it gets easy for software developers to test the compatibility
• it's easier for model designers to chose wich number to increment

[crotwell]

Seems like this will require schema change due to schemaVersion being 'decimal'

[jschaeff]

Yes, the schemaVersion type must be changed for the next major version.