DataLink inputParam PARAM/@value

[Markus Demleitner]

Hi Mark,

On Mon, Nov 20, 2017 at 10:30:23AM +0000, Mark Taylor wrote:
> On Mon, 20 Nov 2017, Markus Demleitner wrote:
> > On Fri, Nov 17, 2017 at 11:06:41AM +0100, Carlos Rodrigo wrote:
> > > In practice, trying to define how to build a meaningful interface
> > > (let's say, a form) just using a "metadata" response has several
> > > subleties when we really think of real cases.
[...]
> My general feeling on this sort of thing is that it's hard to come
> up with external descriptions that do a good job
> of encoding constraints on linked sets of parameters.
> MIN, MAX and OPTIONS are probably reasonable, though even with those 
> there's scope for abuse and confusion; e.g.
> 
>    % curl -s 'http://dc.zah.uni-heidelberg.de/boydende/q/dl/dlmeta?ID=ivo%3A//org.gavo.dc/%7E%3Fboydende/data/fits/HAR081_004308.fits' | xmllint -format - | grep -A5 POLYGON
>       <PARAM arraysize="*" datatype="double" name="POLYGON" ucd="phys.argArea;obs" unit="deg" value="">
>         <DESCRIPTION>A polygon (as a flattened array of ra, dec pairs) that should be covered by the cutout.</DESCRIPTION>
>         <VALUES>
>           <MAX value="13.5628982448 -74.8092154585 11.8908923667 -72.0023786878 2.6858408712 -72.2229858075 2.6979056912 -75.0567925826"/>
>         </VALUES>
>       </PARAM>
> 
> - as a human I can probably guess what that means, but I'd never
> have thought to write code that could understand it if I hadn't 
> seen this kind of example.

I give you that this is a bit of a perverse example (and I've argued
against that specific syntax myself), but it also illustrates why we
simply need this sort of thing: When there isn't a human consuming
the markup but a machine doing something for the human and the human
can't be bothered to read through all the gobbledigook (whether
ostensibly human-readable or not) coming back from the network.

In this particular case, a client will need it to provide some sort
of sky view on which a human can do a cutout -- in this situation you
don't want to download a complete dataset, but you need to now what
area it (roughly) covers on the sky nevertheless.

Another case where uniform and expressive declaration of service
parameters would really be great include all-VO searches that
slightly go beyond the basic parameters a standard gives (think
theoretical spectra, where a client needs to work out what to pass to
what for, say, logg).

> As a builder and to some extent user of UIs, I'm generally more 
> in favour of good human-readable documentation provided by the service
> (per-parameter descriptions of value constraints, comprehensible
> error messages for bad inputs).  Trying to specify (not to mention

If the human is the direct consumer of the service, this may be true.
But I still have to say (as a consumer of various kinds of resource
descriptions) I see a higher chance of such documentation being
halfway useful and complete if you give people a schema they can
essentially fill out (name, unit, range, ucd of a parameter) than if
you ask them to produce free text (which is also far harder to format
into something quickly comprehensible if people want to use not just
two but 200 services at a time).

> to use on server and client side), a machine-readable language for 
> describing constraints is in my view likely to lead to syntax
> which is pretty complicated but still unable to capture all the 
> things you need to say.  I'm afraid my recollection of the details
> of PDL does not dissuade me from that opinion.

Well, I'm not saying PDL doesn't need some development, but I'm quite
sure we're not that far away from a formalism that makes simple things
(reasonably) simple and complex things possible.  

I think VOTable and TAP_SCHEMA nicely show the advantages of
machine-readable column (and partly table) metadata.  Let's have that
for service metadata, too, if we can.

         -- Markus