Service descriptors defining the difference between a required parameter and an optional parameter

[robyww]

When a service descriptor defines a parameter there seems to be no way to know if the parameter is require or if it is optional. This is important for a UI that reads the service descriptor and provides the user a way input those parameters.

This is not a suggestion of syntax, but just an illustration of a solution. I added an isOptional in the third parameter below.

  <RESOURCE type="meta" utype="adhoc:service">
    <DESCRIPTION>a service</DESCRIPTION>
    <GROUP name="inputParams">
      <PARAM name="abc" datatype="char" arraysize="*" ref="col_0" value="">
        <DESCRIPTION>a ref param</DESCRIPTION>
      </PARAM>
      <PARAM name="efg" datatype="char" arraysize="*"  value="123">
        <DESCRIPTION>a required param</DESCRIPTION>
      </PARAM>
      <PARAM name="mn" datatype="char" arraysize="*"  value=""  isOptional="true">
        <DESCRIPTION>a optional param</DESCRIPTION>
      </PARAM>
    </GROUP>
    <PARAM name="accessURL" datatype="char" arraysize="*" value="http://a.b.com/aEndpoint"/>
  </RESOURCE>

[Bonnarel]

This is surely useful. I see a solution different from adding a new attribute to PARAM. FIELDS and PARAMS have a rather seldom used attribute called "type" (no datatype, utype or xtype). It's used by clients as a behavior guid. Current values are "hidden", "location", "trigger". We could add type="optional" and that's it. However the status of this attribute in VOTable is rather unclear. This could be revisted and clarified in VOTable. What do you think ?

[robyww]

Yes, that sounds good. I am sure you know better how to implement it than I do. As long as there is a way to determine an optional parameter.

[cmzwolf]

In PDL, the parameter description comes with an attribute "dependency" which can take REQUIRED or OPTIONAL value (cf. section 5 of https://ivoa.net/documents/PDL/20140523/REC-PDL-1.0-20140523.pdf). What about a better integration between PDL and DataLink?

[Bonnarel]

Can Roby tell us whether the parameters in these services will be required or optional in all contexts or if this quality depends of other parts of the query ? The solution may be different.

[robyww]

Well, that is more complex than what I was thinking. Since the UI does not really know about context that much I would say the answer is.

required or optional in all contexts

They way firefly would us a service descriptor like this is it would present the user with a panel and not allow the search to happen until the required parameters were entered. It would us the optional only if the user enters them. In some cases we can infer defaults. So in the optional case the user might have the option of removing the default value.

[pdowler]

This comes up in even the simplest use cases and I'm a little embarrassed we didn't think of it. The other potentially related thing we cannot currently describe is the cardinality: is a param single-valued or can multiple be submitted in the request?

In a SODA service descriptor, one could use a static template and list all the params: pos, circle, polygon, band, time, pol. Users could use the ones they like, so I think we implicitly assumed that all params were "optional" in this sense. That certainly fits with the fact that you woould not use both POS and CIRCLE at the same time and services could (CADC SODA does) reject that kind of repeated usage (multiple spatial cutouts).

So, to me the question could be reduced to "which params are mandatory?" I looked at the VOTable schema for attributes we could (ab)use, but there isn't anything obvious. We do use utype="adhoc:service" in the resource so we could think about using PARAM utype="something" to indicate mandatory vs optional params (with default when absent: optional). I don't think service params obviously benefit from referring to a field in a model (the nominal utype attr usage)...

Option 1: abuse utype attribute to say required (vs optional), eg utype="adhoc:required"

Option 2: abuse utype to specify cardinality: utype="cardinality:0..1" for optional & single value, then 1..1, 0..*, and 1..* for the other possibilities.

Option 3: defer issue until some useful support/param refactoring is added to VOTable

I'm inclined to defer rather than abuse current votable mechanisms.

[robyww]

I would prefer not to defer the issue. To work well the UI really needs to know if it is a required parameter. I am fine with just specifying required, in some ways that is cleaner.

is a param single-valued or can multiple be submitted in the request

I had not thought of that but I agree it is very important.

The goal in this whole thing is for a user to be able to consistently get results back and not have to experiment with every search. They more we can specify about how to build the URL the better.

[msdemlei]

On Tue, Oct 19, 2021 at 03:57:08PM -0700, Patrick Dowler wrote:

This comes up in even the simplest use cases and I'm a little embarrassed we didn't think of it. The other potentially related

Well, it's not that we forgot about it. It's that at least I had hopes that DM/VODML would let us use PDL (that can even describe rather complex but common relationships between parameters like "if you give POS, REFSYS is mandatory, else it is forbidden"; cf. https://ivoa.net/documents/PDL/) to annotate SODA groups.

After all these years I'm rather sure that won't happen any time soon, and the annotation schemes proposed over in DM don't seem to be great for that use case either.

I'd hence say we're morally entitled to build something ourselves.

I can see two reasonably straightforward ways to make this happen that don't require VOTable changes.

One is inspired the original mechanism for VO-DML annotation, where an external group that adds advanced annotations to the PARAMs. For instance:

<GROUP utype="adhoc:param-annotation" ref="procsvc">
  <PARAMref ref="par1" utype="adhoc:mandatory"/>
  <GROUP utype="adhoc:preset-with">
    <PARAMref ref="par2" utype="adhoc:field"/>
    <PARAM name="_1" utype="adhoc:default" value="27"/>
  </GROUP>
</GROUP>

<RESOURCE ID="procsvc" name="proc_svc" type="meta" utype="adhoc:service">
  <DESCRIPTION>An interactive service on this dataset.</DESCRIPTION>
  <GROUP name="inputParams">
    <PARAM datatype="float" name="par1" id="par1"/>
    <PARAM datatype="float" name="par2" id="par2"/>
  </GROUP>
  ...
</RESOURCE>

This would say "par1 is mandatory" and "in forms, par2 should be preset with 27" (which is another use case I've seen pop up in the wild).

This may look a bit awkward, but in practice it's actually rather pleasant to work with (I can say that because I implemented most of the original GROUP/utype scheme of VODML annotation). This is really flexible and could be extended to support all of PDL if we want that.

The alternative I'd see would be to use LINK children of the PARAMs. We could simply commandeer the action "rdf" to say "it's something like an RDF triple". We'd then use content-role as the RDF property and, where necessary, value as the RDF object. That way, the declarations above could look like this:

<RESOURCE ID="procsvc" name="proc_svc" type="meta" utype="adhoc:service">
  <DESCRIPTION>An interactive service on this dataset.</DESCRIPTION>
  <GROUP name="inputParams">
    <PARAM datatype="float" name="par1" id="par1">
      <LINK action="rdf"
        content-role="#mandatory"/>
    </PARAM>
    <PARAM datatype="float" name="par2" id="par2">
      <LINK action="rdf"
        content-role="#preset-with"
        value="27"/>
    </PARAM>
  </GROUP>
  ...
</RESOURCE>

Here, I've assumed we define content-role as being relative to a hypothetical vocabulary http://www.ivoa.net/rdf/content-roles that would hold such terms.

The third, obviously cleaner, option would be to enable RDFa in VOTable. Perhaps we ought to do that anyway. Put we can't do that immediately, and I'm a bit reluctant to think too much about that before we've played with cases like these.

I'm inclined to defer rather than abuse current votable mechanisms.

I'd say this shouldn't hold up datalink 1.2; in particular, we'll have to work out if and how this ought to take up PDL.

But that doesn't mean it'll have to wait for 1.2. Let's write a note and implement it (whatever "it" is). Either technique can work without changes to any RECs. And you'll have to Bambi-eye implementors to take it up whether it's in the REC or just in a Note until Datalink 1.2.

      -- Markus

[cmzwolf]

Dear All,

As I wrote some time ago, PDL is really well suited for the use case exposed by Roby: the contraints “DefaultValue” and “BelongToSet” (respectively page 37 and 34 of https://ivoa.net/documents/PDL/20140523/REC-PDL-1.0-20140523.pdf) let service provider tell what is the default value and/or the set of authorised values for a given parameter (and the parameter may be a vector).

The problem is moved from “How do we describe parameters” to “ho do we include PDL descriptions” into the existing IVOA framework (e.g. how to associate PDL-service descriptions with services into registries and/or VOSI extensions OR, on a different philosophy, how to include PDL snippets into elements of other Data models).

I think it is better make an existing wheel go round rather then re-inventing the wheel. And if people want to re-invent the wheel, at least be inspired by an already existing one.

Best,

Carlo.

On 20 Oct 2021, at 01:20, Trey Roby @.***> wrote:

I would prefer not to defer the issue. To work well the UI really needs to know if it is a required parameter. I am fine with just specifying required, in some ways that is cleaner.

is a param single-valued or can multiple be submitted in the request

I had not thought of that but I agree it is very important.

The goal in this whole thing is for a user to be able to consistently get results back and not have to experiment with every search. They more we can specify about how to build the URL the better.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/ivoa-std/DataLink/issues/51#issuecomment-947177052, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAU7J6XF7Q22ECF2CVVLXBTUHX4NJANCNFSM4T3OYZWQ. Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

[mbtaylor]

I've made a suggestion in https://github.com/ivoa-std/VOTable/issues/29 that could provide a clean solution to this; but it's not a quick fix, since it would require a new VOTable version.