Schema Versioning

[Markus Demleitner]

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.

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.

Cheers,

          Markus