Changes to VOTable 1.4 Working Draft

[Markus Demleitner]

Dear Apps,

On Wed, Feb 13, 2019 at 10:54:07PM +0000, Tom Donaldson wrote:
> After some discussion about the Working Draft for VOTable 1.4, I
> believe we have some changes that are ready to be folded into the
> draft.  Markus will make the first two edits, then, pending

Ok -- my contribution is now two volute commits, 5313 (STC) and 5314
(versioning).

> 1) (Markus)  Remove references to STC, which were rendered obsolete
> by Erratum 1.3-1.

Here's a detailed log on this:

Mark>   - Sec 1.4: "VOTable relies on the other IVOA standards UCD, Utype,
Mark>     Units and STC." - STC should be removed from the list

Done.  Arguably, there is no "Utype standard" either, so that should
probably go too, if we touch this beyond Erratum 1.3-1.  Otherwise,
I'd say it's 1.5 material.

Mark>   - Figure 1: remove the STC box

Done (with pixel editing:-)

Mark>   - Sec 3.1: the example VOTable contains the namespace declaration
Mark>     'xmlns:stc="http://www.ivoa.net/xml/STC/v1.30"' which is no
Mark>     longer doing any work and should be removed for clarity.

Done.

Mark>   - Bibliography: Items [8] (STC) and [9] (STC-S) are no longer
Mark>     referenced in the text, so should be removed from the bibliography.
Mark>     Item [7] (Referencing STC in VOTable) has already been removed
Mark>     since it is no longer referenced by the normative text;
Mark>     however [7] actually is referenced in the document version
Mark>     history in Appendix 9, so probably it should be reinstated?
Mark>     Or at least the referencing should be updated.

I've removed [8] and [9], and I've replaced the reference to [7] with
a footnote. I've used a footnote over a bibliography entry to make
clear that my beloved STC-in-VOTable note is abandoned and no longer
a pseudo-dependency of VOTable.  Reference renumbering: I'd say we
postpone it to when we're migrating to ivoatex.

Mark>   - Sec 4.1: "The utype attribute ... is used in the example sec 3.1..."
Mark>     Utype is not used there any more, so this comment should be removed
Mark>     (and possibly replaced, if anybody can work out what to say there).

I've simply removed the explanatory sentence.  There's a whole
explanatory section on utype a bit down.  For the record, in *that*
section there's still

	In order to avoid name collisions, the data model identification
	should be introduced following the XML namespace conventions, as
	utype="datamodel identifier:role identifier". The mapping of
	"datamodel identifier" to an xml-type attribute is recommended, by
	means of the xmlns convention which specifies the URI of the data
	model cited, as done in the example of section 3.1.

I'm surprised I've not fumed to get this removed in 1.3, because this
is just total trouble while it's entirely unclear what clients are
expected to do with this "identification".  True to my resolution to
restrict this update to Errata and Timesys, I won't fume now, but in
1.5 this needs to go.  Meanwhile, I have, in addition to Mark's
proposed changes, removed the reference to section 3.1 in the utype
section (which was stale as a consequence of Erratum 1.3-1).

> 2) (Markus)  Add a reference to the XMLVers Endorsed Note to the
> discussion about the distinction between namespace URIs and schema
> URLs.

So... starting to work on this I've found I had to change the
introduction to sect. 3 more than I'd have liked.  But we really
can't, for instance, require
xmlns="http://www.ivoa.net/xml/VOTable/v1.3", because people have
been free to chose non-empty prefixes before (and I've seen VOTables
in the wild that use that).  Also, we should severely discourage
people from using the URL
http://www.ivoa.net/xml/VOTable/votable-1.4.xsd, as anything using
this may very well break on a minor version change.  Anything that
makes minor versions visible is a potential liabilty for what we can
change in a minor version update; see the whole mess with the
versioned namespace URIs we're trying to live with here.

As I said, this one a much larger change that I'd have liked it to
be, but given that we can't expect VOTable implementors to have read
the XML Versioning Policies and we just have to take them up even if
we otherwise restrict ourselves to TIMESYS related changes, I don't
see a way around having at least a brief discussion of this
dependency of ours.  Well, check out the diffs (I'm including them
below).

           -- Markus



Here's the diff in case you'd like to discuss individual points
on-list:

 The overall VOTable document structure is described and controlled
-by its XML Schema [6].  For VOTable version 1.4, the schema is available 
-from \url{http://www.ivoa.net/xml/VOTable/votable-1.4.xsd}
-as well as in \Arefx{XML-schema}{Appendix B} of this document.
-
+by its XML Schema [6].  The schema for VOTable version 1.4 is
+given in \Arefx{XML-schema}{Appendix B} of this document.  It can also
+be retrieved
+from \url{http://www.ivoa.net/xml/VOTable/votable-1.4.xsd}.
+Since neither producers nor consumers of VOTables should depend on the
+minor version used, this URL should not appear in operational code,
+which should use the namespace URI instead to retrieve the current
+VOTable schema.
+ 
 A VOTable document consists of a single all-containing element
 called {\elem{VOTABLE}}, which contains descriptive elements and global definitions
 ({\elem{DESCRIPTION}}, \elem{GROUP}, \elem{PARAM}, \elem{INFO}),
@@ -741,17 +746,21 @@
 
 As the root element, \elem{VOTABLE} has attributes which specify the VOTable version 
 number and XML namespaces used in the document. For VOTable 1.4, the \elem{VOTABLE}
-element MUST have at least these attributes:\newline
-\attrval{version}{1.4}\newline
-\attrval{xmlns:xsi}{http://www.w3.org/2001/XMLSchema-instance}\newline
-\attrval{xmlns}{http://www.ivoa.net/xml/VOTable/v1.3}\newline
+element MUST have define \attrval{version}{1.4}.  All VOTable
+1.4 elements come from the namespace 
+\nolinkurl{http://www.ivoa.net/xml/VOTable/v1.3}.  It is recommended to bind
+the empty namespace prefix to this URI, as in
+\attrval{xmlns}{http://www.ivoa.net/xml/VOTable/v1.3}, but instance
+documents are free to use whatever namespace prefix is convenient for them.
 
-Note that starting with VOTable 1.3, the namespace URI value will remain fixed at \url{http://www.ivoa.net/xml/VOTable/v1.3}
-until the next major version (2.0).  For convenience, that namespace URI 
-will resolve as a URL to the latest recommended schema for VOTable version 1.x.  So when 1.4 becomes 
-the latest recommended VOTable version, \url{http://www.ivoa.net/xml/VOTable/v1.3}
-will return the same schema as \url{http://www.ivoa.net/xml/VOTable/votable-1.4.xsd} until a version 1.5 
-becomes recommended.
+Note that starting with VOTable 1.3, the namespace URI for VOTable will
+remain fixed at \nolinkurl{http://www.ivoa.net/xml/VOTable/v1.3}
+until the next major version as discussed in [7].  As per IVOA
+recommendations, this namespace URI will always redirect to the latest
+recommended schema for VOTable version 1.x.  Validators should use this
+URI to retrieve a schema file for validation.  While instance documents
+may include \attr{schemaLocation} attribute, they should not expect that
+validators actually honor it.
 
 Documents claiming to represent VOTables must
 include the reference to the VOTable schema, and 
@@ -759,18 +768,6 @@
 notice that the validation is a necessary, {\em but not sufficient}, 
 condition for correctness.
 
-Before VOTable 1.4 becomes recommended, this \elem{VOTABLE} attribute will reference
-the version 1.4 schema:
-\begin{verbatim}
-	   xsi:schemaLocation="http://www.ivoa.net/xml/VOTable/v1.3 
-	   http://www.ivoa.net/xml/VOTable/votable-1.4.xsd"
-\end{verbatim}
-Once VOTable version 1.4 becomes recommended, the following schema reference will 
-be upward compatible until the next major version (2.0): 
-\begin{verbatim}
-	   xsi:schemaLocation="http://www.ivoa.net/xml/VOTable/v1.3 
-	   http://www.ivoa.net/xml/VOTable/v1.3"
-\end{verbatim}