PR-TAP-1.1 - Some comments

[Grégory Mantelet]

Hi DAL,

I have few comments about TAP 1.1, PR-2017-08-30.

First, I have noticed the following typos:

     - Section 2.2-{async}, page 10:
            "UWS specifies the name and semantics of **the a** small set of
             child resources used to view and control the job, e.g.:"
         => "UWS specifies the name and semantics of **a** small set of 
[...]"

     - Section 2.7.6-UPLOAD, page 17:
            "as TAP_UPLOAD.<tablename>, where <tablename> is the ****
             specified by the user."
         => "as TAP_UPLOAD.<tablename>, where <tablename> is the **name**
             specified by the user."

     - Section 5.1.2-Modify a Query Job Before Execution, page 28: (not 
being a
       native english speaker, I am not really sure of this one...so, 
sorry if I
       am wrong)
            "for TAP services it is recommended that this **be** set to the
             current time plus the maximum amount of time"
         => "for TAP services it is recommended that this **is** set to 
[...]"

     - Section 5.1.3-Running a Query, page 30:
            "Since services may impose a limit on the maximum wait time 
and may
             return before **ten** job reaches a final phase"
         => "[...] return before **the** job reaches a final phase"


Then, I have also few comments (mostly on details):

     - Section 2.4-/capabilities:
         In the given example, the XML schema of VODataService is in 
version 1.0.
         As far as I can see, there is now a version 1.1. This latter is 
also
         referenced in VOSI-1.1, section 3.3-Table metadata.
         Since this XML extract is given as an example, I assume it does not
         really matter in the sense that TAP-1.1 does not require the use of
         VODataService-1.1 or 1.0. I assume that is up to the TAP service
         implementor.
         => Is it correct?
         => Would it be a good idea to reference the version 1.1 in this 
example,
            considering that it is actually the version recommended in
            Section 2.5-/tables (i.e. Plante and Stébé et al., 2010)?

     - Section 2.5-/tables:
         Still about VODataService-1.1, I wondered whether it would 
interesting
         to briefly speak about the details levels described in 
VODataService-1.1
         (about the table metadata discovery). I know it is written in
         (Plante and Stébé et al., 2010), but since it is a very interesting
         feature for TAP services with a large table set, I think it 
would worth
         briefly mentioning it.

     - Section 4.1-Schemas:
         "The schema_name values must be unique and may be qualified by the
          catalog name or not depending on the implementation requirements."

         => Sorry if I come back on a quite old topic, but since table 
names can
            be qualified and/or delimited/quoted, would not it make sense to
            allow the same thing about schema names?
            If yes, we can add something similar to what is written in
            Section 4.2-Tables:
            "If the schema name is such that the name must be quoted (quoted
             identifier in (Ortiz and Lusted et al., 2008)) then the 
value must
             include the quotes."

     - Section 4.2-Tables:
         1. The column 'table_index' is declared with the datatype 'int' 
and the
            arraysize '1'.
             => Does it mean that it is an array of only one item?
                I don't think so. Then, would not it better if arraysize 
stays
                'null'?

         2. Nothing says that the column 'schema_name' must (exactly?) 
match one
            TAP_SCHEMA.schemas.schema_name entry.
             => I think some TAP clients, and especially STILTS/taplint, 
check
                this relation between TAP_SCHEMA.tables.schema_name and
                TAP_SCHEMA.schemas.schema_name. I assume that this 
relation is
                obvious/implicit (am I wrong?), but it would be however 
nice to
                state it anyway in TAP-1.1.

     - Section 4.3-Columns:
         1. Same comment about the columns 'size', 'indexed', 
'principal', 'std'
            and 'column_index' ; they are declared with the arraysize '1',
            implying that they are arrays...though they are not.

         2. As in Section 4.1-Schemas, nothing says that a column name 
can be
            delimited/quoted if not a regular identifier. It is written that
            "size" must be delimited because it is a reserved word in 
ADQL-2.0,
            but except this exception, nothing is stated about the 
values of the
            column 'column_name'.
            => Again, adding something like the following would be certainly
               enough:
               "If the column name is such that the name must be quoted 
(quoted
                identifier in (Ortiz and Lusted et al., 2008)) then the 
value
                must include the quotes."

         3. And still as in Section 4.1-Schemas, nothing mention the 
(exact?)
            equality relation between TAP_SCHEMA.tables.table_name and
            TAP_SCHEMA.columns.table_name, though this is again more or less
            obvious/implicit.

     - Section 5.2-Example: Synchronous Query:
         In the example of synchronous query, the parameter 
REQUEST=doQuery is
         provided.
         => From what I have read TAP-1.1 does not require this 
parameter anymore
            (and I will certainly not fight against that :) ).
            I know that DALI-1.1 specifies that services may use this 
REQUEST
            parameter if several operation mode are available but this 
is not the
            case anymore in TAP since TAP-1.1. So, of course, a TAP-1.1 
service
            will not complain about spurious parameters like REQUEST, 
but maybe
            the example would be cleaner without this REQUEST=doQuery.

Cheers,
Grégory