[DALI] comments on WD

Fri Apr 20 09:24:06 PDT 2012

Markus's comments remind me that I sent a list of comments on the 
DALI WD to Pat a couple of months back which I don't think ever made
it to the mailing list.  Some are editorial some are more substantial.

I copy the message below; I may or may not get round to summarising
the substantial points on the DALI wiki page.  I'll note here though
that adopting Markus's suggestion of significantly de-complicating
the parameter capabilities would get rid of a couple of the
queries/concerns I've brought up.

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-928-8776 http://www.star.bris.ac.uk/~mbt/

Date: Tue, 7 Feb 2012 12:50:18 +0000 (GMT)          
From: Mark Taylor <m.b.taylor at bristol.ac.uk>
To: Patrick Dowler <patrick.dowler at nrc-cnrc.gc.ca>
Cc: Doug Tody <dtody at nrao.edu>,
    "Durand, Daniel" <Daniel.Durand at nrc-cnrc.gc.ca>,
    Mike Fitzpatrick <fitz at tucana.tuc.noao.edu>
Subject: Re: WD-DALI-1.0

Hi Pat et al.,

On Mon, 6 Feb 2012, Patrick Dowler wrote:

> I finally found time to make the changes to the doc from my Pune notes.
I'd 
> like to get this up asap (like tomorrow) so that I can (optimistically)
make 
> another pass by the end of feb. If you have time to scan for anything I
missed 
> that you recall we discussed that would be great. 

Some comments.  In some cases I'm just flagging issues, not sure I
have a good answer.  Have very little recollection of what was
discussed in Pune (actually, not sure I was in the session), so
this is just a general response to the document as it stands.

General:
   The document refers to "DAL services" or "all DAL services"
   when it means services compliant to this DALI specification.
   Simple Cone Search v1.0 at least could be described as a DAL
   service but fails to meet this spec in several regards.
   Would it be better to say "DALI-compliant services"?

Sec 2.1:
   "A concrete DAL service specification will specify one or more
   asynchronous job list resources..." - reword, either
   "A concrete *asynchronous* DAL service..." or
   "... will specify zero or more asynchronous ...".
   Same applies at the end of section 2.2 for sync services.

Sec 2.2:
   GET and POST - are we saying that every DALI service MUST accept
   requests using both GET and POST?  If so, must they treat them
   as having the same semantics?  If so, make this clear (and if not,
   make clear what is intended).  Do we need to worry about 
   safety/idempotency issues which might make GET inappropriate
   in some cases (see RFC2616 sec 9.1)?

   "Clients should generally expect to get redirects..." - better to
   say "Clients should generally be prepared to handle redirects..."
   (otherwise a client might be justified in acting surprised if it
   gets a direct response).

Sec 2.5:
   "TODO: example table document" - it's done!

Sec 3.1.3:
   The rules for multiple values are quite messy, especially the
   interaction between specifying multiple param=value pairs and
   a single param=value pairs with commas.  Do these forms have to
   be equivalent?  Presumably we're constrained to maintain consistency
   with existing DAL standards - what are the constraints?

Sec 3:
   What are the rules for parameter name syntax?  E.g. are spaces or
   other non-alphanumeric characters permitted?  Is Unicode catered for? 
   In the async case presumably this is addressed by UWS, but that
   doesn't apply to the sync case.
   Probably the best thing is to point at an existing specification
   that applies; either say that the same rules UWS enforces
   (er, does it enforce some?) apply for sync too, or say the rules
   come from application/x-www-form-urlencoded or multipart/form-data
   MIME types (do they have the same rules?).  For sync queries,
   clarify whether it's OK to use either or both of those
   content types (or something else?).  Is it OK to mix them?
   (the example in sec 3.2.5 suggests yes).

   What do you do if you want to specify a single unqualified 
   parameter value containing a comma or a semicolon (i.e. without
   the semantics of sec 3.1.3/3.1.4) like GENRE=shake,rattle and roll 
   - is it impossible?  Should you percent-encode it?

   Actually for Qualifiers (semicolons) it's probably OK, since sec
   3.1.4 says "If specified by the definition of a parameter...".
   Something like a position won't have a semicolon unless it has
   semantics like that.  But for commas it's presented here as
   fundamental to the parameter syntax, so it's harder.

Sec 3.2.2:
   I don't much like the rule that the service MUST use the latest
   recommendation it supports if the client does not specify.
   What if the support for the latest version is experimental/poor?
   Any reason why an absent version specification from the client
   can't just mean the server gets to decide?

   Specifying dated pre-recommendation version numbers like
   VERSION=1.1-20120601: I can see it's well-defined, but in view 
   of the way those numbers can proliferate it looks too complicated
   to be useful.  The client might ask for a version which is later
   than the server knows about, and even if the two versions are
   close enough that interaction would work well, the request would fail.
   Given how long it can take before standards get to REC sometimes
   I'd like to see more pragmatic handling of this.  How about
   VERSION=1.1* or something, meaning anything on the 1.1 track
   but not necessarily the final REC version?  More complicated, but
   still probably an improvement would be VERSION=1.1-20120601+,
   meaning the given version or anything later (including the REC).

Sec 3.2.4:
   I don't really like requiring the overflow indicator even if
   there may be no rows for MAXREC=0.  I'd say if the overflow
   indicator is returned it means that at least one row would be
   present in a real query, since this is the normal overflow
   semantics.  But services may omit the the overflow indicator
   without implying anything about the number of rows.

Sec 3.2.5:
   UPLOAD=table1,http://example.com/t1,table1,http://example.com/t2
                                            ^
   typo, second "table1" should read "table2".

Sec 4.1:
   TBD item about whether result must be named "result" - I don't think
   there's much to be gained by mandating this, the UWS service will
   supply a redirect anyway (doesn't it?), so the client knows the name.

Sec 4.4:
   What's the purpose of requiring a QUERY_STATUS info before the TABLE?
   The possbilities are:

      Success:
           <INFO name="QUERY_STATUS" value="OK"/>
           <TABLE/>
      Error detected early:
           <INFO name="QUERY_STATUS" value="ERROR"/>
           <!-- no table -->
      Error detected late:
           <INFO name="QUERY_STATUS" value="OK"/>
           <TABLE/>
           <INFO name="QUERY_STATUS" value="ERROR"?
      Overflow:
           <INFO name="QUERY_STATUS" value="OK"/>
           <TABLE/>
           <INFO name="QUERY_STATUS" value="OVERFLOW"/>

   The only thing an OK status means is that a TABLE is following, but
   you can tell that by finding the table.  The INFO you're interested
   in is the last one in the results resource, which is either after
   a TABLE or the only thing there.  So, you could ditch the early
   INFO and just require a single one, after any TABLE element (if there
   is one).

   In any case, the wording does not accommodate an early detected error:
   "must contain a RESOURCE ... containing a single TABLE" and
   "RESOURCE ... must contain, before the TABLE element, an INFO..."
   should be modified to take account of the fact that in case of an
   early deteced error, no TABLE will be present.  I made a similar
   comment on TAP section 2.9 at 
   http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/TAPImplementationNotes

   The text "... containing a single TABLE ..." is probably wrong on
   another count too, that resource might want to contain multiple tables
   (I believe this is allowed for in TAP/PQL).

Mark