VOTable 1.4 Working Draft
Tom Donaldson
tdonaldson at stsci.edu
Wed Feb 13 21:56:01 CET 2019
Hello Apps,
Thanks to everyone for the feedback so far. I will send an e-mail shortly to try to summarize where I think we are with the document with an eye towards posting a new WD version by the end of the week.
Meanwhile I have a few comments and questions about this thread embedded below:
On 2/13/19, 4:41 AM, " Markus Demleitner" < msdemlei at ari.uni-heidelberg.de> wrote:
> 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?
I agree also. Yes, Markus, I really appreciate that.
>
> > 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).
I agree also. As I understand it, xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" is not required, but is often used by convention when xsi:schemaLocation is also used in the document.
In softening the language (below) about requiring referencing the schema, there is no reason to require xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance".
> > 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.
Yes, and yes. Since you'll remove the references for STC, Markus, it would be great to add this one at the same time.
>
> > 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.
Sounds good to me.
I think a brief discussion of xsi:schemaLocation may still be useful (but I could be talked off that if people find it unhelpful or too confusing). I propose modifying the wording of the existing text to:
Neither the VOTable nor XML standards require specifying the VOTable schema location within the VOTable document. However, providing the schema location enables some XML parsers and editors to do automatic schema validation. To do so correctly during and after the VOTable 1.4 approval process, follow these guidelines:
Before VOTable 1.4 becomes recommended, use these VOTABLE attributes to reference the version 1.4 schema:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ivoa.net/xml/VOTable/v1.3
http://www.ivoa.net/xml/VOTable/votable-1.4.xsd"
Once VOTable version 1.4 becomes recommended, the following schema reference will be upward compatible until the next major version (2.0):
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ivoa.net/xml/VOTable/v1.3
http://www.ivoa.net/xml/VOTable/v1.3"
>
> > 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.
I support the idea of adding both the VOUnit and DALI references. Indeed just this week I looked here to learn about legal units values for a MAST service, and followed the existing reference to the CDS catstd document. Not a disaster, but it would be nice to send people to the right place.
These reference details evolved since VOTable 1.3, so really feel a bit like errata that could have been legitimately applied already. To me it really depends on our confidence that the changes are backward compatible (which they really should be).
I support adding those references along with the related suggestion to mention DALI and VOUnit in section 1.4. I'm hesitant however to update Figure 1 in that I don't know how to do that, and I thought a refresh of that picture is currently being worked for the IVOA in general.
>
> > "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.
This offer is too good for me to turn down. I will be happy to support to that effort, not least as an excuse to become familiar with ivoatex.
>
> 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?
Since we've built up several probably non-controversial changes, I'd prefer to do those updates, and push an official updated WD soon.
>
>
> > 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).
Thanks for those updates, Mark, and for all the careful reviewing.
> I'd say that's also reasonable for a silent update of the current
> document in the docrepo.
>
> Thanks,
>
> Markus
>
Thanks,
Tom
More information about the apps
mailing list