VOSIV1RFC < IVOA

---+ IVOA Support Interfaces (VOSI) RFC (Version 1.0)

This document is a "Request for Comment" (RFC) for the Proposed Recommendation "IVOA Support Interfaces V1.0" (also known as VOSI). The latest version of the specification (11-03-2010) can be found at:

http://www.ivoa.net/Documents/VOSI/20101206/

IVOA Review Period: 9 Apr 2010 - 14 May 2010.

TCG Review Period: 8 Dec 2010 - 7 Jan 2011

This specification describes the minimum required interface to participate in the IVOA as a web service. It is an essential component of the TAP specification and so any TAP implementation also serves as a VOSI implementation.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your !WikiName so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the GWS WG mailing list, grid@ivoa.net. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

<hr noshade>

---++ Comments from the community
   * Sample comment by TWiki.WikiName
      * Response (by TWiki.WikiName)


   * Comment by BobHanisch (23 April 2010)

Well, this is one of the more opaque standards documents, at least to me.  Here are some things I think would help make this a bit more approachable and provide someone less familiar with the VO some sense of perspective.

In the Introduction, please define the acronyms and provide references to where these external standards are defined.

Delete "It is felt"; not the language of a standard.

Replace the last paragraph of the Introduction with the usual text that refers to RFC 2119.

Section 2, 1st sentence, the word "apply" seems odd here.  Do interfaces apply to a service?  Pertain?  Invoke?  With which they are associated?

In the 4th paragraph, there is a typo in "standardld".  Or is this supposed to be something like standardID?  (With a sans-serif font you can't tell.)  The reference to Section 2.4 looks incorrect.

Final paragraph, "The client must find the appropriate URLs from the registration..."; shouldn't that be "registry"?

Section 2.1, 3rd bullet, "not fixed in".  Do you mean "defined"?

Just prior to the group of two bullets, "The capability list alone...", I don't understand the sense of "alone" here.  Is it that the capability list only has two uses, or that only the capability list has two uses?

Next bullet, "drive the service" sounds very colloquial.  Just say "use" or "invoke".

Just below the two bullets, here is something to show my ignorance, but I do not understand what is intended by the { } notation in the root element of the URL.  The text here seems to run in circles:  ...a child element capability...that describes the capabilities...  the capability element...is of type ... capability ... a capability element may be ...a legal subtype of ...capability ...  Uggh.

In the example on the next page (sample response for SIA service) why, in xsi:schemaLocation, is each entry repeated twice?  The text in this example box flows outside the box quite a lot.

Section 2.2, remove "description" from the section heading.

Add a reference to resource metadata (1st bullet), and I don't think the quotation marks are then necessary.

Section 2.3, 3rd paragraph, "If any of these check fail..." should be "checks"

Next paragraph, I don't think services "wish" or "intend" to do anything.

Just prior to Section 3.4, the paragraph "Ultimately some portals..." is not terribly relevant to defining the standard and can be dropped.

In Section 2.5, 3rd paragraph, missing "by" "after represented".

4th paragraph, missing "of" after "value".

--

   * Comment by IVOA.PatrickDowler (27 Apr 2010)

I sent a very small schema for VOSITables that is necessary for actually using the TableSet element from VODataService as the root
element of a document. I think it should be in A.3 since VOSITables is defined in this standard.

For implementation, http://code.google.com/p/opencadc/ contains source code and several services at CADC implement VOSI endpoints (see http://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/caom/ for example). Aside from the above missing schema document, it was straightforward to write code to emit the fully validated (XML schema validation using SAXParser) xml documents.

   * Comment by IVOA.MarkTaylor (12 May 2010)

There are several typos:
   * sec 2.1: "...these two might well be apply to...".
   * Example in sec 2.1: the comment "the interface that returns this document" appears above both the =VOSI#capabilities= and the =VOSI#availability= elements.  I think the second occurrence is a mistake.
   * sec 2.1: "The data and time at which the metadata last changed shall be obtained the Last-Modified...".  I can't make sense of this sentence, though perhaps I'm just not reading it right.  Is "data" a typo for "date"?  Or not?
   * sec 2.3: "If any of these check fail..." should read "checks".
   * sec 2.3: "... with a registered URIL".  Should that read URL?  Or perhaps I'm just getting behind with my ETLAs.
   * sec 2.5: "should be represented an element" presumably missing "by" - twice.
   * sec 2.5: "the value its standardID attribute" presumably missing "of" - twice.

I found the organisation of this document a bit confusing.  It seems to me that sections 2.1 (most of it), 2.3 and 2.4 belong together, being descriptions of the different capabilities which may be registered, though this is complicated by the fact that the capabilities element itself describes how to register them.  Would it be advantageous to rearrange the document so that these are three subsections of a parent section, with the rest of the content at a higher level?

I mean something like a section containing only:
   * Capability types
      * "Capabilities" capability _(part of content of sec 2.1, plus capabilities part of sec 2.5)_
      * "Availability" capability _(content of sec 2.3, plus availability part of sec 2.5)_
      * "Tables" capability _(content of sec 2.4, plus tables part of sec 2.5)_

with the rest of the material in different top-level sections.  I think the Example could profitably be outside of this "Capability Types" section as well, since in some sense it applies to the whole of VOSI.

--

All of these comments have attend to in the latest version.

-- IVOA.MatthewGraham - 08 Dec 2010

---++ Comments from TCG during TCG Review (8 Dec 2010 to 7 Jan 2011)

---+++Applications (Tom !McGlynn, Mark Taylor)

Thanks for addressing my comments about document structure.

There remain a couple of typos:
   * sec 1.2: "...to use engage them..." - doesn't make sense
   * "auotmated" - spelling

There are also a couple of places where I _think_ that in line with the usage described by the Note in section 3.1, the term "capability" ought to be italicised but isn't: In section 3.1 "For example, one capability might describe a cone search..." and in section 4 "With all three VOSI functions, the capability element...".

Finally, in line with Matthew's revision of the mandate that all VO services must support VOSI, I think the abstract needs rewording slightly to reflect this.  I also question the notion from the abstract of services participating in the IVOA - sounds like a category error.  Services participating in the VO instead?

Subject to consideration of the above, the Apps WG recommends acceptance.

-- IVOA.MarkTaylor - 13 Dec 2010

---+++Data Access Layer (Patrick Dowler, Mike Fitzpatrick)

Approved.

-- IVOA.Patrick.Dowler - 2011-03-01

---+++Data Model (Mireille Louys, JesusSalgado)
Approved.
 
-- IVOA.MireilleLouys 2011-05-04

---+++Grid&Web Sevices (Matthew Graham, Paul Harrison)

I approve this document.

-- IVOA.MatthewGraham - 08 Dec 2010

The current version of the document mandates that *all* VO services provide the availability and capabilities interfaces. Following discussion at the Nara Interop closing plenary session, it was agreed that this statement should be amended in the VOSI document to read:

It is agreed that IVOA "services" standards previous to VOSI may not be forced to retrospectively implement VOSI (although that should be encouraged). Nonetheless, all new IVOA "services" standards (or updated existing ones) must enforce the VOSI implementation.

-- IVOA.MatthewGraham - 12 Dec 2010

---+++Registry (Gretchen Greene, Pierre Le Sidaner)

Registry WG approves with following comments: 

comments reflect on the abstract statement...web service requires?
later in section 3.1 service should provide.  which is it?  i see your
comments later,  but perhaps the abstract can reflect the clarification you've stated above for *new* IVOA services standards

section 3.2  please move the non-service metadata section to last

would be good to clarify the registry and vosi getCapability does this come from services?  request that this is explicitly written

This document should mention WADL as a possible descriptor for REST service.

Preference not to require client to require SOAP service binding for VOSI endpoint to SOAP service.  VOSI can simply be URL based
different from web service.

Terminology is confusing as described in the Capability description of the document.  It may help to clarify service capability vs resource capability further and what the hierarchy of xml elements are in each case.  Example http://voparis-srv.obspm.fr/srv/tap-titan_temperature/capabilities

Request more detailed examples:
a second example for SIA should be done 
  classical param of SIA 1.0 (sky position + ROI)
  extended parameters (time, band) that should be taken from STC 
(inclusion of schema) or Observation DM
 

-- IVOA.GretchenGreene - 08 March 2011

I've responded to all of these in the latest version. In particular, an appendix has been added to clarify the service capability vs resource capability issue.

Regarding the more detailed examples request, Ray comments: The SIA example kept the SIA capability minimal so as to highlight the format features of VOSI.  How to format an SIA capability which all its use of extended parameters and STC coverage is more something for the SimpleDALRegExt document.

-- IVOA.MatthewGraham - 05 May 2011



---+++Semantics (Sebastien Derriere, Norman Gray)

Document approved, just a few minor typos to be fixed in the final version :

p5, the reference to section 2.2.1 of [1] should be section 2.2.1 of [12], i.e. <nop>VOResource and not SOAP

In section 4, 1st table, typo in endpoint: capabilties -> capabilities

Section 5, in the last comment of the first XML example, it is not the interface returning this document, but the interface returning availbility.

---+++VOEvent (Rob Seaman, Roy Williams)

Approved (in the absence of objection from Roy).  -- IVOA.RobSeaman - 14 March 2011

---+++Standard and Processes (Francoise Genova)

---+++Data Curation & Preservation (Alberto Accommazzi)

---+++KDD (Giuseppe Longo)

---+++Theory (Herve Wozniak, Claudio Gheller)

I approve.

Just s small comment. In the sentence (end of Sect. 1) "Once a user discovers data and services of interest, she will want to use engage them in an analysis process.", why the user cannot be a man?

---+++TCG (Christophe Arviset, Severin Gaudet)

I approve the document, seconding Matthew's comments discussed and agreed at the Nara closing plenary.

A couple of minor editing remarks to be taken into account:
   * for the last version, it would be good that the PDF version does not show the path to Matthew's local disk ;-)
   * on page 7 and 8, the text runs outside the borders

-- IVOA.ChristopheArviset - 8 Dec 2010


<br/>
<!--
      * Set ALLOWTOPICRENAME = %MAINWEB%.TWikiAdminGroup
-->
This topic: IVOA > VOSIV1RFC
Topic revision: r18 - 2011-05-05 - MatthewGraham