/[volute]/trunk/projects/grid/VOSI/VOSI.tex
ViewVC logotype

Diff of /trunk/projects/grid/VOSI/VOSI.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 3388 by major.brian, Thu Apr 14 23:46:17 2016 UTC revision 3389 by msdemlei, Fri May 6 17:22:59 2016 UTC
# Line 3  Line 3 
3    
4  \usepackage{listings}  \usepackage{listings}
5  \lstloadlanguages{XML}  \lstloadlanguages{XML}
6  \lstset{flexiblecolumns=true,basicstyle=\small,tagstyle=\ttfamily}  \lstset{flexiblecolumns=true,basicstyle=\footnotesize,tagstyle=\ttfamily,showspaces=false}
7    
8  \title{IVOA Support Interfaces}  \title{IVOA Support Interfaces}
9    
# Line 62  Line 62 
62  \begin{figure}  \begin{figure}
63  \centering  \centering
64    
 % Get the architecture diagram from the TCG chair  
 % http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG  
 % If they give you a PDF, for now dumb it down to a png by  
 % convert -antialias -density 72x72 archdiag.pdf archdiag.png  
 % Oh -- Notes don't need this; you'd have to remove archdiag.png  
 % from FIGURES in the Makefile, too.  
65    
66  \includegraphics[width=0.9\textwidth]{archdiag.png}  \includegraphics[width=0.9\textwidth]{archdiag.png}
67  \caption{VOSI in the IVOA Architecture. VOSI is the standard that defines the basic functions that all VO services should provide in order to support management of the VO.}  \caption{VOSI in the IVOA Architecture. VOSI is the standard that defines the basic functions that all VO services should provide in order to support management of the VO.}
68  \label{fig:archdiag}  \label{fig:archdiag}
69  \end{figure}  \end{figure}
70    
71  In this architecture, users employ a variety of tools (from the User Layer) to discover and access archives and services--that is, resources--of interest (represented in the Resource Layer). A registry plays a role in discovery by harvesting metadata that describe archives and services and making them searchable from a central service. The VOSI interface provides a means for a service to provide some of this metadata itself; this allows a registry to pull the metadata from the service rather than relying on a human to provide it (e.g. by typing the data into a registration form manually). This mechanism can make it easier to collect highly detailed metadata (e.g. descriptions of columns in a catalog) that might not be practically provided otherwise. As some of this metadata describes the service interface and how it behaves, other applications can use this information for controlling how they use the service. Even when the service is "discovered" through some means other than a registry, an application can still understand how to use the service by querying for this information directly. (See Appendix \ref{appendix:harvesting} for a more detailed description of this use case.)  In this architecture, users employ a variety of tools (from the User
72    Layer) to discover and access archives and services -- that is,
73    resources -- of interest (represented in the Resource Layer). A registry
74    plays a role in discovery by harvesting metadata that describe archives
75    and services and making them searchable from a central service. The VOSI
76    interface provides a means for a service to provide some of this
77    metadata itself; this allows a registry to pull the metadata from the
78    service rather than relying on a human to provide it (e.g. by typing the
79    data into a registration form manually). This mechanism can make it
80    easier to collect highly detailed metadata (e.g. descriptions of columns
81    in a catalog) that might not be practically provided otherwise. As some
82    of this metadata describes the service interface and how it behaves,
83    other applications can use this information for controlling how they use
84    the service. Even when the service is ``discovered'' through some means other than a registry, an application can still understand how to use the service by querying for this information directly. (See Appendix \ref{appendix:harvesting} for a more detailed description of this use case.)
85    
86  Once a user discovers data and services of interest, she will want to engage them in an analysis process. Success requires that the selected services are actually up and running properly as a down service can cause automated processing to fail completely. Registry and workflow services can assist with this by tracking the availability of services and alerting users about downtime. We envision that VOSI will allow VO projects to better track the overall health of the VO ecosystem.  Once a user discovers data and services of interest, she will want to engage them in an analysis process. Success requires that the selected services are actually up and running properly as a down service can cause automated processing to fail completely. Registry and workflow services can assist with this by tracking the availability of services and alerting users about downtime. We envision that VOSI will allow VO projects to better track the overall health of the VO ecosystem.
87    
# Line 85  Line 92 
92    
93  In the REST binding, the support interfaces shall have distinct URLs in the HTTP scheme and shall be accessible by the GET operation in the HTTP protocol. The response to an HTTP POST, PUT or DELETE to these resources is not defined by this specification. However, if an implementation has no special action to perform for these requests, the normal response would be a HTTP 405 "Method not allowed" status code.  In the REST binding, the support interfaces shall have distinct URLs in the HTTP scheme and shall be accessible by the GET operation in the HTTP protocol. The response to an HTTP POST, PUT or DELETE to these resources is not defined by this specification. However, if an implementation has no special action to perform for these requests, the normal response would be a HTTP 405 "Method not allowed" status code.
94    
95  The endpoints and interface types for the support interface shall be defined in the service's registration using one Capability element for each interface. The values of the standardID attribute for these Capabilities are given in section 4.  The endpoints and interface types for the support interface shall be defined in the service's registration using one \xmlel{capability} element for each interface. The values of the \xmlel{standardID} attribute for these Capabilities are given in section~\ref{sec:endpoints}.
96    
97  When using the REST binding, any HTTP URLs may be used. The client must find the appropriate URLs from the service's entry in the VO registry and, in general, should not try and infer the URLs from any other URLs for that service. However, standards for specific services may put extra constraints on the form of the URLs.  When using the REST binding, any HTTP URLs may be used. The client must find the appropriate URLs from the service's entry in the VO registry and, in general, should not try and infer the URLs from any other URLs for that service. However, standards for specific services may put extra constraints on the form of the URLs.
98    
# Line 103  Line 110 
110    
111  This section defines how each of these classes is represented. The following typographic convention is used to represent a XML element defined within a particular namespace:  This section defines how each of these classes is represented. The following typographic convention is used to represent a XML element defined within a particular namespace:
112    
113  \begin{verbatim}  $$\hbox{\xmlel{http://some.name.space\#elementName}}$$
 http://some.name.space\#elementName  
 \end{verbatim}  
114    
115  For example, http://www.ivoa.net/xml/VOResource/v1.0\#resource indicates a XML element named resource that is described in the XML schema associated with the 'http://www.ivoa.net/xml/VOResource/v1.0' namespace - in this case, this would be VOResource.xsd \citep{std:VOR}.  For example, \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#resource} indicates a XML element named \xmlel{resource} that is described in the XML schema associated with the 'http://www.ivoa.net/xml/VOResource/v1.0' namespace -- in this case, this would be VOResource.xsd \citep{std:VOR}.
116    
117  \subsection{Capability metadata}  \subsection{Capability metadata}
118    
119  Note:  Note:
120      'Capability' is unfortunately an overloaded term in the VO referring to both a functional aspect of a service and also particular pieces of metadata defined by various XML schema. When referring to an XML element called 'capability', it shall be be put in italics. Its parent namespace may also be included (using the syntax described above) if it is ambiguous which XML schema is being referred to.      'Capability' is unfortunately an overloaded term in the VO referring to both a functional aspect of a service and also particular pieces of metadata defined by various XML schema. When referring to an XML element called \xmlel{capability}, it shall be typeset in italic typewriter. Its parent namespace may also be included (using the syntax described above) if it is ambiguous which XML schema is being referred to.
121            
122  This interface provides the service metadata in the form of a list of Capability descriptions. Each of these descriptions is an XML element that:  This interface provides the service metadata in the form of a list of Capability descriptions. Each of these descriptions is an XML element that:
123    
# Line 124  Line 129 
129    
130  For example, one Capability might describe a cone search function and another the TAP implementation but these two might well apply to the same service.  For example, one Capability might describe a cone search function and another the TAP implementation but these two might well apply to the same service.
131    
132  An entry for a service in the resource registry - i.e., its VOResource - contains the Dublin Core resource metadata (identifier, curation information, content description, etc.) followed by the service's capability descriptions (expressed as a series of http://www.ivoa.net/xml/VOResource/v1.0\#Capability elements). Effectively, the resource metadata describes the service to human users and the capability list describes it to software. Therefore, the latter list has two uses:  An entry for a service in the resource registry - i.e., its VOResource - contains the Dublin Core resource metadata (identifier, curation information, content description, etc.) followed by the service's capability descriptions (expressed as a series of \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Ca\-pa\-bi\-lity} elements). Effectively, the resource metadata describes the service to human users and the capability list describes it to software. Therefore, the latter list has two uses:
133    
134  \begin{itemize}  \begin{itemize}
135  \item it may be read by a client application to find out how to invoke the service. This presumes that the service has been already been selected and the VOSI endpoint located.  \item it may be read by a client application to find out how to invoke the service. This presumes that the service has been already been selected and the VOSI endpoint located.
136  \item it may be read by the registry itself to compile the registry entry for the service. In this case, the resource metadata are entered into the registry directly and the service metadata are then read from the service. Since the service implementation usually knows its capabilities, this removes the need for a human to type them into the registry.  \item it may be read by the registry itself to compile the registry entry for the service. In this case, the resource metadata are entered into the registry directly and the service metadata are then read from the service. Since the service implementation usually knows its capabilities, this removes the need for a human to type them into the registry.
137  \end{itemize}  \end{itemize}
138    
139  The service metadata shall be represented as an XML document with the root element http://www.ivoa.net/xml/VOSICapabilities/v1.0\#capabilities. (See Appendix \ref{appendix:capabilities} for the definition of the VOSICapabilities XML schema.) This element must contain one or more child 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  The service metadata shall be represented as an XML document with the root element \xmlel{http://www.ivoa.net/xml/VOSICapabilities/v1.0\#capabilities}. (See Appendix \ref{appendix:capabilities} for the definition of the VOSICapabilities XML schema.) This element must contain one or more child capability elements that describe the capabilities of the service. Given that the capability element is defined to be of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}, a capability element may be represented by a legal sub-type of
140  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 \citep{std:VOR}).  \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}, in which case, the capability element must use an \xmlel{xsi:type} attribute to identify the sub-type (see section 2.2.1 of VOResource \citep{std:VOR}).
141    
142    
143  Note:  \begin{admonition}{Note}
144      The value of the capability element's standardID attribute is used to indicate the service's support for particular standard protocols (such as Simple Image Access, Simple Cone Search, etc.). In the case of some protocols, the support for the standard is further characterized by additional metadata provided by a standard XML schema extension of Capability for that protocol. The extension metadata is enabled by adding a xsi:type attribute to the capability element set to the Capability sub-type value defined in the extension schema for that protocol (see example below).  The value of the capability element's \xmlel{standardID} attribute is used to indicate the service's support for particular standard protocols (such as Simple Image Access, Simple Cone Search, etc.). In the case of some protocols, the support for the standard is further characterized by additional metadata provided by a standard XML schema extension of \xmlel{Capability} for that protocol. The extension metadata is enabled by adding a \xmlel{xsi:type} attribute to the capability element set to the Capability sub-type value defined in the extension schema for that protocol (see example below).
145            
146   The VOResource list of capabilities should include capabilities describing VOSI endpoints as specified in section \ref{sec:endpoints}.  The VOResource list of capabilities should include capabilities describing VOSI endpoints as specified in section \ref{sec:endpoints}.
147    \end{admonition}
148    
149  In the REST binding, the service metadata shall be a single web resource with a registered URL. The date and time at which the metadata last changed shall be obtained from the Last-Modified HTTP Header keyword sent in the response to a GET or HEAD request to the registered URI.  In the REST binding, the service metadata shall be a single web resource with a registered URL. The date and time at which the metadata last changed shall be obtained from the Last-Modified HTTP Header keyword sent in the response to a GET or HEAD request to the registered URI.
150    
# Line 158  Line 164 
164    
165  \subsection{Availability metadata}  \subsection{Availability metadata}
166    
167  This interface indicates whether the service is operable and the reliability of the service for extended and scheduled requests. The availability shall be represented as an XML document in which the root element is http://www.ivoa.net/xml/Availability/v1.0\#availability. This element shall contain child elements providing the following information.  This interface indicates whether the service is operable and the reliability of the service for extended and scheduled requests. The availability shall be represented as an XML document in which the root element is \xmlel{http://www.ivoa.net/xml/Availability/v1.0\#availability}. This element shall contain child elements providing the following information:
168    
169  \begin{itemize}  \begin{itemize}
170  \item available - whether the service is currently accepting requests  \item \xmlel{available} -- whether the service is currently accepting requests
171  \item upSince - duration for which the service has been continuously available  \item \xmlel{upSince} -- duration for which the service has been continuously available
172  \item downAt - the instant at which the service is next scheduled to be unavailable  \item \xmlel{downAt} -- the instant at which the service is next scheduled to be unavailable
173  \item backAt - the instant at which the service is scheduled to become available again after down time;  \item \xmlel{backAt} -- the instant at which the service is scheduled to become available again after down time;
174  \item note - textual note, e.g. explaining the reason for unavailability.  \item \xmlel{note} -- textual note, e.g. explaining the reason for unavailability.
175  \end{itemize}  \end{itemize}
176    
177  The elements upSince, downAt, backAt and note are optional. The available element is mandatory. There may be more than one note element.  The elements \xmlel{upSince}, \xmlel{downAt}, \xmlel{backAt} and \xmlel{note} are optional. The \xmlel{available} element is mandatory. There may be more than one \xmlel{note} element.
178    
179  The XML document shall conform to the schema given in appendix \ref{appendix:availability} of this specification.  The XML document shall conform to the schema given in appendix \ref{appendix:availability} of this specification.
180    
# Line 189  Line 195 
195  The VODataService standard \citep{std:VODS11} defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.  The VODataService standard \citep{std:VODS11} defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.
196    
197  A service which uses tables in its interface should define a VOSI endpoint from which table metadata can be read. The table metadata for all content of a service shall be represented as an XML document of which the root element is of type  A service which uses tables in its interface should define a VOSI endpoint from which table metadata can be read. The table metadata for all content of a service shall be represented as an XML document of which the root element is of type
198  http://www.ivoa.net/xml/VODataService/v1.1\#TableSet. The table metadata for a single table (see below) shall be represented as an  \xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#TableSet}. The table metadata for a single table (see below) shall be represented as an
199  XML document of which the root element is of type http://www.ivoa.net/xml/VODataService/v1.1\#Table. This element may contain any mix of elements allowed by the VODataService XML schema.  XML document of which the root element is of type \xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#Table}. This element may contain any mix of elements allowed by the VODataService XML schema.
200    
201  In the REST binding, the tableset metadata shall be a hierarchical web resource with a registered URL. This base REST endpoint must support an optional query parameter named detail with value min.  In the REST binding, the tableset metadata shall be a hierarchical web resource with a registered URL. This base REST endpoint must support an optional query parameter named detail with value min.
202    
# Line 221  Line 227 
227  \begin{tabular}{l l l l l}  \begin{tabular}{l l l l l}
228  \label{tab:registration}  \label{tab:registration}
229  Endpoint type & standardID value \\  Endpoint type & standardID value \\
230  availability & ivo://ivoa.net/std/VOSI\#availability \\  availability & \nolinkurl{ivo://ivoa.net/std/VOSI#availability} \\
231  capabilities & ivo://ivoa.net/std/VOSI\#capabilities \\  capabilities & \nolinkurl{ivo://ivoa.net/std/VOSI#capabilities} \\
232  tables (1.0) & ivo://ivoa.net/std/VOSI\#tables \\  tables (1.0) & \nolinkurl{ivo://ivoa.net/std/VOSI#tables} \\
233  tables (1.1) & ivo://ivoa.net/std/VOSI\#tables-1.1 \\  tables (1.1) & \nolinkurl{ivo://ivoa.net/std/VOSI#tables-1.1} \\
234  \end{tabular}  \end{tabular}
235    
236  An availability endpoint shall be represented by an element named capability, of type http://www.ivoa.net/xml/VOResource/v1.0\#Capability (defined by the standard VOResource XML schema \citep{std:VOR}). The value of the standardID attribute of the capability shall be ivo://ivoa.net/std/VOSI\#availability.  An availability endpoint shall be represented by an element named \xmlel{capability}, of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability} (defined by the standard VOResource XML schema \citet{std:VOR}). The value of the \xmlel{standardID} attribute of the capability shall be \nolinkurl{ivo://ivoa.net/std/VOSI#availability}.
237    
238  A capabilities endpoint should be represented by an element named capability, of type http://www.ivoa.net/xml/VOResource/v1.0\#Capability. If such a capability is provided then the value of the standardID attribute must be ivo://ivoa.net/std/VOSI\#capabilities.  A capabilities endpoint should be represented by an element named \xmlel{capability}, of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}. If such a capability is provided then the value of the \xmlel{standardID} attribute must be \nolinkurl{ivo://ivoa.net/std/VOSI#capabilities}.
239    
240  A tables endpoint should be represented by an element named capability, of type http://www.ivoa.net/xml/VOResource/v1.0\#Capability. If such a capability is provided then the value of the standardID attribute must be ivo://ivoa.net/std/VOSI\#tables.  A tables endpoint should be represented by an element named \xmlel{capability}, of type \xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}. If such a capability is provided then the value of the \xmlel{standardID} attribute must be \nolinkurl{ivo://ivoa.net/std/VOSI\#tables}.
241    
242  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).  With all three VOSI functions, the \xmlel{capability} element that describes the function must contain an \xmlel{interface} element of a type semantically appropriate for the binding of the function to the service; the \xmlel{accessURL} element within the \xmlel{interface} element indicates the endpoint for the VOSI function. For the REST binding, this \xmlel{accessURL} element must set the \xmlel{use} attribute to \texttt{"full"}. Furthermore, for the REST binding, this document recommends using the \xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#ParamHTTP} interface type to encode VOSI endpoints (see the examples given in section~\ref{sec:examples}).
243    
244  \section{Example VOSI responses}  \section{Example VOSI responses}
245  \label{sec:examples}  \label{sec:examples}
246    
247  Example 1:  \subsection{Example 1: SIA 1.0 capabilities}
248    
249  A sample response from a capabilities resource describing an SIA service.  A sample response from a capabilities resource describing an SIA service.
250    
251  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
252  <?xml version="1.0" encoding="UTF-8"?>  <?xml version="1.0" encoding="UTF-8"?>
253  <vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"  <vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
254      xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"      xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
255      xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0"      xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0"
256      xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0"      xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0"
257      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
258      xsi:schemaLocation="http://www.ivoa.net/xml/VOSI/v1.0 http://www.ivoa.net/xml/VOSI/v1.0      xsi:schemaLocation="http://www.ivoa.net/xml/VOSI/v1.0
259  http://www.ivoa.net/xml/VOResource/v1.0 http://www.ivoa.net/xml/VOResource/v1.0          http://www.ivoa.net/xml/VOSI/v1.0
260  http://www.ivoa.net/xml/VODataService/v1.0 http://www.ivoa.net/xml/VODataService/v1.0        http://www.ivoa.net/xml/VOResource/v1.0
261  http://www.ivoa.net/xml/SIA/v1.0 http://www.ivoa.net/xml/SIA/v1.0">          http://www.ivoa.net/xml/VOResource/v1.0
262          http://www.ivoa.net/xml/VODataService/v1.0
263            http://www.ivoa.net/xml/VODataService/v1.0
264          http://www.ivoa.net/xml/SIA/v1.0
265            http://www.ivoa.net/xml/SIA/v1.0">
266    
267    <!-- a generic capability (for custom, non-standard interfaces) -->    <!-- a generic capability (for custom, non-standard interfaces) -->
268    <capability>    <capability>
269      <interface xsi:type="vr:WebBrowser">      <interface xsi:type="vr:WebBrowser">
270        <accessURL use="full"> http://adil.ncsa.uiuc.edu/siaform.html </accessURL>        <accessURL use="full"> http://adil.ncsa.uiuc.edu/siaform.html
271          </accessURL>
272      </interface>      </interface>
273    </capability>    </capability>
274        
275    <!-- the SIA capability -->    <!-- the SIA capability -->
276    
277    <capability xsi:type="sia:SimpleImageAccess" standardID="ivo://ivoa.net/std/SIA">    <capability xsi:type="sia:SimpleImageAccess"
278          standardID="ivo://ivoa.net/std/SIA">
279      <interface xsi:type="vs:ParamHTTP" role="std">      <interface xsi:type="vs:ParamHTTP" role="std">
280        <accessURL> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f&amp; </accessURL>        <accessURL> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f&amp;
281          </accessURL>
282      </interface>      </interface>
283    
284      <imageServiceType>Pointed</imageServiceType>      <imageServiceType>Pointed</imageServiceType>
# Line 302  Line 316 
316    <!-- the interface that returns this capability -->    <!-- the interface that returns this capability -->
317    <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">    <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
318      <interface xsi:type="vs:ParamHTTP" role="std">      <interface xsi:type="vs:ParamHTTP" role="std">
319        <accessURL use="full"> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/capabilities </accessURL>        <accessURL use="full">
320            http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/capabilities
321          </accessURL>
322      </interface>      </interface>
323    </capability>    </capability>
324    
325    <!-- the interface that returns this availability-->    <!-- the interface that returns this availability-->
326    <capability standardID="ivo://ivoa.net/std/VOSI#availability">    <capability standardID="ivo://ivoa.net/std/VOSI#availability">
327      <interface xsi:type="vs:ParamHTTP" role="std">      <interface xsi:type="vs:ParamHTTP" role="std">
328        <accessURL use="full"> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/availability </accessURL>        <accessURL use="full">
329            http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/availability
330          </accessURL>
331      </interface>      </interface>
332    </capability>    </capability>
333    
# Line 317  Line 335 
335  \end{lstlisting}  \end{lstlisting}
336    
337    
338  Example 2:  \subsection{Example 2: TAP tables}
339    
340  A sample response from a tables resource describing a TAP service.  A sample response from a tables resource describing a TAP service.
341    
342  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
# Line 357  Line 376 
376        <name>TAP_SCHEMA.keys </name>        <name>TAP_SCHEMA.keys </name>
377        <column>        <column>
378          <name>key_id </name>          <name>key_id </name>
379          <description>unique key to join to TAP_SCHEMA.key_columns </description>          <description>unique key to join to TAP_SCHEMA.key_columns
380            </description>
381          <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>          <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>
382        </column>        </column>
383        <column>        <column>
# Line 377  Line 397 
397  </vosi:tableset>  </vosi:tableset>
398  \end{lstlisting}  \end{lstlisting}
399    
400  Example 3:  \subsection{Example 3: Tables, minimal detail}
401    
402  A sample response from a tables resource with detail=min parameter (e.g. http://example.net/srv/tables?detail=min).  A sample response from a tables resource with detail=min parameter (e.g. http://example.net/srv/tables?detail=min).
403    
404  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
# Line 413  Line 434 
434  </vosi:tableset>  </vosi:tableset>
435  \end{lstlisting}  \end{lstlisting}
436    
437  Example 4:  \subsection{Example 4: Child table resource}
438    
439  A sample response from a child table resource (e.g. http://example.net/srv/tables/TAP\_SCHEMA.columns).  A sample response from a child table resource (e.g. http://example.net/srv/tables/TAP\_SCHEMA.columns).
440    
441  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
# Line 487  Line 509 
509  </vosi:table>  </vosi:table>
510  \end{lstlisting}  \end{lstlisting}
511    
512  Example 5:  \subsection{Example 5: Availability}
513    
514  A sample response from an availability resource.  A sample response from an availability resource.
515    
516  \begin{lstlisting}[language=XML]  \begin{lstlisting}[language=XML]
# Line 701  Line 724 
724    
725   In the section \ref{sec:introduction}, we summarized the role that the metadata retrieval functions play in the discovery of services. In particular, it mentions that a registry can harvest this information from a service's VOSI interface to save the provider from entering the information explicitly into a web form. In this appendix, we describe this use case in more detail, including both the publishing of the metadata and its typical use by service clients.   In the section \ref{sec:introduction}, we summarized the role that the metadata retrieval functions play in the discovery of services. In particular, it mentions that a registry can harvest this information from a service's VOSI interface to save the provider from entering the information explicitly into a web form. In this appendix, we describe this use case in more detail, including both the publishing of the metadata and its typical use by service clients.
726    
727  Some publishing registries \citep{std:RI1} provide a publicly accessible publishing tool: it allows any data service provider to "register" his service by providing the necessary metadata adequate to describe it. Such a tool typically provides a form that the provider fills out to enter all the metadata; the form processor uses those inputs to format a VOResource record that describes the service based on that metadata. Prior to the registry's support for the VOSI metadata functions, entering all of the metadata (particularly, fully describing all of the table columns) would often be laborious; consequently, providers are effectively discouraged from providing the mostly optional information.  Some publishing registries \citep{std:RI1} provide a publicly accessible publishing tool: it allows any data service provider to ``register'' his service by providing the necessary metadata adequate to describe it. Such a tool typically provides a form that the provider fills out to enter all the metadata; the form processor uses those inputs to format a VOResource record that describes the service based on that metadata. Prior to the registry's support for the VOSI metadata functions, entering all of the metadata (particularly, fully describing all of the table columns) would often be laborious; consequently, providers are effectively discouraged from providing the mostly optional information.
728    
729  With support for the VOSI metadata functions, the registry's publishing tool can now offer an alternative mechanism for providing much of the information. After generally describing the service via core metadata (e.g., its title, identifier, general description, contact information, etc.), the registry can offer the option of entering the VOSI URLs that provide the capability and table metadata. In the case of TAP, where these VOSI functions are mandated as part of the TAP interface, it would only be necessary for the user to enter the TAP service's base URL (in VOResource parlance, the "access URL"). In either case, the tool would access the VOSI URLs, pull over the metadata, integrate it into the core metadata, and show the provider the combined results before publishing it to the registry. The tool might also ask the provider if this data is expected to change over time and thus whether the VOSI URLs should be polled regularly to update the service description held by the registry. Alternatively, the tool may may allow the provider to quickly update the service description via a single button click that causes the tool to re-access the VOSI endpoints and refresh service description held by the registry.  With support for the VOSI metadata functions, the registry's publishing tool can now offer an alternative mechanism for providing much of the information. After generally describing the service via core metadata (e.g., its title, identifier, general description, contact information, etc.), the registry can offer the option of entering the VOSI URLs that provide the capability and table metadata. In the case of TAP, where these VOSI functions are mandated as part of the TAP interface, it would only be necessary for the user to enter the TAP service's base URL (in VOResource parlance, the ``access URL''). In either case, the tool would access the VOSI URLs, pull over the metadata, integrate it into the core metadata, and show the provider the combined results before publishing it to the registry. The tool might also ask the provider if this data is expected to change over time and thus whether the VOSI URLs should be polled regularly to update the service description held by the registry. Alternatively, the tool may may allow the provider to quickly update the service description via a single button click that causes the tool to re-access the VOSI endpoints and refresh service description held by the registry.
730    
731  We note that pulling certain metadata from the service itself is expected to save the provider time and effort because the information is in large part inherently available to the service implementation. This most obviously applies to the table metadata: the provider's underlying database will normally have access to table schemas which can be used to provide, for instance, detailed descriptions of all the tables and their columns. It is less natural, perhaps, for the service to have access to the capability information; however, with the growing use of service toolkits that allow a provider to quickly deploy compliant IVOA services, it is possible that the capability information could naturally be assembled from the configuration information that was used to set up the service. Of course, if the provider is forced to create static XML documents manually to implement the VOSI functions, it's unlikely that this has saved her any time over entering the metadata into a publishing tool.  We note that pulling certain metadata from the service itself is expected to save the provider time and effort because the information is in large part inherently available to the service implementation. This most obviously applies to the table metadata: the provider's underlying database will normally have access to table schemas which can be used to provide, for instance, detailed descriptions of all the tables and their columns. It is less natural, perhaps, for the service to have access to the capability information; however, with the growing use of service toolkits that allow a provider to quickly deploy compliant IVOA services, it is possible that the capability information could naturally be assembled from the configuration information that was used to set up the service. Of course, if the provider is forced to create static XML documents manually to implement the VOSI functions, it's unlikely that this has saved her any time over entering the metadata into a publishing tool.
732    
733  A key goal of the VOSI metadata functions is to encourage the capture of metadata that is useful for discovering and selecting services that a user will want to work with. For example, a user may wish to find services that access a table containing redshift values. Or, a user may wish to find Simple Spectral Services (a particular capability) that are fully compliant. A second goal is to make that metadata available so that the user can plan its use of the service: for example, the user, through some tool, might browse through the table column descriptions to figure out how to form her query. In this latter use, the client tool can either use the registry as the source of this information or the service itself via its VOSI functions. The question that arises for the client tool developer then is, which source--the registry or the service--should be preferred?  A key goal of the VOSI metadata functions is to encourage the capture of metadata that is useful for discovering and selecting services that a user will want to work with. For example, a user may wish to find services that access a table containing redshift values. Or, a user may wish to find Simple Spectral Services (a particular capability) that are fully compliant. A second goal is to make that metadata available so that the user can plan its use of the service: for example, the user, through some tool, might browse through the table column descriptions to figure out how to form her query. In this latter use, the client tool can either use the registry as the source of this information or the service itself via its VOSI functions. The question that arises for the client tool developer then is, which source -- the registry or the service -- should be preferred?
734    
735  This VOSI specification does not recommend the use of one source over the other. The choice, in general, will depend on the context of a particular client tool and what it is trying to do, and the preferences of developers may indeed evolve over time as, say, VOSI support becomes more ubiquitous. At least initially, client tools--particularly general ones that can engage different kinds of service protocols--will likely prefer to use the registry for the source of capability and table metadata. The main reason would be that not all services will be implemented to support VOSI. By going to the registry in this case, the client gets this metadata for both services where it was retrieved via VOSI and where it was entered explicitly into a publishing tool by the provider. Under certain circumstances however, say, where the client works with just one kind of service protocol like TAP in which VOSI support is mandated for compliance, the VOSI interface might be the preferred source. In particular, if the service URL was obtained by the client through some means other than the discovery in a registry, then it would not be necessary for the client to go to the registry to understand what can be done with the service; the tool can get this information from the service itself.  This VOSI specification does not recommend the use of one source over the other. The choice, in general, will depend on the context of a particular client tool and what it is trying to do, and the preferences of developers may indeed evolve over time as, say, VOSI support becomes more ubiquitous. At least initially, client tools -- particularly general ones that can engage different kinds of service protocols -- will likely prefer to use the registry for the source of capability and table metadata. The main reason would be that not all services will be implemented to support VOSI. By going to the registry in this case, the client gets this metadata for both services where it was retrieved via VOSI and where it was entered explicitly into a publishing tool by the provider. Under certain circumstances however, say, where the client works with just one kind of service protocol like TAP in which VOSI support is mandated for compliance, the VOSI interface might be the preferred source. In particular, if the service URL was obtained by the client through some means other than the discovery in a registry, then it would not be necessary for the client to go to the registry to understand what can be done with the service; the tool can get this information from the service itself.
736    
737  We have implied in the above discussion that the capability and table metadata are the same whether they are retrieved from the registry or from the service. It is possible, however, that the service could change--new capabilities or table columns could be added--and the registry could (at least temporarily, depending on the registry) get out of sync with the service. This circumstance may occur rarely; nevertheless, if being up-to-date is important, then the client may need to be more sophisticated in its retrieval. That is, it could retrieve the resource description from the registry; then if the description indicates support for VOSI, the VOSI URLs would be accessed to get the latest, up-to-date information.  We have implied in the above discussion that the capability and table metadata are the same whether they are retrieved from the registry or from the service. It is possible, however, that the service could change -- new capabilities or table columns could be added -- and the registry could (at least temporarily, depending on the registry) get out of sync with the service. This circumstance may occur rarely; nevertheless, if being up-to-date is important, then the client may need to be more sophisticated in its retrieval. That is, it could retrieve the resource description from the registry; then if the description indicates support for VOSI, the VOSI URLs would be accessed to get the latest, up-to-date information.
738    
739  \section{Changes from Previous Versions}  \section{Changes from Previous Versions}
740  \label{appendix:changes}  \label{appendix:changes}

Legend:
Removed from v.3388  
changed lines
  Added in v.3389

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26