Using @version to indicate the schema version

[Markus Demleitner]

Hi Paul,

On Wed, Aug 29, 2018 at 09:13:51AM +0000, Paul Harrison wrote:
> It has struck me that in fact this @version is not actually the
> schema version but really the associated standard version - it is

On reflection, I think I agree with this statement (but it took
reflection...).  We'll have to be much more explicit about that.  It,
in particular, means that @*version is decoupled from whatever version
is in the schema file name; for SimpleDALRegExt, for instance, we'd
have @version="1.1" throughout, although the schema file names are
variously -v1.1 or -v1.2.  I've handled this differently up to now.
I don't think switching here would have operational significance for
SimpleDALRegExt, so I'd be happy to push in an Erratum if that's
where we're going.

> * emphasise that the version corresponds to the standard
> major.minor version, rather than the schema version per-se and than
> it is not even necessary until there has been a point release, .

+1, except I'd say  we should replace "it" with "giving a version
attribute".

> * recommend that it be called  ???stdVersion??? in the namepace of
> the parent schema.

Probably helps prevent misconceptions, so +1 on that.

> * though it must be called something else if the name clashes with
> an existing sub-element/attribute on the same element - the
> relevant standard document should mention what the actual attribute
> is.
> * say something about more minor schema changes, that require the
> schema???s top level version to change (e.g. errata), but not the
> stdVersion.

So, for UWSRegExt, which started this whole thing, this would mean
that the schema would have to look like this:

   <xs:complexType name="Async">
        <xs:annotation>
            <xs:documentation>
            The UWS Async interface.
            </xs:documentation>
        </xs:annotation>                                  nor rather not?
        <xs:complexContent>                                    |
            <xs:extension base="vr:Interface"/>                V
            <xs:attribute name="stdVersion" type="xs:token" use="required">
            <xs:annotation>
            <xs:documentation>
              The version of UWSRegExt this description corresponds to.
            </xs:documentation>
            <xs:documentation>
              Not that this is *not* the version of this schema;
              clients have no way to determine which minor schema 
              version the element was written against, nor should
              they care.
            </xs:documentation>
         </xs:annotation>
      </xs:attribute>
      </xs:complexContent>
  </xs:complexType>

Is this what we mean?

Reflecting again, I'd suggest no. You see, this will be in, say, a
TAP capability (with a corresponding standard id of, fantasising,
TAP#1.2), and so *if* a client cares about a minor version of *UWS*,
there's no way they can figure this out from the registry record.
With so many standards going into some of our services, I start
suspecting that describing all of the versions going in would require
a new mechanism (or hard-coupling the various standards, which I'd
find very regrettable).  But I'd hope we don't need minor versions of
everything.

In the UWSRegExt case, we could say with async, the stdVersion
actually corresponds to the version of UWS rather than UWSRegExt or
VODataService.  

Which would be automatic if UWSRegExt simply were part of UWS itself
-- ah, if only the XRegExts were part of the respective standards! 

The situation is still uglier because

(a) Sync and Async may become parts of VODataService, which is even
further decoupled from UWS.

(b) We have Sync, where there's not a standard that directly governs
it in the first place.

So...

(1) Do we have a use case for discovering minor versions on this
level (for UWS, I think there is)?

(2) If there is, my hunch is that even in UWSRegExt (and even more if
this moves into VODataService) we should be saying "stdVersion of
Async refers to UWS" and (for lack of a better idea) "stdVersion of
Sync refers to DALI".

(3) Of course, there's always the option of having Async specified in
UWS and Sync specified in DALI; then the ambiguity goes away, at the
price of having two additional tiny schemas people need to manage.
DaCHS already manages 33 schemata at the moment, so you might argue
that a 6% increase in the number of schemas isn't a disaster.  On the
other hand, if we manage to reduce the number of schemas clients may
have to worry about, that'd be a plus in my book...

Anyway: as far as the schema versioning note, it seems to me that the
proposed semantics is flexible enough to cope with the mess we've
cooked up if we're sufficiently careful and rigorous when defining
what exactly stdVersion refers to.

So, let's go ahead with fixing its text and then revisit the use
cases we've had so far (UWS, SimpleDALRegExt, VOResource, upcoming
TAPRegExt and UWSRegExt; any others?).  And let's in particular think
hard what this means for VOTable, where I hope we'll keep the 1.3
namespace URI, and where there's been a version attribute for quite a
while.  Anyone up for visiting an Apps session in College Park and
asking what people do with VOTABLE/@version?[1]

         -- Markus

[1] Not me -- I won't make it to College Park, sorry.