new TAP-1.1 WD released

[Mark Taylor]

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."
    Add or remove a bracket.

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

    "Within the ADQL query, the following ADQL functions mus[t] be
     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
    by a reference to DALI.  Was this considered?

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
    uses short.  (See also table_index in TAP_SCHEMA.tables).

    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.
> 
> Please read through it and comment!
> 
> Cheers,
>     François & Marco (DAL chair&vice)
>     Pat (TAP editor)
> 

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