Datalink Feedback V: Examples

[Patrick Dowler]

note: working my way backward through the feedback :-)

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.

The mechanisms in DALI-examples are enough to encode a complete usable 
example, including boring boilerplate parameters like REQUEST. 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 any value 
in saying that such-and-such value is assumed if not specified. Just 
include all required parameter/value in the example; if nothing else it 
will continually reinforce that it is a required parameter.

I can elaborate the text a bit and provide an example, using the basic 
markup from DALI-examples.


Pat



On 03/04/14 02:54 AM, Markus Demleitner wrote:
> Dear DAL list,
>
> This is about section 2.2, Examples: DALI-examples.  It currently
> just says:
>
>    DataLink services should provide a DALI-examples resource [1]. The
>    document includes example invocations that show the variety of links
>    that the service can return. This example should have a minimum of ID
>    values, but may have multiple if that is needed to give a
>    representative response.
>
> I think that's a bit terse.  For one, I don't think ID should be a
> generic-parameter for Datalink.  Hence, I'd like to see something
> like:
>
>    For datalink examples, we introduce the property ``dl-id``, which
>    is a value for ID for a service.  To construct an example query,
>    the content of the element marked with dl-id must be passed in ID.
>    [If we *really* have to keep REQUEST: "REQUEST=getLinks is implied
>    and should not be explicitely specified in the example"]
>
>    We also include the property ``dl-endpoint``, the content of which
>    is the value of {links} to be used for the given example.  At least
>    one example should be given for every links endpoint the service
>    supports.
>
>    At least one ``dl-id`` and exactly on ``dl-endpoint`` properties
>    *must* be given in every example.
>
> Furthermore, I think "should have a minimum of ID values" should be
> "should have a miminum of one ID value", but I suspect that sentence
> could go altogether.
>
> What I think would be *really* important is an example for an
> examples snippet.  Maybe like this:
>
> <div vocab="ivo://ivoa.net/std/DALI#examples">
>    <div resource="#cube" typeof="example" id="cube">
> 	  <h2 property="name">Cube example</h2>
>   	  <p>For cubes like <span property="dl-id"
>   	    >ivo://example.org/antenna.fits<span>, the
>   	    <a href="../dlmeta" property="dl-endpoint">dlmeta</a>
>   	    endpoint
>   	    returns links to the source spectra that are not rebinned,
>   	    a cutout service with many parameters, ...</p>
>    </div>
>
>    <div resource="#multi" typeof="example" id="multi">
> 	  <h2 property="name">Multiple IDs</h2>
>   	  <p>If a client passes in multiple IDs -- e.g.,
>   	    <span property="dl-id">ivo://example.org/antenna.fits<span>,
>   	    <span property="dl-id">ivo://example.org/jupiter.xml<span>,
>   	    and
>   	    <span property="dl-id">ivo://example.org/2011-02.csv<span>
>   	    on <a href="../dlmeta" property="dl-endpoint">dlmeta</a> --,
>   	    the union of all links will be returned.  Note that...  </p>
>    </div>
> </div>
>
> What this doesn't include is a capability property; I still feel it
> would clutter the text (IVORNs aren't all that pretty), and I'd be
> happy to just say "The capability ID
> ivo://ivoa.net/std/DataLink#links-1.0 is implied if no capability
> property is given in an example."
>
> This could, in addition, say: "Service validators should get material
> for test queries from the examples endpoint and run their tests
> against every example given."  This would save us a registry
> extension just to have a testQuery; on the other hand, you couldn't
> sensibly give "negative" examples.  Which probably is just as well,
> but we should briefly stop to think if that's what we want.
>
>
> Cheers,
>
>          Markus
>
>

-- 

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

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