Bridging the VOSI-TAP gap (Pt. 1)

[Ray Plante]

Hi VOSI proponents,

A few people (most notably, Tom McGlynn) have noted a gap between the TAP
specification of the getCapabilities() and the specification in VOSI that
makes it unclear exactly how to implement this operation for TAP.  I would 
therefore like to propose specific changes to these documents intended to 
close this gap.  This email specifically addresses VOSI.

The aim is to be more specific in section 2.1 ("Capability metadata") on 
how to return the capability metadata, and in section 2.5 ("Registration 
of VOSI endpoints") on how register the endpoints.  Please note the 
previous discussion in which I recommended that define a additional XML 
schema components for encoding the Capability metadata response (beginning 
with http://www.ivoa.net/forum/grid/0910/0733.htm).  In this message,
I assume my proposed XML schema is acceptable.  In all, I make here 6 
recommendations:

1) Section 2.1:  Mandate the use of the VOSI schema for delivering
    capability metadata.

Replace the paragraph beginning "The service metadata shall be 
represented..." with:

    The service metadata shall be represented as an XML document with the
    root element {http://www.ivoa.net/xml/VOSI/v1.0}capabilities.  (See
    Appendix 1 for the definition the VOSI schema.)  This element must
    contain one or more child {http://www.ivoa.net/xml/VOSI/v1.0}capability
    elements that describe the capabilities of the service.  Given that the
    capability element is defined to be of type
    {http://www.ivoa.net/xml/VOResource/v1.0}Capability, a
    capability element may be represented by a legal sub-type of
    {http://www.ivoa.net/xml/VOResource/v1.0}Capability, in which case, the
    capability element must use an xsi:type attribute to identify the
    sub-type (see section 2.2.1 of [VOResource ref]).

2) Section 2.1: Add a non-normative note explaining the use of standard
    VOResource extensions.

I propose we add the following note within section 2.1 immediately after 
the paragraph re-written by (1).

     Note:
     In order for the service to be recognized as compliant with a
     particular standard protocol (such as Simple Image Access, Simple Cone
     Search, etc.), the Capabilities metadata resource should include a
     capability element with an xsi:type attribute set to the
     standard Capability sub-type for that protocol.  Standard
     Capability extensions, which are documented for each
     protocol elsewhere, provide information that is specialized for the
     protocol.

By "Note", I am recommending that this be typeset according to one of the
styles used currently by some standards to set off non-normative comments
intended to provide clarification to the normative text.

3) Section 2.1:  Recommend including capabilities for the VOSI resources

Insert the following after the Note from (2):

     The list of capabilities should include capabilities describing VOSI
     endpoints as specified in section 2.5.

4) Section 2.1:  Provide an example of a legal capabilities metadata
    response.

5) Section 2.5:  Recommend the use of ParamHTTP as the interface type

Append the following paragraph to section 2.5:

     With all three VOSI functions, the capability element that describes
     the function must contain an interface element of a type semantically
     appropriate for the binding of the function to the service; the
     accessURL element within the interface element indicates the endpoint
     for the VOSI function.  For the REST binding, this accessURL element
     must set the use attribute to "full".  Furthermore, for the REST
     binding, this document recommends using the
     {http://www.ivoa.net/xml/VODataService/v1.1}ParamHTTP interface type
     to encode VOSI endpoints (see example given in section 2.1).

6) Appendix 1:  Replace Availabiltiy schema listing with new VOSI schema
    listing.

Of course, I would happy to provide a revised version of the spec with 
these inserts; however, I list the suggested changes here so that folks 
can discuss them individually.

cheers,
Ray