[p3t] A thought on DataLink in a JSON-based protocol

[Russ Allbery]

Paul Harrison <paul.harrison at manchester.ac.uk> writes:

> I had had a similarish idea a while back
> https://github.com/ivoa-std/DataLink/issues/53
> <https://github.com/ivoa-std/DataLink/issues/53> - I feel that an
> openAPI description would be way too low level for this description,
> however. You will see that I even made the heretical suggestion that
> perhaps the service description did not need to be embedded within
> VOTable – that removes a lot of problems…

Thanks for this pointer!  This was an interesting discussion.

I'm not entirely sure what you mean by "low level" when it comes to
OpenAPI, since I think of an OpenAPI specification as roughly at the same
level of the current DataLink service descriptor (list of parameters with
their types, MIME type of the response, etc.), just considerably more
comprehensive in the set of things that it can describe.

That said, the more I've thought about this, the more I think that
specifying services using all of OpenAPI would just be Too Much for client
implementors.  The spec allows too many things, trying to implement them
all would be impossible, and trying to select the important bits would
probably be overwhelming.  That leads me back to some sort of simpler
service description, perhaps inspired by OpenAPI and similar languages.

We have a specific interest in an improved service descriptor language
because we would like to be able to specify services that take POST
parameters (in JSON format) rather than GET parameters.  But we definitely
don't need the full structure specified by OpenAPI.  I suspect restricting
the POST parameters to a flat key/value structure may be sufficient for
the ad hoc services that we anticipate, although I'm not positive.

I think the main benefit that service descriptors have from being embedded
in a VOTable is that this allows them to be customized to the specifics of
the VOTable in which they're embedded.  For example, the fixed parameters
may be specific to that particular reply, and the service descriptor
supports linking to specific columns.  I find the way this is encoded in a
VOTable to be a bit awkward, but the functionality feels very important,
including the ability to include it in a TAP result.  We're planning on
using that fairly heavily.

I'm not sure at first glance the best way to retain that functionality if
the service descriptor were served from a different service.  Some sort of
state would have to be carried over from the VOTable in the request for
the external service descriptor to fill in those details, which feels a
bit awkward, or the VOTable-specific service parameters would have to be
separated from the rest of the service descriptor.

I will keep pondering this and might take another pass at it once I get
back from vacation.

-- 
Russ Allbery (eagle at eyrie.org)             <https://www.eyrie.org/~eagle/>