VTP schema versioning updates

[Markus Demleitner]

Hi John,

On Wed, Apr 17, 2019 at 06:09:44PM -0700, John Swinbank wrote:
> Thanks for your comments — I am purely a dilettante at understanding the
> details of XML, so I was hoping somebody like you would weigh in.

...where of course it would have been preferable if I had bothered to
actually read all necessary documentation before blurting out.  Which
I have not -- sorry about that.

> Markus Demleitner wrote on 2019-04-15:
> 
> > In namespace URIs, please don't include minor versions (any more).
> > Since you can't change a namespace URI without breaking clients,
> > doing that precludes having minor version updates.
> 
> I don't _think_ I proposed doing this. My suggestion was that the schema
> should live at the http://ivoa.net/xml/VTP-v2.0.xsd URL, but that it
> contain the text:
> 
>   <xs:schema xmlns="http://www.ivoa.net/xml/VTP/v2"
>     xmlns:xs="http://www.w3.org/2001/XMLSchema"
> 	targetNamespace="http://www.ivoa.net/xml/VTP/v2"
> 	version="2.0">

Yes, that is correct and the pattern required by the XML versioning
note (where I've never been terribly fond of VTP/v2 as opposed to
VTP2, but that's really a matter of taste; namespace URIs are, at the
root, opaque strings).

> So to back up a bit further, my understanding is that the current VTP
> schema doesn't define a VTP-specific namespace at all: it simply starts
> with a:
> 
>   <xs:schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>     xmlns:xs="http://www.w3.org/2001/XMLSchema">
> 
> (and then never uses the “xsi” namespace).

There's no reason to leave the the xsi namespace declaration in,
then.  While you're at it, removing the XML declaration
("<?xml...?>") from the printed schema might be a good idea, too, in
particular because it claims an encoding it can't be sure about as
long as the schema is part of a larger document.  But that's no big
deal either way.

> By convention? historical accident? something like that, documents
> claiming to comply with this schema (including the examples in the IVOA
> rec) have contained the line:
> 
>   xmlns:trn="http://telescope-networks.org/schema/Transport/v1.1"

Uh!  This is a mess all around.  For the second time in two days I
have to go in dust and ashes for having rubber-stamped a document
with fairly obvious technical problems.

Let me try and untangle that:

Sect. 6.1 of VTP has this example:

  <trn:Transport role="iamalive" version="1.0"
   xmlns:trn="http://telescope-networks.org/schema/Transport/v1.1"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://ivoa.net/xml/Transport/v1.1
                       http://ivoa.net/xml/Transport-v1.1.xsd">
      <Origin>ivo://invalid.broker/example#</Origin>
      <TimeStamp>2001-01-01T00:00:00Z</TimeStamp>
  </trn:Transport>

This is a bit schizophrenic in that by xmlns:trn they talk about
an element
{http://telescope-networks.org/schema/Transport/v1.1}Transport but
then proceed to give the schema location for a namespace
http://ivoa.net/xml/Transport/v1.1.

I read this as "the authors wanted to move to the ivoa namespace but
forgot to fix the namespace binding.  Something like this I should
have noticed while reviewing.  Oh dang.

Anyway, I'd fix it by fixing the namespace binding:

  <trn:Transport role="iamalive" version="1.0"
   xmlns:trn="http://ivoa.net/xml/Transport/v1.1"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://ivoa.net/xml/Transport/v1.1
                       http://docs.g-vo.org/schemata/Transport-v1.1.xsd">
      <Origin>ivo://invalid.broker/example#</Origin>
      <TimeStamp>2001-01-01T00:00:00Z</TimeStamp>
  </trn:Transport>

I've also re-pointed the schema location to a place I control for now
so that I can test things.

Now, this still won't validate with Transport-v1.1.xsd as published,
as that doesn't define a target namespace and thus defines the element
Transport (outside of any namespace) rather than
{http://ivoa.net/xml/Transport/v1.1}Transport as required by the
document.

We could fix the document, but then we don't do that in the VO -- our
(global) types and elements live in their own namespaces.  So, let's
fix the schema to define the namespace intended here:

  <xs:schema targetNamespace="http://ivoa.net/xml/Transport/v1.1"
  ...

There's still a problem in that with the targetNamespace, the
roleType type now actually is
{http://ivoa.net/xml/Transport/v1.1}roleType, and so the role
attribute's type="roleType" points nowhere.  To fix this, we
introduce the targetNamespace in the schema, too:

  <xs:schema targetNamespace="http://ivoa.net/xml/Transport/v1.1"
             xmlns:xs="http://www.w3.org/2001/XMLSchema"
             xmlns:tn="http://ivoa.net/xml/Transport/v1.1">

and then change the role attribute definition to:

   <xs:attribute name="role" type="tn:roleType" use="required" />

You'll realise why I'm still amazed that (glorious) XML survived the
onslaught of (nefarious) XML schema.

The full fixed schema is at
http://docs.g-vo.org/schemata/Transport-v1.1.xsd; the sample
documents in the text would need to be fixed as for our example
above.  If you ask me to, I'd do that in Volute, but that would lead
up to a VTP 2.1 rather than an erratum (which, given these findings,
would be somewhat longish anyway).

> I therefore *am* suggesting that we change the namespace URI to refer to
> an ivoa.net domain.

Yes.  And fix the schema to match the intention one might gather from
the examples.

> Is this a sane position, or should I move on with my life and do
> something more productive instead?

It's not only sane, it's highly laudable.  With the current spec,
implementors will spit, fume and despair when trying to get their
instance documents to validate.  That's not how we should have our
standards, and so we really should fix things.

Thanks for pushing that along,

         Markus