VOSI 1.1 review

[Markus Demleitner]

Dear GWS,

[if you're on the DAL mailing list as well: sorry for the deluge,
this should have reached you 18 hours ago, but the list isn't gws@,
it's grid@]

I took the liberty of committing some, I claim, content-preserving
markup fixes into VOSI 1.1, rev. 3389.

However, here are some points regarding contents that I'd like to
make and perhaps discuss in Cape Town (what's left after might go to
the RFC page...):

(1) Abstract: "to participate in the IVOA" sounds a bit like 2003.  As does,
now that I re-read it, the entire abstract that doesn't really say what
VOSI actually is about.  How about:

  VOSI (Virtual Observatory Support Interfaces) defines a set of three
  endpoints that allow clients and other VO components to discover
  service metadata and properties from a service rather than from a
  registry.  Specifically, a capabilities endpoint serves information on
  access modes to the service, an availability endpoint informs about
  scheduled or accidental downtimes and their reasons, and a table
  metadata endpoint gives the structure of any table(s) underlying the
  service.  The endpoints are defined in terms of (trivial) HTTP-based
  interfaces and XML schemata defining the responses.


(2) Sect. 2, last paragraph: "When using the REST binding, any HTTP URLs
may be used."  This may be a minor thing, but I think experience has
shown that it's easy to mess things up with this much freedom.  I'd much
prefer if this said:

  In the REST binding, standards SHOULD arrange URL schemes such that
  all endpoints, including the VOSI endpoints, are siblings.  In this
  way, the capabilities endpoint -- which in effect serves as a roadmap
  to the service -- can be located by simply replacing the last
  component of the path in any service access URI and replacing it with
  the literal \texttt{capabilities}.

  The exception to this rule is availability.  The reason for this
  exception is that these endpoints will typically be hosted at a
  physically different location.

(this would need a redactional change further down to fix the
capabilities name).

(3) are you sure you want to keep the huge element names with the full
namespaces?  In registry, we have a few brief introductory text mapping
canonical prefixes to URIs and thus dodge all the ugly typesetting
almost inevitable with long URIs in running text.


(4) Sect. 3.3  says:

  When reporting availability, the service should do a good check on its
  underlying parts to see if it is still operational and not just make a
  simple return from a web server, e.g., if it relies on a database...

I've never liked that language.  If availability ever actually gets
used, clients will probably fire off a large number of requests to it.
Doing actual tests for each of these requests would put a severe strain
on the resources.  I'd much rather read:

  The availability report should reflect the results of an actual test
  of the resource described.  Operators may cache these results for a
  reasonable time span.  Serving an actual availability request should
  be cheap resource-wise, and it should be fast so as not to discourage
  clients from using availability.


(5) Sect 3.4 still has the "detail" parameter.  I still claim this
should be removed.  It doesn't help the client (at least until all VOSI
1.0 services are dead, it would still have to be prepared to process
in-root table metadata, and even after they'd probably want the
one-document form if possible).  It also doesn't help the service, as it
will have to implement the split form even if it doesn't need it.

No, I still claim we can simply say:

  In the REST binding, the tableset metadata may be a hierarchical web
  resource with a registered URL.  In this case, a request to the tables
  endpoint returns a document without \xmlel{Column} or
  \xmlel{ForeignKey} elements.  This signals to a client that detailed
  table metadata is available from child resources of the table
  resource, named with the fully-qualified table name.  For example:

    GET http://example.net/srv/tables/ivoa.ObsCore

  would return a Table document describing the ivoa.ObsCore table.
 
  This is primarily intended for services with a large number of tables
  and/or columns for which a full TableSet document would be
  prohibitively large.

Better for the service -- it will simply choose the representation most
appropriate for the data it serves --, at least as good for the client,
as it just has to inspect the response it gets rather than worry about
possible redirects to discover service behaviour.


(6) In Sect. 4, it says "If such a capability is provided..." for
capability and availability capabilities, where they are made mandatory
above.  I think for consistency we should strike these "if"s.

(7) Some examples have a schemaLocation, some don't...  Anyway, my
recommendation would be to have the files external and include them so
they can be schema-validated before REC-ing the whole thing.  May I?

(8) I'm against including the schemas in the document.  It's wasting a
lot of paper for something nobody in their right mind would ever read,
and it makes for a second place where things would need to get fixed
when there's a problem.


See you soon,

           Markus