comments on TAP

[Robert Hanisch]

Since Keith announced V0.31 of the TAP specification about ten days ago,
there have been no comments posted to the DAL list.  I don¹t know if people
are busy with holiday preparations, confused by the differences between
V0.30 and V0.31, or simply not paying attention! (Perhaps all three!)  I
thought that by posting some of my own comments that it might help move the
discussion along. 
 
First I want to say that I think Guy, Pat, and Doug did a remarkable job
bringing the document to its current state.  I¹m sorry to hear that Guy has
decided to remove himself from the process.
 
To begin I am going to work my way through the table showing the proposed
restructuring of V0.31. But before that, I just want to note that most of
the cross-references within the document are missing, and most of the time
the magic words must, should, etc., are in bold face but not always (e.g.,
Section 2.1).  There are also frequent errors in the use of ³which² and
³that²; presumably the editor will fix these.
 
Section 1. Introduction.  I think all of this is ³informative², not just the
interface overview (1.2).  Being informative, it makes more sense to me to
discuss things from simple to complex, i.e., parametric then ADQL and
synchronous then asynchronous. Being informative, this simply lays out a
logical progression and does not suggest superiority of one approach over
another.
 
Section 2, I mostly agree with the proposed renaming, and it seems that the
grouping of parameters for ADQL queries, Param queries, and those that are
common to both makes sense.
 
In 2.1, isn¹t support for table metadata queries a ³must²?  In any case, it
is confusing (to me at least) when overall compliance is defined as ³should²
in Section 2.1, and then the language describing that part of the interface
uses ³must².  This could mean ³it should do this, and if it does it must do
it this way.²  Is that the intent?
 
I don¹t understand why 2.4.12 ³Missing or null-valued parameters² is not
needed.  Perhaps 2.4.11, 2.4.12, 2.4.13, and 2.4.14 could be combined into
one subsection (the proposed 2.7 ³Parameter Rules and Syntax².
 
It does not make sense to me to rename 2.7 ³Table Uploads² to ³Inline Table
Uploads² when two methods of table upload are described.
 
It makes a bit more sense to me to describe TAP service metadata before TAP
service results. I mean, you can¹t get results until you know how to find
out what the TAP service provides.  I¹d suggest switching the order of the
proposed sections 3 and 4.  Within the Service Metadata section, I¹d put the
section on VOSI last; this just seems a more logical order of exposition.
 
In the section TAP Results, I am not sure what is intended for ³Mapping Rich
Datatypes to VOTable² or ³Modification of Results by use of MTIME.²  But,
taking things at face value, a more logical order to me would be ³Use of
VOTable², ³Mapping Rich Datatypes...², ³Modification...², ³Overflows², and
³Errors².  These might even be organized into three sections, with the first
two combined, then ³Modification...², and then ³Overflows and Errors.²
 
V0.31 Section 7, ³Use of HTTP,² seems to me to be normative rather than
informative.  It is a compilation of the relevant rules from RFC 2616 and is
replete with ³must² statements.  And being normative, it seems more logical
to have it precede the information sections on Service Registration,
Extended Capabilities, and so on.
 
I think that¹s it as far as the proposed restructuring goes.  A few other
comments:
 
o  I think section 2.1 of V0.30, which described the general architecture of
TAP, provided useful background.  It would be nice to see this restored to
the Introduction.  This might lead to a bit of redundancy with the existing
text, but that could be resolved with a bit of editing.  There might be
other sections from V0.30 that should also be brought forward; I think they
are mostly here, but am not 100% sure.
 
o  Section 2.9.1 in V0.31 contains a little op-ed piece on IVOA version
numbers, which is inappropriate for this document (not to mention that its
assertions are incorrect).  The IVOA numbering conventions are being
discussed now in the TCG.  It would be cleanest for the TAP document to
refer to these conventions, which will be incorporated into the IVOA
Document Standards process definition.

cheers,
and happy holidays,
Bob