[DALI] DAI-examples markup

[Patrick Dowler]

OK, so I am in favour of enough RDFa lite markup so that all the params 
for an example can be included with what we write in DALI. Generic code 
can extract "complete" example requests; I have written it and it is 
pretty simple.

Markus favours each spec saying how to use property attributes to encode 
examples specific to that spec.

Neither what is currently written or what Markus proposes is enough to 
tell someone what to do if they create a web service with 2 or more 
different capabilities as they would have oe base url, one /examples 
document, and examples would be for one of those capabilities.

At a minimum, we need either a resource url or a capability to go with 
each example; we could allow it to be absent if there is only one 
capability.

In general, we need a tie-breaking vote or three on whether 
DALI-examples should be complete or a starting point completed in the 
service spec.

thanks in advance,

Pat

On 04/25/2013 12:30 AM, Markus Demleitner wrote:
> Dear DAL folks,
>
> Let me briefly make my point again -- sorry if I'm boring you.
>
> On Wed, Apr 24, 2013 at 03:10:33PM -0700, Patrick Dowler wrote:
>> So, DALI-examples specifies how to markup an (xhtml) document so the
>> exmaples for using the service are machine-readable. I have written a
>> really simple bit of code that extracts the examples so they can
>> actually be executed.
>
> Well, when I wrote the /examples for TAP
> (http://volute.googlecode.com/svn/trunk/projects/dal/TAPNotes/TAPNotes-fmt.html#tf-examples)
> my goal was not to allow clients to execute something (though it may
> be a side effect); the goal is to support clients to support the
> *users*, with the prime use case of example queries that, for
> TAP/ADQL, are IMHO crucially important.  In this concrete case, the
> goal was, true, to let machines extract the queries, but not to
> actually execute them but to show them to the user within their UI,
> complete with a means for her to read associated prose.
>
> So, I guess that's the first thing we should agree upon -- what's the
> purpose of what /examples returns:
>
> (1) Documentation for the user, marked up in a way that clients can
> present it in a structured way.
> (2) More generic documentation that allows, e.g., validation of the
> type "is that documentation still valid?"
> (3) If both, how much "inconvenience" for (1) or (2) are we prepared
> to accept to support (2) or (1), respectively.
>
> A case in point for the kind of issue that comes up with (3) is the
> worry I've pointed out on
> http://wiki.ivoa.net/twiki/bin/view/IVOA/DALI1RFC, starting with "I
> don't think the base-url specification..."
>
>> base URL for the service (to have found the <baseURL>/examples doc)
>> so they don't need #2 and #3, but since a service could have multiple
>> types of jobs with different resource URLs, all under the same base
>> url, and with different behaviour/semantics, they cannot actually
>> know how to execute the example without more information.
>
> Right, and hence my suggestion that service specs that need that
> kind of thing define this in their private vocabulary (and again,
> preferably in "domain terms" rather than generically, e.g.,
> "wavelength" rather than "a float-valued parameter called BAND").
>
>> A3: is there a 3rd option? We have to assume that the examples
>> document contains examples for using different sync or async
>> resources that make up a  service...
>
> My suggestion in a single sentence: "DALI should just say it's XML
> that should be renderable by common HTML engines with a specific,
> restricted kind of RDFa compatible markup and define the example,
> name, and continuation properties, leaving everything else to
> concrete protocols".
>
> Cheers,
>
>          Markus
>
> .
>

-- 

Patrick Dowler
Canadian Astronomy Data Centre
National Research Council Canada
5071 West Saanich Road
Victoria, BC V9A 2L9

250-363-0044 (office) 250-363-0045 (fax)