Datalink Feedback V: Examples

[Markus Demleitner]

Hi DAL,

On Tue, Apr 08, 2014 at 10:18:42AM -0700, Patrick Dowler wrote:
> I don't think I agree with the idea of each specification defining
> new properties. It makes it harder/impossible for any generic code to
> parse an examples document, capture the DALI-examples metadata, and
> build example service invocations. I would not like to see knowledge
> of the standardID to be required to extract and build the complete
> example.

Here I heartily disagree (and that was the reason why I opposed the
genericParameter property in DALI) -- in what I had in mind for the
examples endpoint, its material is primarily directed towards
*protocol clients*.

Put another way: The point of examples is -- I claim -- not to enable
anyone to build a working query string.  The point of examples is to
allow a protocol client to build a correct invocation (e.g., pre-fill
some form; not that the form will not usually have fields for random
generic parameters).  That is why we should not talk about *generic*
parameters, we should talk about entities of the protocol.

The original use case was TAP: Here, the client must be able to
figure out the query and some label to display to the user.
Everything else is, at best, a nuisance.  It'd suck for a TAP client
to have to go through all genericParameters of REQUEST and VERSION
and whatever else people might put in there to eventually figure out
QUERY (and should qUery work, too, as it does for TAP?).  If it has
QUERY, will it be enough or have operators put in more magic
parameters that they want for this particular example?

The whole idea of using semantic markup is to say what something is
in a given frame.  If examples documents lived in the frame of
protocol design, I'd say, yes, talk about generic parameters.
However, I'd claim they instead live in the frame of protocol *use*,
and there they should name the actual entities (queries, dataset
identifiers, positions, search radii, etc) and leave out
implementation details.

Just as TAP-examples talk about queries and their titles (and hence
use appropriate vocabulary in the current draft), so
datalink-examples should talk about datasets.  In the VO, the proper
way to refer to those is the pubDID, so that's what examples
documents should talk about.

Now -- Can we agree that for *datalink clients*, having explicit
markup would be preferable?

What would use cases for protocol-independent code doing something
with examples be?

> The document does not need to show (for example) REQUEST=getLinks for
> every example; it can be easily encoded in a hidden element so it is
> machine readable but not necessarily displayed... so I also don't see

It's not *that* easy -- this involves CSS, and I had designed
examples such that even very simple HTML formatters as they might
be used in clients would do something useful.  That's why DALI says:

  Javascript or CSS must not be necessary to find and interpret the
  elements specified below.

I give you it doesn't actually say "display", but at least my intent
has been to enable easy inline display of examples.

TL;DR: examples should not allow the construction of query strings,
it should allow pre-filling client forms.

Please holler if you disagree.

Cheers,

         Markus