# VOTable 1.4 Working Draft

Mark Taylor M.B.Taylor at bristol.ac.uk
Mon Feb 11 14:45:54 CET 2019

Tom and Apps,

I've got some comments on WD-VOTable-1.4.20190131.  Sorry not to
have come up with them at the pre-WD stage, but I've only just
got round to a close look.

STC/COOSYS/VOTable Erratum 1.3-1
--------------------------------
As far as I can tell, following application of VOTable Erratum 1.3-1
undeprecating COOSYS, the IVOA STC standard is no longer really used by
the VOTable standard itself, so some references to STC in the text
should be removed.  Specifically:

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

- Figure 1: remove the STC box

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

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

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

Section 3: The VOTable Document Structure
-----------------------------------------

This version of the document introduces the requirement that VOTables
must contain the declaration:

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

I can't see what the reason for this is, can you explain?
If there is not a good reason, this requirement should be removed,
and that attribute assignment should for clarity be removed from
all the examples where it's not doing any work (which is, I think,
all of them).

The detailed discussion of schema locations that has been added here
still be quite surprising to readers, it would be useful to have a
pointer to why it's happening, so a reference to the XMLVers Endorsed
Note could be a good idea.

"Documents claiming to represent VOTables must include the reference
to the VOTable schema": I know this text was inherited from earlier
versions of the standard, but I *think* what the authors originally
meant was that use of the VOTable namespace must be declared -
that's what the examples in previous versions actually did
(xmlns="http://www.ivoa.net/xml/VOTable/v1.3"), which looked quite
like referencing the schema but didn't strictly do that.
Given the reorganisation of this section and the decoupling at this
version of the schema namespace URI from the VOTable version
identification, I would suggest at least modifying this text.
It could be replaced with "Documents claiming to represent VOTables
must declare use of the VOTable namespace"; on the other hand that
is already mandated by the requirement to include the attribute
declaration xmlns="http://www.ivoa.net/xml/VOTable/v1.3",
so it could be left out altogether (or used in explanation of that
requirement).  I would suggest rewording it like:

Documents claiming to represent VOTable must validate against the
relevant version of the VOTable schema without error; notice that...

but you might be able to think of better formulations.

Adjusting the indentation of the xsi:schemaLocation examples might

\begin{verbatim}
xsi:schemaLocation="http://www.ivoa.net/xml/VOTable/v1.3
http://www.ivoa.net/xml/VOTable/votable-1.4.xsd"
\end{verbatim}

with

\begin{verbatim}
xsi:schemaLocation="http://www.ivoa.net/xml/VOTable/v1.3
http://www.ivoa.net/xml/VOTable/votable-1.4.xsd"
\end{verbatim}

Section 3.5: TIMESYS
--------------------

Reword "The TIMESYS element defines such a time system and gives itself
the identifies itself with..."

The ID attribute values in the example in Sec 3.5 are not being used
here, it might be clearer to remove them.

Section 4.3: Extended Datatype xtype
------------------------------------

Discussion of the xtype attribute says:

"The actual values of the \attr{xtype} attribute are not defined
in this VOTable specification; it is expected however that
common conventions will be adopted by the various components
of the Virtual Observatory, in a way similar to the adoption of the
Unified Content Descriptor (\Arefs{example1}{section 4.5})"

since VOTable 1.3 was written, the DALI standard has become the
repository for at least many of these xtype values.  A reference to
DALI in this section would therefore be helpful.  Maybe for this
reason DALI should be added to the discussion in section 1.4 and/or
to Figure 1 as well?

Section 4.4: Units
------------------

The discussion of the value space for the Units attribute references
by URL the CDS catstd document [3], but since VOTable 1.3 was written,
the VOUnits standard has passed to REC.  I suggest therefore that this
section should reference VOUnits instead.  That is in principle
a significant change, but VOUnits was specifically intended to be
compatible with existing usage, so it would probably not invalidate
documents whose units comply with the earlier recommendation.

The reference in section 1.4 and the architecture figure should in
that case be updated as well (VOUnits instead of Units, and the box
outlined to denote a REC rather than a standard in development).

"Status of This Document" section
---------------------------------

The text here refers to REC status; it should be replaced by the
rubric from the DocStd Appendix, or some similar form of words:

"This is an IVOA Working Draft for review by IVOA members and other
interested parties.  It is a draft document and may be updated,
replaced, or obsoleted by other documents at any time. It is
inappropriate to use IVOA Working Drafts as reference materials or
to cite them as other than work in progress''."

Figures 3, 4
------------

A detail of the colouring on figure 4 was misleading, my mistake when
preparing the previous version.  I've made the necessary fix to the
java source in volute (the figures will need building again).

Mark

On Fri, 1 Feb 2019, Tom Donaldson wrote:

> Dear IVOA,
>
> We are pleased to announce that the first Working Draft for VOTable version 1.4 is ready for review at http://www.ivoa.net/documents/VOTable/20190131/ .
>
> The driving reason for this update is to implement the recommendations of the note, "A Proposal for a TIMESYS Element in VOTable" (http://www.ivoa.net/documents/Notes/TimeSys/index.html ).
>
> Since the scope of the changes is relatively narrow, we are hoping that this review process can move quickly, ideally proceeding to official Recommendation (REC) shortly after the Paris Interop meeting.  If you have an interest in this update, or will be obligated to have an interest (TCG), please review at your earliest convenience and bring comments and concerns to the Applications Working Group list (apps at ivoa.net ).
>
> In addition to the changes driven by TIMESYS, please note the new language in section 3 attempting to clarify some subtleties regarding namespace and schema versioning (also see http://www.ivoa.net/documents/Notes/XMLVers/20180529/ ).  Feedback on all aspects of the document is welcome.
>
> I will also propose a slight change in the syntax for TIMESYS (to *require* the use of "ref" in TIMESYS references), but I will leave that for a separate thread on the Apps WG list.
>
> Regards,
> Tom

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-9288776  http://www.star.bris.ac.uk/~mbt/