Transition from 'name="this"' to 'utype="adhoc:this"' for service self-description

[Dubois-Felsmann, Gregory P.]

To make things more concrete, I filed a PR on DataLink with a slightly revised version of my suggested language on backward compatibility:

https://github.com/ivoa-std/DataLink/pull/102

Gregory

--
Gregory Dubois-Felsmann | Senior Staff Scientist | Caltech/IPAC
Science Platform Scientist, Vera C. Rubin Observatory
Pipeline System Designer, NASA SPHEREx mission
Mail Code MR 100-22 | Pasadena, CA 91125-2200 | gpdf at ipac.caltech.edu


________________________________________
From: Dubois-Felsmann, Gregory P.
Sent: Friday, March 10, 2023 12:04 PM
To: <dal at ivoa.net>
Cc: Silverman, Judith
Subject: Transition from 'name="this"' to 'utype="adhoc:this"' for service self-description

I (rather belatedly - my apologies) took the time to red-pencil the current DataLink draft this morning, and I noticed what is clearly a long-standing change in the draft vs. v1.0 -- the old recommendation that services providing a self-describing service descriptor annotate it with 'name="this"' in the <RESOURCE> element has been changed to having them self-describe with 'utype="adhoc:this"' instead of the usual 'utype="adhoc:service"'.

I've traced this back to

* https://github.com/ivoa-std/DataLink/issues/21 and
* https://github.com/ivoa-std/DataLink/commit/2ace09d971bb6f21e8577f25ef2d2c55f2730ebc
* https://github.com/ivoa-std/DataLink/commit/522c342ca96b4de106817bb91f50ea8227bf1ff0

I'm very supportive of freeing up "name" for free-form use, so this is good.  However, we have a backward-compatibility issue here that is linked to at least one other standard.

In SIAv2, Section 3.1.2, "SIA {query} Service Descriptor", says:
https://ivoa.net/documents/SIA/20151223/REC-SIA-2.0-20151223.html#toc37
'The DataLink [8] specification describes a mechanism for describing a service within a VOTable resource and recommends that services can describe themselves with a special resource with name=”this”. SIA {query} responses should include a descriptor describing both standard and custom query parameters (if applicable).'
and goes on to provide an example of this usage.

I think SIAv2 presents a key use case for self-description, where client software can use the results from a "MAXREC=0" query, as explicitly recommended in the standard, to provide guidance to users on the useful/available values to supply for certain query parameters (e.g., INSTRUMENT).

As a result, I think we should include in DataLink-1.next a statement like:

'For backward compatibility with DataLink 1.0 and SIA 2.0, client software conforming to the present recommendation should also treat <RESOURCE> elements with type="meta", utype="adhoc:service", and name="this" as self-descriptions, equivalent to type="meta" utype="adhoc:this" name="".  A conforming client should treat the provision of more than one self-description <RESOURCE> element as an error, except that if a service provides exactly one of each of the present (DataLink 1.1 and beyond) and DataLink 1.0 styles, the client may silently ignore the DataLink 1.0 style instance.'

And we should promptly queue a minor change to SIAv2 to change the recommendation therein.
I've filed https://github.com/ivoa-std/SIA/pull/22 for this.

This issue is relevant to active development work at IPAC on an SIAv2 service.

Gregory