DALI-1.0 RFC

This document will act as RFC centre for the Data Access Layer Interface 1.0 specification. The current version of the document is available at:

http://www.ivoa.net/Documents/DALI/index.html

Review period: 2013-02-22 to 2013-03-22

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your WikiName so authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Discussion about any of the comments or responses should be conducted on the DAL mailing list (dal@ivoa.net). However, please be sure to enter your initial comments here for full consideration in any future revisions of this document.

Implementation details

Links and description of existing interoperable implementations

Comments from the Community

Points by MarkusDemleitner, 2013-03-14

• (Throughout) I'd prefer "see Section 3" rather than "see 3" in cross references

• p. 7/8, In the example starting with "POST http://example.com/base/async-jobs", "<" characters are used to indicate (I guess) a response; In the following example, no such indication is provided. I'd suggest some other way to distinguish query from response (though I can't make a useful suggestion here), or even none, which would still be better than the current, confusing status.

• At the bottom of p. 8 you let people POST parameters after job creation. Paul Harrison (as one of UWS' parents) thinks that the libertinage with posting parameters has gone a bit too far. I tend to agree with him; even if we want people to post to parameters, I think we should really clarify the semantics (if only by referring to the later chapter on parameters). In the TAP implementation notes, there's some language: https://volute.googlecode.com/svn/trunk/projects/dal/TAPNotes/TAPNotes-fmt.html#uc-initpost Frankly, I'd say we should restrict what UWS allows, and probably to just POSTing to /parameters.

• p. 9, top "A concrete DAL service specification will specify one or more asynchronous ..." -- I'd say that should be "zero or more" after what's said above. The same applies to "A concrete DAL service specification will specify one or more synchronous..." a bit further down on that page.

• p. 9, "The parameters used to specify the job are the same for synchronous and asynchronous DAL jobs." -- doesn't that contradict the statement above that services are free to do one thing on sync and something else on async?

• p. 10, "no other vocab attributes are allowed in the document, for example:" -- I propose to move the "no other..." phrase behind the example; the example is for what's in front of the semicolon, not for the "no other" part.

• p. 10, "located inside the first element (the one with the vocab attribute) would indicate the presence of a single example." -- I'd rather just write "would contain an example referrable via the x fragment identifier." I'd leave out the language about "first element" and "single example" -- it confused me, for one.

• p. 11, I don't think the base-url specification is a good idea (if a machine has the examples URL, it has the access URL). And anyway, we really should not require it in each example -- that would make for extremely tedious reading (think of TAP examples: "On our http://dc.g-vo.org/tap endpoint, you can query...", and that 20 times?)

• p. 11, http-action property -- about the same thing. I don't even think we should have it, but I'm sure we must not require it.

• p. 11, generic-parameter -- for the record, I'm not a big fan of generic-parameter, either -- examples should IMHO be examples for a concrete protocol, known to the client. Hence, the semantics should be up to the concrete protocol (TAP talks about a query, SIAP about a region of interest -- and not about POS and SIZE parameters, that's up to the client to figure out --, SCS about center positions and cone sizes -- and not about RA, DEC, and SR). With http-action and generic-parameter, /examples moves in the direction of a machine readable standards markup language, and I don't think we want that.

• p. 12, "element with a vocab and examples as described above. If present, links back to a parent examples document must not be marked up with continuation attributes as this would create a loop." -- hm; we should ponder the implications of this. This means that the "primary" examples document is somehow special. That may be what we want, but we should be clear on this. I'd prefer things to be symmetric, but if we make such a rule, why not state clearly: "To ward against loops, documents referenced using continuation MUST NOT contain continuations themselves"?

• p. 14, "services may be registered and described without such an extension." -- Yes! In the early TAP takeup, the misconception about this kept many people from registering TAP services although that would have been possible even without TAPRegExt. Hence, I'd like to add here: "The use of standardID -- which should contain the IVORN of the standard a capability adheres to -- does not imply a particular xsi:type." Or something like that.

• p. 14, VOSI-tables -- should we explicitely state that when tables is not implemented, services must return 404 there?

• p. 19, "If a client requests a format by specifying the mimetype [...] the response that delivers that content must set that mimetype in the Content-Type header." I've always considered that requirement as fairly funky (and, by the way, an implementation hassle). So, I'd suggest we add some motivation here. Is this actually just about pulling thorugh text/xml in hopes that the browser does something sensible with this as opposed to application/x-votable+xml?

• p. 22, "an HTTP status code (??)". Well... If we want to specify anything here, we should list the HTTP status codes we want to see, which is somewhat tricky given there could be proxies, etc. The reason I wanted this in is that I'd liked to have seen that errors actually cause HTTP error codes -- I still maintain it's unwise to return an error message of any kind with a 200 HTTP status code (excepting, of course, the /error document in UWS); it's an abuse of HTTP. If we cannot agree to change what the current DAL protocols do, we should just say "Working DAL services always return 200 OK, even if the execution ended with an error, as long as they can produce a VOTable (that might contain an error message), or a redirect (302 or 303) eventually resolving to such a resource. Clients must nevertheless be prepared for other status codes, in particular 401, 404, and 500." Still sounds weird to me.

• p. 22, "Successfully executed requests should result in a response with HTTP status code 200 (OK)..." Why only "should"? Also, we should add "eventually" here, since the immediate response could also be a redirect.

• p. 23, "If the error document is being returned directly after a DALI-sync request, the service should use a suitable status codes (e.g. 4xx or 5xx for HTTP transport)" -- uh, I'm confused. The stuff I wrote above (about 200 codes for VOTable error messages) appeared to be what came out of the Sao Paulo DALI session. If that's negotiable after all, can we just say "Any error messages come with non-200 status codes" or similar in the section introduction?

• p. 23, "...RESOURCE element identified with the attribute type="results", containing a single TABLE element..." -- what do we gain by requiring this to be a single table? This is, after all, a fairly serious limitation, and I could well imagine some IVOA-sanctioned protocol for services like NED or VizieR, where the result of the query contains many "fragments" from different sources that have different columns. So, what would we break if we lifted this limitation?

Comment by Arnold Rots

In an attempt to be more specific, I suggest replacing the following text in Section 3.1.2:

Values never include a time zone indicator and are always interpreted as UTC [17].
In cases where values may be expressed using Julian Date (JD) or Modified Julian Date (MJD), these follow the rules for double precision numbers above and may have additional metadata as described in 4.4.

by:

Values must never include a time zone indicator and shall be interpreted as stated below.
In cases where values may be expressed using Julian Date (JD) or Modified Julian Date (MJD), these follow the rules for double precision numbers above
and may have additional metadata as described in 4.4.
All date-time values (ISO-8601, JD, and MJD) shall be interpreted as referring to time scale UTC and time reference position UNKNOWN, unless either or both of these are explicitly specified to be different [17].

-- ArnoldRots - 2013-03-15

The VAO has reviewed this document and, aside from Arnold's comment above, has no further comments to make.

-- MatthewGraham - 2013-03-19

• Sample comment (by BrunoRino): ...
  • Response (by authorname): ...