Schema Versioning

[Paul Harrison]

> On 2016-07 -18, at 15:19, Markus Demleitner <msdemlei at ari.uni-heidelberg.de> wrote:
> 
> Hi Paul,
> 
> On Mon, Jul 18, 2016 at 01:18:51PM +0000, Paul Harrison wrote:
>>> In the future, this kind of thing is fairly easy to avoid: Only put
>>> the major version into the namespace; I suppose we should use things
>>> like http://www.ivoa.net/xml/SIA1, http://www.ivoa.net/xml/SIA2, and
>>> so on (where this particular example stinks a bit because the
>>> extension schema is maintained independently of the standard).
>>> 
>>> For the transition, this isn't suitable. We have the "broken"
>>> namespaces.
>>> 
>>> I see a couple of escape routes.
>>> 
>>> (1) Comment that only legacy namespaces have minor versions in, and
>>>   these minor versions are to be ignored in the VO. Only the major
>>>   versions actually carry meaning.
>> 
>> This is what the schema versioning note tries to say, see the first
>> point in the summary of recommendations. This is what was done for
>> UMS1.1 too - the namespace still have a ???1.0??? in it but the
>> other indicators of version in the instances and schema have
>> ???1.1??? - this satisfies the constraints
> 
> Oh, yes, I had forget this part.  I think we need to make this
> stronger and more explicit, in particular because I think people
> might dislike this, and we should come clear here early on.

I think that they have to like it if they want to follow the note’s recommendation, as the purpose of the note is to allow small schema evolution with minimal disruption  - However, I think that it should not be assumed that the note means that all schema evolution *must* follow the note’s recommendation - some standards might want to issue new namespaces for point version increments - but the note is the recommended pattern to follow for minimal disruption.
> 
> What about
> 
> +\subsubsection{Version numbers in Namespace URIs}
> 
> +In the IVOA, namespace URIs traditionally contained the full version
> +specification, as in \nolinkurl{http://www.ivoa.net/xml/UWS/v1.0}.
> +This practice is somewhat paradoxical, as changes in the minor version
> +number should, by the IVOA's document standards
> +\citep{2010ivoa.spec.0413H}, not break downwards compatibility, but a
> +change in the namespace URI is, as laid out above incompatible in both
> +directions.
> +
> +Therefore, future namespace URI must only contain the major version
> +number.  The recommended format is to have the major version as the last
> +URI element, for instance,
> +
> +$$\hbox{\nolinkurl{http://www.ivoa.net/xml/UWS/2}.}$$
> +
> +\todo{I'd actually prefer UWS-2, but that's just my taste -- MD}
> +
> +A somewhat unfortunate side effect of the current specification is that
> +legacy namespace URIs become somewhat confusing, as a namespace like
> +\nolinkurl{http://www.ivoa.net/xml/UWS/v1.0} can refer to schema
> +documents with actual versions of 1.1, 1.2, etc.  Specifications should
> +warn their readers to this effect.  The suggested presentation is an
> +admonition box with a content like this:
> +
> +\begin{quotation}
> +The namespace URI \nolinkurl{http://www.ivoa.net/xml/UWS/v1.0} is used
> +for backwards compatibility.  The presence of the string \texttt{v1.0}
> +does \emph{not} indicate that the content conforms to version 1.0 of the
> +standard.  The actual version it conforms to can be obtained from the
> +\xmlel{version} attribute on the instance document's root element [or
> +the element containing the namespace declaration, if applicable].  It
> +does mean, however, that any XML reader compliant with the
> +recommentation laid down in Harrison et al (2016) [this would be a
> +reference to the current version of this note] must be able to process
> +the elements' content if they support any version 1.0 or later of this
> +specification.
> +\end{quotation}
> +
> 
> after the subsection on "Version numbers in schema files"?  Unless
> someone protests loudly, I'd commit that for further review.
> 

the above seems reasonable - I have also put a better bit of text for the start of section 2 on http://wiki.ivoa.net/twiki/bin/view/IVOA/XMLVersRFC

Cheers,
	Paul.