new TAP-1.1 WD released

Mark Taylor m.b.taylor at bristol.ac.uk
Thu Jul 20 01:30:27 CEST 2017

Hi DAL,

here are some comments on the recent TAP-1.1-20170707-WD.

Reference style:
The text has quite a few references like "As required by
(Dowler and Demleitner et al., 2013)".  It would be a bit more
readable to see "As required by DALI 1.0" (possibly followed by
a reference).  I'm not sure if that's something that can be
handled at that ivoatex level?  Anyway not essential.

Abstract:
"A multi-position query capability permits queries against an
arbitrarily large list of astronomical targets, providing a
simple spatial cross-matching capability."
This comment seems a bit opaque, I suppose it is alluding to
upload queries, but not in a very straightforward way.
Could be removed or reworded?  However, since it's inherited
from TAP 1.0 it may be preferred to leave it intact.

Sec 1.2.6:
"A TAP service must be able to support use of other query languages ..."
This sounds like it's saying that all TAP services must have more
than one supported language.  Replace with something like
"TAP allows for use of other query languages..."?

Sec 2:
"... compatibility with TAP-1.0 (which required these names."

Sec 2.1:
"Representations of results of queries if defined" -> "is defined"?

Sec 2.4:
"The content is described by [8]."
This reference is hard coded into the LaTeX source, it doesn't
appear to point to any of the actual bibliography entries.

Sec 2.6:
"A GET from this endpoint MUST yield a document with a MIME
type of either application/xhtml+xml or text/html.
A service that does not provide examples MUST return a 404 HTTP
status on accessing this resource."
The intention is reasonably clear, but taken literally this says
that even the 404 response must be application/xhtml+xml or text/html.
Write instead "A successful GET from this endpoint ..."?

"... element with simple text content having a property attribute
valued query" and "attributes having the value table":
These sentences would be more readable if the attribute values
mentioned were quoted' or {\em emphasized} or something, e.g.
"... property attribute valued query'" and
"... having the value query'".

Sec 2.7.2:
"... schema, table, and column names, function names, and
other ADQL keywords are not case sensitive."
I think this neglects the case of delimited identifiers.
I will leave it up to Markus or some other SQL ninja to
come up with replacement text.

"Within the ADQL query, the service must support the use of timestamp
values as described in  (Dowler and Demleitner et al., 2013)"
This appears to be imposing an unnecessary (and meaningless) burden
on services with no date/time data.  Replace with something like
"If timestamp comparisons are supported within ADQL queries,
they must use the syntax defined in ..."?

supported: INTERSECTS, CONTAINS, POINT, CIRCLE, and POLYGON."
This is introducing a new requirement for TAP 1.1, namely that
geometry support is mandatory.  In TAP 1.0 the equivalent passage
was qualified by the text "If the tables that are queried
through a service contain columns with spatial coordinates
and the service supports spatial querying via the ADQL
region' constructs...", which made it clear that it was
permitted to avoid geometry support altogether.
I'm not necessarily disagreeing with this change, but if it is
intended it's a significant difference, and should be noted
in the change log more prominently than the current text,
which just says "Clarified required and optional ADQL
geometric functions".  Note also that as for the timestamp case,
it doesn't make much sense if there is no sky position
data in the service (e.g. RegTAP, EPN-TAP??)

"Clients should avoid using the coordinate system argument to
geometric functions should not be used" - redundant text.

Sec 3.1:
This section looks like it could be mostly or completely replaced

Sec 3.2:
"VOTable structure follows the rules in section 2.9" -
The reference to the (non-existent) section 2.9 is hard-coded
into the LaTeX source and needs to be replaced.

Sec 3.4:
"If the output format is VOTable, section 2.9.1 describes ..."
Non-existent sec 2.9.1 reference hard coded into the LaTeX source.

Sec 3.5:
"For result tables, the column name or an alias specified in
the query is used to set the name attribute of the FIELD
elements in the output table (the alias overrides the normal
column name)."  If the output column is calculated and no
alias is supplied, you can't do either of those and have to
make up a FIELD name somehow.  Add "where available" or
similar to this sentence?

Sec 4:
"The qualified names in the tables of the TAP schema must
follow the rules defined in section 2.4."
Section 2.4 is hard coded into the LaTeX source, it's probably
not the intended reference target here.

Sec 4.2:
The table_index column datatype is listed as "char".
That looks like a mistake, probably "int" was intended - but
see below.

Sec 4.3:
The datatypes for columns indexed, principal and std are
listed as boolean.  In TAP 1.0 they were integer with
value 0 or 1 indicating false or true.  Changing them
to boolean therefore looks like breaking backwards
compatibility, and additionally I believe(?) makes them
impossible to query in standard ADQL, which lacks boolean tests.
So I think these have to go back to an integer type,
though not necessarily "int" in the VOTable sense.

The description column datatype is "char".  DaCHS at least
uses unicodeChar here.

The column_index column datatype is "int".  DaCHS currently

In both these cases, possibly others, I'm not sure it's
necessary or helpful to be as prescriptive as that.

Similarly, mandating "*" as the arraysize value for the
various character data columns in these tables is
unnecessarily restrictive; there's no reason that
services should not return fixed-width character array
columns here if they want to.

In general I think all of the TAP_SCHEMA table columns
defined in sections 4.1-4.4 should be described using the
generic terms either "integer" or "string" (or "character array").
Mandating VOTable datatype and arraysize attributes looks
to me like introducing more problems than it solves.

Sec 5.1.1:
"The client may have to check the phase multiple times until
the job finishes."
If the service implements UWS 1.1, this is no longer necessary,
since you can do a blocking poll.  Should we mention this here?
Maybe mention it in sec 5.1.3 as well.

References:
The citations of DALI and UWS are both to the 1.0 versions of
those standards.  Should they be 1.1 in both cases?
I'm not totally sure in any case how the TAP 1.1 version relates
to the versions of other standards (e.g. does TAP 1.1 service have to
support UWS 1.1?)  Maybe this could be discussed in the text
somewhere.

I have also made a few typo corrections at rev 4190.

Mark

On Wed, 12 Jul 2017, Marco Molinaro wrote:

> Dear all,
> this is to inform you that a new WD for TAP-1.1
> has been released on the IVOA Document Repository
>
> http://www.ivoa.net/documents/TAP/20170707/
>
> (change-logs available through volute)
> This is expected to be the last WD for version 1.1
> and we plan to promote it to PR soon enough to
> allow closing RFC before Santiago Interop, i.e.
> end of July/start of August, considering the northern
> summer vacation period.
>