Datalink Feedback V: Examples

[Markus Demleitner]

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