DALI 1.1 working draft available

[Mark Taylor]

Hi DAL,

On Mon, 8 Feb 2016, François Bonnarel wrote:

>      This email to advertize you that the DALI 1.1 working draft, edited by
> Pat Dowler is available since last week on the IVOA website, in the
> "Standards" section.

I have some comments.  For reference, the version I'm commenting on is
WD-DALI-2015-10-27, from http://www.ivoa.net/documents/DALI/20151027/.


Rubric:
   There is an extra "Status of this Document" section *after* the
   Table of Contents that claims it's a REC - should be removed.


Sec 2.3.3:
   The example of the DALI-examples RDFa property "generic-parameter"
   in this section uses what is obviously a TAP-based example.
   But I *think* we eventually decided (following Markus's plan not
   Pat's) to provide examples for TAP specifically using TAP-specific
   properties "query" and "table" rather than the "generic-parameter"
   as here (the current TAP 1.1 draft in volute, projects/dal/TAP/TAP.tex
   r2949, backs this up).

   That makes this example a bit misleading.  Perhaps it would be
   better to replace it with a DALI-example snippet for a protocol
   that is actually expected to use property="generic-parameter".


Sec 2.3.2, 2.5:
   The deprecated term "IVORN" should be replaced (by "IVOID" or
   "IVOA Identifier", perhaps with a reference to the Identifiers
   document).


Sec 3:
   This asserts "A DAL job is defined by a set of parameter-value pairs",
   and goes on to give examples like "FOO=bar", but it doesn't actually
   discuss anywhere how these parameters are passed from client to
   service.

   It is generally done using either the application/x-www-form-urlencoded
   MIME type in the query part of a URL for a GET request
   (?p1=v1&p2=v2...) or the multipart/form-data MIME type
   in the body of a POST request.  POST with
   application/x-www-form-urlencoded in the query part may also be
   permitted.  The only place I know these MIME types
   are defined is written down is in the HTML standard:
   https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4

   This is standard practice, so maybe "obvious", but it might be
   a good idea to make it explicit here, so it's easier for
   DALI client standard authors and implementers to know where to
   go when they're trying to remember how you're supposed to encode
   embedded spaces etc.

   This affects section 2.1 as well, where it says that you can
   POST additional parameters to a given resource, but is not
   explicit about how to do that.


Sec 3.3, 3.3.1, 3.3.2:
   Integer, real and boolean value representation is mandated here
   to be done in accordance with the XML Schema Datatypes standard.

   That makes sense for specifying parameters in
   application/x-www-form-urlencoded or multipart/form-data form
   as part of an HTTP GET or POST, but not if the values are
   encoded for output in a VOTable document, since VOTable
   has its own encoding rules.  It's kind of obvious that that would
   be the case, but since sec 3.3 explicitly says that it's
   talking about the cases "as parameter values when invoking simple
   services, as data values in response documents (e.g. VOTable), etc"
   it would be better to be explicit here about exactly when
   these literal representations are to be used.


Sec 3.3.3:
   The ISO-8601-like format mandated here is (admittedly, informally)
   written as follows:

      YYYY-MM-DD['T']hh:mm:ss[.SSS]

   but following expected (by me, anyway) usage of square brackets,
   that doesn't seem to match the textual description of an optional
   time part.  I think this would be closer to what's intended:

      YYYY-MM-DD['T'hh:mm:ss[.SSS]]

   The cited references (FITS and STC) both allow arbitrarily many decimal
   places for the seconds part.  If we want to follow that, it should
   say something like

      YYYY-MM-DD['Thh:mm:ss[.SSS...]]

   and it would be a good idea to add an example where the number of
   decimal places is not equal to 3.  Otherwise (if decimal places
   are supposed to be exactly either 3 or 0) there should be an
   explicit comment to that effect.


   The text says

       "Date and time values must be represented using the [iso8601-like]
        convention established for FITS"

   and later

       "In cases where values may be expressed using Julian Date (JD)
        or Modified Julian Date (MJD) ..."

   which looks like an inconsistency, but it maybe just needs more
   careful wording to indicate what's meant (though I'm not actually
   sure what that is - see the next point).

      "Timestamp values serialised on VOTable must have the following
       metadata in the FIELD element:
       datatype='char' arraysize='*' xtype='timestamp'."

   This looks like it's saying that if service providers want to
   return data tables with columns containing date/time information,
   they MUST use the iso8601-like format described here,
   and not e.g. MJD, JD, decimal year etc.  I suspect that's not
   the intention, in which case it needs to be reworded.
   If that is the intention, I don't think it should be.

   See below for more comments about the attribute values mandated here,
   and a separate posting for more comments about timestamps and xtypes.


Sec 3.3.4, 3.3.5, 3.3.6, 3.3.7:
   These sections all mandate that the datatype attribute of the
   corresponding FIELD element must be "double".  Is there a good
   reason that services cannot be permitted to use float (or even
   an integer type) here?  For large results, unwarranted
   double precision might mean significantly larger output tables,
   and could also be misleading (suggesting more precision than
   the values support).  It may also make it difficult for
   services which have this data in existing tables in a
   numeric type other than double (they'd have to rewrite columns
   rather than just annotate them appropriately).

   I seem to remember that the corresponding requirement in Simple
   Cone Search has caused trouble in the past, leading to services
   that fail validation, even though there's nothing really wrong
   with them.


Sec 3.3.3 and 3.3.7:
   These sections mandate that the arraysize attribute of the
   corresponding FIELD element must have the value "*".
   I don't see any good reason that services should not be permitted
   to use some other length specification that does the same job
   (e.g. arraysize="19" for iso8601-alike timestamps).


Sec 4.1:
   Long lines in table (Content-Length and Last-MOdified entries)
   overflow in PDF document.

   "Last-MOdified" -> "Last-Modified"


Sec 4.4:
   name = "QUERY_STATUS"2.  - erase the rogue '2'.

   Long lines in table (ERROR and OVERFLOW entries)
   overflow in PDF document.

I have some other comments related to timestamps and xtypes.
I plan to write these in a separate message, crossposted to the
time domain mailing list.

Mark

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