[SIAv2] query params

[Markus Demleitner]

Dear DAL list,

On Tue, Nov 12, 2013 at 03:17:53PM -0800, Patrick Dowler wrote:
> CIRCLE <long> <lat> <radius>
> POLYGON <long1> <lat1> <long2> <lat2> ...
> 
> an instead of the BOX (from STC) that is somewhat complex to do
> correctly, I propose:
> 
> RANGE <long1>/<long2> <lat1>/<lat2>
> 
> which uses the range syntax supported by the BAND and TIME parameters.
> 
> So, a "conesearch" kind of query is POS=CIRCLE 12 34 0.5, for example.
> 
> This would make SIZE obsolete (in the multi-dimensional world, it is
> semantically ambiguous) and I this whole line of reasoning would kick
> REGION=<STC-S string> out entirely.
> 
> The result is that SIAv2 query parameters would be POS, BAND, TIME,
> and POL (plus I heard arguments about the redshift axis needing a
> REDSHIFT param).
> 
> The actual syntax (separators between terms/numbers is TBD, and I
> know there have also been differences of opinion abut the range
> syntax with /) but Daniel Durand and I wrote a bunch of examples on
> my whiteboard and it looks very simple and comprehensible (including
> using the range syntax within the POS=RANGE ... construct).
> 
> 
> Comments?

Apologies for repeating points I already made, but there's an aspect
here that's I'd actually like to comment on: The thing with
"comprehensible".

I don't believe "comprehensible" parameter syntax ought to be a
design goal.  "Machine readable", on the other hand, is IMHO of
utmost importance: We're talking about machine-to-machine protocols
here.  As analogy I offer that I doubt many of you have ever manually
spoken SMTP (say), and yet you're sending mails all the time.  So: as
long as interfaces can reliably *construct* protocol requests, the
requests themselves can be as butt-ugly and incomprehensible as you
like [1].

For clients to be able to do just this, I consider it crucial that
the remote machine can figure out the syntax (and preferably
semantics) of well-formed parameters.  And don't underestimate the
necessity for service-specific extension parameters.


So, again: *if* you insist on syntax for the "standard" parameter
values (and I wish you didn't),

(1) please include some mechanism in the spec that lets people define
the sensible ranges (PARAM VALUE probably doesn't quite cut it with
complex parameters, if only because VOTable MIN and MAX don't make
much sense for string-valued parameters), and

(2) clearly state whether custom parameters should use atomic VOTable
types or whether they should follow the syntax of the standard
parameters.  In the latter case, figure out a way how these custom 
parameters can communicate the legal syntax(es) and again the
range of acceptable values [2].

> (for whatever input values they receive) then it is another way to fail. We
> certainly would need *and do not have* a way to describe which coordsys
> values are supported by services. In Hawaii, I think we concluded that in

Well, for metadata replies in VOTable, I claim we do...

Cheers,

         Markus

<soapbox>
  Ceterum censeo _MIN/_MAX with atomic values still is by far the
  simplest, most robust, and, ah, well, comprehensible mechanism for
  specifying ranges, and it's easily extensible to more complicated
  compounds (_STEP, _COOSYS, _REFPOINT, _CENTER, _SIZE...), with
  straighforward ways for clients to figure out a service's actual
  capabilities.  I'll only shut up with this if someone shows me a
  use case that's not covered by this but that works with reasonably
  complex parameter syntax.  Or gives another reason why this is
  undesirable.
</soapbox>


[1] Well, in a footnote I may qualify this: Plain-text-readable
protocols are great for debugging.  So, making things wantonly
unreadable *cough*Office Open XML*cough* is bad, too, of course.  But
that's not what we'd be talking about when we're using atomic
parameters, right?

[2] The reason I'm insisting on communicating the acceptable values
is that the top request I get for user interfaces is "sample values"
or "pre-filled queries".  And I often get the horror vacui myself:
The scary empty input box for which I have no idea what to enter. A
friendly "this should be between 40 and 5.38382e7" can make the
difference between a frustrated and a delighted user.