DataLink inputParam PARAM/@value

[Markus Demleitner]

Hi Mark,

On Tue, Nov 14, 2017 at 04:28:19PM +0000, Mark Taylor wrote:
> I'm taking my first thorough look at DataLink with a view to writing
> a client.  It mostly makes sense, but I have a question about the
> use of the PARAM elements in the inputParams GROUP within a
> service descriptor RESOURCE.
> 
> According to VOTable, PARAM elements must have a @value attribute.
> But the @value doesn't seem to serve any purpose in an inputParams
> GROUP, since the PARAM is just there to describe arguments that
> are to be supplied, in some other way, to the described service.

Oh, it does -- and it's just a tiny wee bit cheesy.

Essentially, PARAMs that can or must be filled (there's no way for a
machine client to distinguish between the two cases yet; I am hoping
for a VO-DML-based annotation there) have value=""; the rationale is
that PARAM/@value is, in effect, TABLEDATA-encoded[1] and in TABLEDATA,
an empty string is always NULL since VOTable 1.3.

If, on the other hand, @value is non-empty, then this value should be
included in the query literally (or after parsing and
TABLEDATA-serialisation, which should end up with an equivalent
result).

The classic use case is in a datalink service response.  Say you
asked for the dataset ivo://example/data?GW150914.

When the datalink response includes processing service declaration,
it's very likely that you'll want to reference the dataset in some
way, and PARAM/@value is how you'd do this.  For instance:

  <RESOURCE ID="deabonwl" type="meta" utype="adhoc:service">
    <GROUP name="inputParams">
      <PARAM arraysize="*" datatype="char" name="ID"
        ucd="meta.id;meta.main" value="ivo://example/data?GW150914"
        <DESCRIPTION>The pubisher DID of the dataset of interest</DESCRIPTION>
      </PARAM>
      <PARAM arraysize="*" datatype="char" name="L_LEVEL" 
        ucd="stat.likelihood" value="">
        <DESCRIPTION>Likelihood level to generate a contour for.</DESCRIPTION>
          <MIN value="1e-7"/>
          <MAX value="1e-1"/>
        </VALUES>
      </PARAM>
    </GROUP>
    <PARAM arraysize="*" datatype="char" name="accessURL" 
      ucd="meta.ref.url" value="http://example.astro/ligo/soda"/>
    <PARAM arraysize="*" datatype="char" name="standardID" 
      value="ivo://ivoa.net/std/SODA#sync-1.0"/>
  </RESOURCE>

[I note in passing that that would be a valid SODA service that just
happens to not have any of the currently defined standard SODA
parameters]

While in this case you could arguable still have operated with @ref
(I'd at least discourage that, though), it's not unlikely that the
processing service doesn't actually receive the datalink pubDID but
instead use some other, internal identifier, the form of which is
only known to the remote datalink service; in that case, the
respective PARAM might look like this:

      <PARAM arraysize="*" datatype="char" name="ID"
        ucd="meta.id;meta.main" value="external/GW150914.vot"
        <DESCRIPTION>Internal dataset identifier</DESCRIPTION>
      </PARAM>

-- with the "just include whatever is in @value" policy, clients just
don't have to bother.

I've wondered for a bit whether the should be an update to the
datalink document just trying to clarify the various aspects a bit.
Should there?

> One other point: at the end of Section 4.3, it says
> 
>    'This PARAM would be added to the GROUP name="input" of the service
>     description.'
> 
> I think that should read 'name="inputParams"' - is that right?

Indeed.  Volunteers for pushing through an erratum?

        -- Markus

[1] I think VOTable 1.4 should explicitly say that somewhere,
incidentally.