RIWSDLCorrection < IVOA

<small>Jumps:  IvoaResReg :: [[http://www.ivoa.net/forum/registry/][registry mail archive]] :: RegistryMetadata :: VOResourceV10 :: RegUpgradeSummer2006
<br> Meetings:  InterOpMay2006ResReg :: InterOpSep2006ResReg </small>


---+ Adapting to Corrections to the Registry Interface WSDL

Author:  RayPlante

This is draft version of a note to be submitted to the [[http://www.ivoa.net/Documents/][IVOA Document Repository]].  

---++ Abstract


Prior to 24 September 2008, an inconsistency was discovered in the
IVOA Registry Interface standards document (v1.00) between the text
and the actual WSDL document included in the appendix and provided on
the IVOA web site
(via <a href="http://www.ivoa.net/xml/">http://www.ivoa.net/wsdl/</a>).
The Registry Working Group plans to change the WSDL to match the
text.  Consequently, this has implications for current registries that
are compliant with the uncorrected WSDL.  This document describes how
the WSDL is being changed as well as how we can provide backward
compatible support for currently deployed registries.  In particular,
we will correct the official WSDL without changing the namespace.  We describe how registry providers should indicate which versions of the WSDL are supported, how clients can learn which interface is supported, and how registries and clients may choose to support both the corrected and uncorrected interface.

%TOC{title="Contents"}%

---++ 1. Introduction:  the Problem

The <a href="http://www.ivoa.net/Documents/cover/RegistryInterface-20061107.html">Registry Interface v1.00</a> (RI) contains an inconsistency in the description of the keyword search interface between the text provided in section 2.1.3 and the WSDL spelled out in Appendix A.1.  In the text description, the 3rd and 4th arguments to the *KeywordSearch* operation, =from= and =max=, respectively, control which sequence of matched records are returned.  The =from= parameter indicates "the minimum position in the complete set of matched records of the range of records to be returned", and =max= indicates "the maximum number of matched records to return".  Thus the position of the last record returned is =from+max-1=.  When a client uses this to page through a large number of matched records, the value of =from= for the next query will be =from+max=.

In the WSDL document, the 3rd and 4th parameters controling the range of matches are called =from= and =to=.  The intended meaning of =from= is the same as described above, but =to= indicated the position last record to display.  When paging, the value of =to= for the next query would be =to+1=.  

As of 24 September 2008, the copy of the WSDL as given in the appendix has been also available on the IVOA Web site (via 
<a href="http://www.ivoa.net/wsdl">http://www.ivoa.net/wsdl</a>).  Consequently, this is typically been the basis for implementations up to that date.  

The discrepancy presumably resulted from an incomplete edit to the RI document.  In an earlier version, both the *Search* and the *KeywordSearch* operations took the =from= and =to= argument parameters.  After review by the working group, it was decided to change it to =from= and =max= for both of the operations.  While the text was updated in both places, the WSDL was only updated for the *Search* operation.  

---++ 2. Correcting the Standard and Impact on Existing Implementations

As =from= and =max= represent the intention of the working group review, the next version of the RI document will change the WSDL to match the description in the text of section 2.1.3.  To minimize the disruption to existing deployed registries and clients, the namespace for the WSDL document will __not__ be changed.

Normally, changing the interface defined in the WSDL to this extent would wreak havoc with existing clients.  However, our working group discussions suggest in this particular case, such a change will not have a major practical impact, mainly due to the current lack of penetration of the RI standard search interface.  The most extensive use of the standard search interface today is within the <a href="http://www.astrogrid.org">Astrogrid project</a>, specifically via its desktop environment.  In this case, nearly all of the registry queries are done via the <strong>XQuerySearch</strong> operation, and the <strong>KeywordSearch</strong> interface is not used at all.  

Other IVOA registries (e.g. from NVO and Euro-VO) are in a less mature state and would be more easily adapted.  

The reference implementation of the client library provided by the NVO's [[http://trac.us-vo.org/nvo/wiki/IVOARegistry][IVOARegistry package]] and is actively supported, though not widely used outside of the NVO Project at this time.  The latest version is aware of the problem described in this Note:  it pulls the WSDL from the service and attempts to analyze whether its <strong>KeywordSearch</strong> supports the =to= or the =max= parameter and adapts its query accordingly.  This analysis is not trivial nor robust, so a simpler solution for making this distinction would be helpful.

While it seems the proposed correction to the WSDL will result in few effects seen by users today, it will be important that registry server and client applications incorporate the change to prevent problems in the future. Of course, there may be some period of time, particularly for <a href="http://www.astrogrid.org">AstroGrid</a> registries, before all implementations of the RI can be brought into compliance with the corrected WSDL.  Therefore, it is worth spelling out a plan for providing compatibility across corrected and uncorrected implementations.

---++ 3. Providing Compatibility Across Corrected and Existing Implementations

This section addresses the expectation that once the RI search interface is changed, there will exist some Registries supporting in the <strong>KeywordSearch</strong> interface the old =to= parameter and some supporting the new =max= parameter.  It would be helpful if a client could be constructed to talk to either variety in a manner that is transparent to the user.  To enable this, this note proposes the following:

<ul>
   <li> A pre-corrected registry updates the VOResource description of itself, setting the =version= attribute to the search =interface= element to "1.0p" (for pre-1.0).  This updated VOResource should be returned by the registry's <strong>GetIdentity</strong> search operation.  </li>
   <li> A client that wishes to support pre-corrected registries calls the <strong>GetIdentity</strong> operation to determine which interface it can use.  </li>
   <li> A server may wish to support both varieties _within the same webservice implementation_.  In this case, the server should use an altered version of the !RegistrySearch WSDL presented with this Note.  </li>
</ul>

The efficacy of this proposal is based on two assumptions:
<ul>
   <li> it is so straight-forward to update an existing registry's (namely, AstroGrid's) VOResource description that it can be done more-or-less immediately without disruption to existing users.  </li>
   <li> the standard <strong>KeyworkSearch</strong> function is not widely used at this time.  In particular, there are few existing standard registry search clients applications in use that rely on the <strong>KeyworkSearch</strong> function.  Those that do exist can be updated quickly.  </li>
</ul> 

---+++ 3.1. Updating VOResource Descriptions

This document proposes that we use a registry's resource description to indicate whether the search interface supports the =to= parameter (the uncorrected interface) or the =max= parameter.  For uncorrected services, the =&lt;interface&gt;= element should have the =version= attribute set to '1.0p' (mneumonic: pre-1.0):

<pre>
   &lt;capability xsi:type="vr:Search" 
               standardID="ivo://ivoa.net/std/Registry"&gt;
      &lt;interface xsi:type="vr:WebService" <strong>version="1.0p"</strong> &gt;
         &lt;accessURL use="post"&gt; http://my.registry.org/search &lt;/accessURL&gt;
      &lt;/interface&gt;
   &lt;/capability&gt;
</pre>

If a registry supports =max= parameter of the corrected interface, it should set =version="1.0"=:

<pre>
   &lt;capability xsi:type="vr:Search" 
               standardID="ivo://ivoa.net/std/Registry"&gt;
      &lt;interface xsi:type="vr:WebService" <strong>version="1.0"</strong> &gt;
         &lt;accessURL use="post"&gt; http://my.registry.org/search &lt;/accessURL&gt;
      &lt;/interface&gt;
   &lt;/capability&gt;
</pre>

As per the <a href="http://www.ivoa.net/Documents/REC/ReR/VOResource-20080222.html#s:Interface">VOResource standard (s3.2.2)</a>, version 1.0 should be assumed when no =version= attribute is provided--i.e. the =max= parameter is supported.

For maximum compatibility, a registry may choose to support both interfaces.  In this case, both interface entries should be included.  They <i>may</i> point to the same access URL (see S3.3 below):

<pre>
   &lt;capability xsi:type="vr:Search" 
               standardID="ivo://ivoa.net/std/Registry"&gt;
      &lt;interface xsi:type="vr:WebService" <strong>version="1.0p"</strong> &gt;
         &lt;accessURL use="post"&gt; http://my.registry.org/search &lt;/accessURL&gt;
      &lt;/interface&gt;
      &lt;interface xsi:type="vr:WebService" <strong>version="1.0"</strong> &gt;
         &lt;accessURL use="post"&gt; http://my.registry.org/search &lt;/accessURL&gt;
      &lt;/interface&gt;
   &lt;/capability&gt;
</pre>

---+++ 3.2. Client application strategies

If a client application wishes to be compatible with both corrected and uncorrected registries, then it can consult the VOResource description to determine whether to use the =to= parameter or the =max= parameter.  It is expected that it would accomplish this by starting its query session with a registry by calling the its <strong>GetResource</strong> operation to return the VOResource description.  

The expected recipe would be that the client would first search for the 1.0 version interface; the XPath that extracts the access URL would be:

<pre>
  capability[@xsi:type='vg:Search']/interface[@version='1.0']/accessURL
</pre>

If the 1.0 interface is not found, the client could fall back onto the 1.0p interface.  The XPath for this would be:

<pre>
  capability[@xsi:type='vg:Search']/interface[@version='1.0p']/accessURL
</pre>

---+++ 3.3. Servers supporting both interfaces: the modified WSDL

In many cases, it may be quite simple to modify an existing registry search implementation (i.e. the server side implementation) to support both varieties of the search interface within the same implementation.  To enable this backward compatibility, this document recommends using [[%ATTACHURL%/RegistrySearch-v1.0-bc1.wsdl][the modified WSDL]] included with this note (and also available from <a href="http://www.ivoa.net/internal/IVOA/RIWSDLCorrection/RegistrySearch-v1.0-bc1.wsdl">http://www.ivoa.net/internal/IVOA/RIWSDLCorrection/RegistrySearch-v1.0-bc1.wsdl</a>) when constructing the service. 

This differs from the corrected standard WSDL in its definition of the <strong>KeywordSearch</strong> operation:

<pre>
  &lt;xs:element name="KeywordSearch"&gt;
    &lt;xs:complexType&gt;
      &lt;xs:sequence&gt;
        &lt;xs:element name="keywords" type="xs:string" 
                    minOccurs="1" maxOccurs="1" /&gt;
        &lt;xs:element name="orValues" type="xs:boolean" 
                    minOccurs="1" maxOccurs="1" /&gt;
        &lt;xs:element name="from" type="xs:positiveInteger" 
                    minOccurs="0" maxOccurs="1" /&gt;
        &lt;xs:choice&gt;
          &lt;xs:element name="max" type="xs:positiveInteger" 
                      minOccurs="0" maxOccurs="1" /&gt;
          &lt;xs:element name="to" type="xs:positiveInteger" 
                      minOccurs="0" maxOccurs="1" /&gt;
        &lt;/xs:choice&gt;
        &lt;xs:element name="identifiersOnly" type="xs:boolean" 
                    minOccurs="0" maxOccurs="1" /&gt;            
      &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
  &lt;/xs:element&gt;      
</pre>

The semantics of this interface shall be as follows.  If the query includes the =max= parameter, the service will interpret the value as defined in the (corrected) RI standard--i.e. the number is the maximum number of records to return.  

If the query includes the =to= parameter, the service will return records up to and (if there are sufficient number of results) including the position given by the value of the parameter.  

In both cases, the service may choose to return fewer records than requested according to the value it specifies for =maxRecords= in its resource description.

While this modified WSDL is not the standard one, *it should be considered endorsed by the Registry Working Group as compliant in functionaliy with the RI standard*.  The modified WSDL _may_ be returned in response to the standard =?wsdl= query.  It is recommended though that the VOResource entry for the standard interface include an =&lt;wsdlURL&gt;= that invokes the standard !RegistrySearch WSDL.  

---++ References

<p><a name="r:ri">[RI]</a> Benson, K, Andrews, K., Auden, E., Graham,
G, Greene, G, Hill, M., Linde, T., Morris, D., O'Mullane, W., Plante,
R., Rixon, G., Stebe, A. 2007 <i>Registry Interfaces Version 1.01</i>
<br/><a href="http://www.ivoa.net/Documents/latest/RegistryInterface.html">http://www.ivoa.net/Documents/latest/RegistryInterface.html</a>
</p>

<p>
<a name="r:vor">[VOR]</a> Plante, R., Benson, K., Graham, M. Greene, G,
Harrison, P., Lemson, G., Linde, T., Rixon, G., Stebe, A. 2006,
<i>VOResource: an XML Encoding Schema for Resource Metadata, Version
1.02</i>, an IVOA Working Draft,
<a href="http://www.ivoa.net/Documents/latest/VOResource.html">
http://www.ivoa.net/Documents/latest/VOResource.html</a>
</p>


<br/>
<!--
      * Set ALLOWTOPICRENAME = %MAINWEB%.TWikiAdminGroup
-->
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
wsdl	RegistrySearch-v1.0-bc1.wsdl	r3 r2 r1	manage	12.8 K	2008-09-26 - 14:50	RayPlante	WSDL for backward compatibility
This topic: IVOA > WebHome > IvoaResReg > RegistryInterface > RIWSDLCorrection
Topic revision: r11 - 2008-09-26 - RayPlante