VOTable 1.4 Working Draft

[Markus Demleitner]

Dear Mark, dear Apps,

On Mon, Feb 11, 2019 at 01:45:54PM +0000, Mark Taylor wrote:
> 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).

I agree these are consequences of Erratum 1.3-1.  Tom: Since I've
missed these when applying the erratum, should I just do these?

> 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).

Agreed.  This namespace declaration is only necessary if we provide a
schemaLocation attribute, for which I see no pressing requirement.
It is also unrelated to TIMESYS or the errata (if perhaps marginally
related to freezing the namespace; but it doesn't help much).

> The detailed discussion of schema locations that has been added here
> is helpful; but since this 1.4-schema-with-1.3-namespace business can
> 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.

Agreed.  Again, I'd volunteer to put it in if there's no dissent
here.

> 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...

I like it.  Let's write it this way.

> 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.

Agreed.

> 
> 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?

Even though this is reasonable, I'd like to avoid adding changes
beyond TIMESYS.  I won't contest it if people agree it's benign, but
personally I'm neutral-negative on grounds of possible feature creep
in the changes for 1.4.

> 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.

Very reasonable as well, but again I'd like to postpone it unless
we're sure the change won't offend anyone.

> "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''."

Oh, right.  Declaration: I volunteer for curating a VOTable 1.5 right
after 1.4 is through.  This would include a port to ivoatex (which
automates these kinds of things), and the DALI and VOUnits
references.

Meanwhile, I think we should do a silent update of what's in the
docrepo right now and just change the status declaration, as it is
fairly miselading to outsiders (or later consumers).  Tom?


> 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).

I'd say that's also reasonable for a silent update of the current
document in the docrepo.

Thanks,

          Markus