ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 4206 - (hide annotations)
Tue Aug 15 18:07:21 2017 UTC (3 years, 1 month ago) by major.brian
File MIME type: application/x-tex
File size: 42319 byte(s)
1 pdowler.cadc 3232 \documentclass[11pt,letter]{ivoa}
2     \input tthdefs
4     \usepackage{listings}
5     \lstloadlanguages{XML}
6 msdemlei 3389 \lstset{flexiblecolumns=true,basicstyle=\footnotesize,tagstyle=\ttfamily,showspaces=false}
7 pdowler.cadc 3232
8     \title{IVOA Support Interfaces}
10     \ivoagroup{Grid and Web Services Working Group}
12     \author{Grid and Web Services Working Group}
14     \editor{Matthew Graham}
15     \editor{Guy Rixon}
16 pdowler.cadc 3233 \editor{Patrick Dowler}
17 major.brian 3306 \editor{Brian Major}
18 pdowler.cadc 3232
19 pdowler.cadc 3233 \previousversion[http://www.ivoa.net/documents/VOSI/20110531/REC-VOSI-1.0-20110531.html]{VOSI-1.0}
20 pdowler.cadc 3232
21     \begin{document}
22     \begin{abstract}
23 major.brian 3306 This document describes the minimum interface that a web service requires to participate in the IVOA. Note that this is not required of standard VO services developed prior to this specification, although uptake is strongly encouraged on any subsequent revision. All new standard VO services, however, must feature a VOSI-compliant interface.
24 pdowler.cadc 3232 \end{abstract}
27     \section*{Acknowledgments}
29     This document has been developed with support from the National Science Foundation's Information Technology Research Program under Cooperative Agreement AST0122449 with The Johns Hopkins University, from the UK Particle Physics and Astronomy Research Council (PPARC), from the European Commission's (EC) Sixth Framework Programme via the Optical Infrared Coordination Network (OPTICON), and from EC's Seventh Framework Programme via its eInfrastructure Science Repositories initiative.
31     This work is based on discussions and actions from the 2003 IVOA meeting in Strasbourg and further discussions on registry functionality at JHU late in 2003. Later inputs came from a local meeting at JHU in Sept. 2004. William O'Mullane and Ani Thakar were the editors and primary authors for these early versions.
33     The decision to split the interfaces into a mandatory set and optional logging interfaces was taken by GWS-WG at the IVOA meeting of May 2006.
35     \section*{Conformance-related definitions}
37     The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
38     ``OPTIONAL'' (in upper or lower case) used in this document are to be
39     interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
41     The \emph{Virtual Observatory (VO)} is a
42     general term for a collection of federated resources that can be used
43     to conduct astronomical research, education, and outreach.
44     The \href{http://www.ivoa.net}{International
45     Virtual Observatory Alliance (IVOA)} is a global
46     collaboration of separately funded projects to develop standards and
47     infrastructure that enable VO applications.
50     \section{Introduction}
51 major.brian 3306 \label{sec:introduction}
52 pdowler.cadc 3232
53 major.brian 3306 This document describes a set of common basic functions that VO web services provide in the form of a standard support interface in order to allow for the effective management of the VO. There are three basic support functions that this document describes: The reporting of capability metadata, the reporting of service availability metadata, and the reporting of table metadata (if applicable).
54 pdowler.cadc 3232
55 major.brian 3306 VO service standards previous to VOSI may not be forced to retrospectively implement VOSI (although that should be encouraged). Nonetheless, all new VO service standards (or updated existing ones) must enforce the VOSI implementation.
56 pdowler.cadc 3232
57 major.brian 3306
58 pdowler.cadc 3232 \subsection{Role within the VO Architecture}
60 major.brian 3306 The IVOA Architecture \citep{note:VOARCH} provides a high-level view of how IVOA standards work together to connect users and applications with providers of data and services, as depicted in the diagram in Figure ~\ref{fig:archdiag}.
61 pdowler.cadc 3232
62     \begin{figure}
63     \centering
66     \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.}
68     \label{fig:archdiag}
69     \end{figure}
71 msdemlei 3389 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 pdowler.cadc 3232
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.
88     \section{Interface bindings}
89 major.brian 3306 \label{sec:bindings}
90 pdowler.cadc 3232
91 major.brian 3764 This section explains how services are to report VO support metadata through a standard interface.
93 major.brian 3306 The standard interface returns metadata without changing the state of the service with which it is associated. This standard requires a REST binding of VOSI even when applied to services that do not have a RESTful interface.
94 pdowler.cadc 3232
95 major.brian 3764 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. Both the capabilities and availability bindings must be available to anonymous requests.
96 pdowler.cadc 3232
97 msdemlei 3389 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}.
98 pdowler.cadc 3232
99     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.
101     \section{Metadata specification}
102 major.brian 3306 \label{sec:metadata}
103 pdowler.cadc 3232
104     There are various classes of metadata that might be returned by a service through its standard interface:
106     \begin{itemize}
107     \item those describing its functional capabilities
108     \item those describing its operational behaviour - availability, reliability, etc.
109     \item those describing tabular data handled by the service
110     \item those describing other aspects of the service
111     \end{itemize}
113     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:
115 msdemlei 3389 $$\hbox{\xmlel{http://some.name.space\#elementName}}$$
116 pdowler.cadc 3232
117 msdemlei 3389 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}.
118 pdowler.cadc 3232
119     \subsection{Capability metadata}
121     Note:
122 msdemlei 3389 '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.
123 pdowler.cadc 3232
124     This interface provides the service metadata in the form of a list of Capability descriptions. Each of these descriptions is an XML element that:
126     \begin{itemize}
127     \item states that the service provides a particular, IVOA-standard function;
128     \item lists the interfaces for invoking that function;
129     \item records any details of the implementation of the function that are not defined as default or constant in the standard for that function.
130     \end{itemize}
132     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.
134 msdemlei 3389 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:
135 pdowler.cadc 3232
136     \begin{itemize}
137     \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.
138     \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.
139     \end{itemize}
141 major.brian 3764 The service metadata shall be represented as an XML document with the root element:\\
142     $$\hbox{\xmlel{http://www.ivoa.net/xml/VOSICapabilities/v1.0\#capabilities}}$$\\
143     (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\\
144     $$\hbox{\xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}}$$\\
145     a capability element may be represented by a legal sub-type of\\
146     $$\hbox{\xmlel{http://www.ivoa.net/xml/VOResource/v1.0\#Capability}}$$\\
147     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}).
148 pdowler.cadc 3232
149 msdemlei 3389 \begin{admonition}{Note}
150     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).
151 pdowler.cadc 3232
152 msdemlei 3389 The VOResource list of capabilities should include capabilities describing VOSI endpoints as specified in section \ref{sec:endpoints}.
153     \end{admonition}
154 pdowler.cadc 3232
155     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.
157     All VO services should provide this interface.
159     \subsection{Availability metadata}
161 msdemlei 3389 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:
162 pdowler.cadc 3232
163     \begin{itemize}
164 msdemlei 3389 \item \xmlel{available} -- whether the service is currently accepting requests
165     \item \xmlel{upSince} -- duration for which the service has been continuously available
166     \item \xmlel{downAt} -- the instant at which the service is next scheduled to be unavailable
167     \item \xmlel{backAt} -- the instant at which the service is scheduled to become available again after down time;
168     \item \xmlel{note} -- textual note, e.g. explaining the reason for unavailability.
169 pdowler.cadc 3232 \end{itemize}
171 msdemlei 3389 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.
172 pdowler.cadc 3232
173 major.brian 3306 The XML document shall conform to the schema given in appendix \ref{appendix:availability} of this specification.
174 pdowler.cadc 3232
175     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 it should check that the database is still up. If any of these checks fail, the service should set available to false in the availability output.
177     If a service is to be online but unavailable for work (e.g., when a service with a work queue intends to shut down after draining the queue) then the service should set available to false.
179     There are no special elements in the availability document for the contact details of the service operator. These details may be given as a note element if they are known to the service.
181     In the REST binding, the availability shall be a single web resource with a registered URL
183     All VO services shall provide this interface.
185     \subsection{Table metadata}
187 major.brian 3306 Some services deal with tabular data. These data may be the target of ADQL queries, as in TAP \citep{std:TAP}, or they may be the output of other operations, as in SIAP queries. In each case, it is useful if the service describes the details of the tables concerned. It is more useful if this description can be captured in the resource registry.
188 pdowler.cadc 3232
189 major.brian 3306 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.
190 pdowler.cadc 3232
191 major.brian 3764 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\\
192     $$\hbox{\xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#TableSet}}$$\\
193     The table metadata for a single table (see below) shall be represented as an
194     XML document of which the root element is of type\\
195     $$\hbox{\xmlel{http://www.ivoa.net/xml/VODataService/v1.1\#Table}}$$\\
196     This element may contain any mix of elements allowed by the VODataService XML schema.
197 pdowler.cadc 3232
198 major.brian 3455 In the REST binding, the TableSet metadata shall be a hierarchical web resource with a registered URL. There are two levels of TableSet metadata detail that may be returned from the base \textit{tables} endpoint. Maximum detail (max) is the complete metadata including all details of the Table elements. Minimum detail (min) includes the full set of Table elements with names and optional descriptions, but does not include Table elements of type Column or ForeignKey.
199 pdowler.cadc 3232
200 major.brian 3455 If the parameter \textit{detail} accompanies the request with values of either \textit{max} or \textit{min}, the service should take this as a suggestion as to what level of detail to return, but may return either level. If the parameter \textit{detail} is not present, the service may choose the level of metadata detail to return.
202     For example, the request:
204 pdowler.cadc 3233 \begin{verbatim}
205     GET http://example.net/srv/tables?detail=min
206     \end{verbatim}
208 major.brian 3455 should be taken as a suggestion to return the minimum level of TableSet metadata detail.
209 pdowler.cadc 3233
210 major.brian 3455 Services with a large number of tables and/or columns cannot normally respond with a usable TableSet document that has the maximum level of detail so may wish to always respond with the minimum level of detail.
212 major.brian 3583 The REST endpoint must also support a child resource for each table described in the TableSet document. The child resource must be named as it appears in the name of the corresponding child Table element. For example:
213 pdowler.cadc 3233
214     \begin{verbatim}
215     GET http://example.net/srv/tables/ivoa.ObsCore
216     \end{verbatim}
218 major.brian 3583 would return a Table document describing the ivoa.ObsCore table in full detail, starting:
219 pdowler.cadc 3233
220 major.brian 3583 \begin{verbatim}
221     <vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0">
222     <name>ivoa.ObsCore</name>
223     <column>
224     ...
225     \end{verbatim}
227 major.brian 4206 \subsection{Non-service metadata (non-normative)}
229     There may be other metadata associated with a service than the capability metadata described above.
231     \begin{itemize}
232     \item Every service has the Dublin Core resource metadata \citep{std:DUBLINCORE}.
233     \item Some services are associated with registered applications.
234     \item Some services are associated with registered data collections.
235     \end{itemize}
237     None of these are explicitly provided for in this version of VOSI. Some might be covered in later versions of VOSI.
239 pdowler.cadc 3232 \section{Registration of VOSI endpoints}
240 major.brian 3306 \label{sec:endpoints}
241 pdowler.cadc 3232
242     The endpoints for the service and availability metadata shall be included in the registration of each service that provides them.
244     \begin{tabular}{l l l l l}
245     \label{tab:registration}
246     Endpoint type & standardID value \\
247 msdemlei 3389 availability & \nolinkurl{ivo://ivoa.net/std/VOSI#availability} \\
248     capabilities & \nolinkurl{ivo://ivoa.net/std/VOSI#capabilities} \\
249     tables (1.0) & \nolinkurl{ivo://ivoa.net/std/VOSI#tables} \\
250     tables (1.1) & \nolinkurl{ivo://ivoa.net/std/VOSI#tables-1.1} \\
251 pdowler.cadc 3232 \end{tabular}
253 msdemlei 3389 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}.
254 pdowler.cadc 3232
255 msdemlei 3389 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}.
256 pdowler.cadc 3232
257 major.brian 3764 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}, or, for version 1.1, \nolinkurl{ivo://ivoa.net/std/VOSI\#tables-1.1}.
258 pdowler.cadc 3232
259 msdemlei 3389 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}).
260 pdowler.cadc 3232
261 major.brian 3737 The capabilities and availability endpoints must not require any credentials to view. Thus, the \xmlel{interface} registry entries for capabilities and availability must not contain a securityMethod element.
263 pdowler.cadc 3232 \section{Example VOSI responses}
264 major.brian 3306 \label{sec:examples}
265 pdowler.cadc 3232
266 msdemlei 3389 \subsection{Example 1: SIA 1.0 capabilities}
268 pdowler.cadc 3232 A sample response from a capabilities resource describing an SIA service.
270 msdemlei 3389 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
271 pdowler.cadc 3232 <?xml version="1.0" encoding="UTF-8"?>
272     <vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
273     xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
274 major.brian 3764 xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
275 pdowler.cadc 3232 xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0"
276 major.brian 3764 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
277 pdowler.cadc 3232
278     <!-- a generic capability (for custom, non-standard interfaces) -->
279     <capability>
280     <interface xsi:type="vr:WebBrowser">
281 msdemlei 3389 <accessURL use="full"> http://adil.ncsa.uiuc.edu/siaform.html
282     </accessURL>
283 pdowler.cadc 3232 </interface>
284     </capability>
286     <!-- the SIA capability -->
288 msdemlei 3389 <capability xsi:type="sia:SimpleImageAccess"
289     standardID="ivo://ivoa.net/std/SIA">
290 pdowler.cadc 3232 <interface xsi:type="vs:ParamHTTP" role="std">
291 msdemlei 3389 <accessURL> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f&amp;
292     </accessURL>
293 pdowler.cadc 3232 </interface>
295     <imageServiceType>Pointed</imageServiceType>
297     <maxQueryRegionSize>
299     <long>360.0</long>
301     <lat>180.0</lat>
303     </maxQueryRegionSize>
305     <maxImageExtent>
307     <long>360.0</long>
309     <lat>180.0</lat>
311     </maxImageExtent>
313     <maxImageSize>
315     <long>5000</long>
317     <lat>5000</lat>
319     </maxImageSize>
321     <maxFileSize>100000000</maxFileSize>
323     <maxRecords>5000</maxRecords>
325     </capability>
327     <!-- the interface that returns this capability -->
328     <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
329     <interface xsi:type="vs:ParamHTTP" role="std">
330 msdemlei 3389 <accessURL use="full">
331     http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/capabilities
332     </accessURL>
333 pdowler.cadc 3232 </interface>
334     </capability>
336     <!-- the interface that returns this availability-->
337     <capability standardID="ivo://ivoa.net/std/VOSI#availability">
338     <interface xsi:type="vs:ParamHTTP" role="std">
339 msdemlei 3389 <accessURL use="full">
340     http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/availability
341     </accessURL>
342 pdowler.cadc 3232 </interface>
343     </capability>
345     </vosi:capabilities>
346     \end{lstlisting}
349 major.brian 3455 \subsection{Example 2: TAP tables, maximum detail}
350 msdemlei 3389
351 major.brian 3455 A sample response from a tables resource describing a TAP service in full (maximum) detail.
352 pdowler.cadc 3232
353     \begin{lstlisting}[language=XML]
354     <?xml version="1.0" encoding="UTF-8"?>
355     <vosi:tableset
356     xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
357     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
358 major.brian 3764 xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
359     version="1.1">
360 pdowler.cadc 3232
361     <schema>
362     <name>cfht </name>
363     <table type="output">
364     <name>cfht.deepU </name>
365     <column>
366     <name>cfhtlsID </name>
367 major.brian 3764 <dataType xsi:type="vs:TAP" size="30">adql:VARCHAR </dataType>
368 pdowler.cadc 3232 </column>
369     <column>
370     <name>survey </name>
371 major.brian 3764 <dataType xsi:type="vs:TAP" size="6">adql:VARCHAR </dataType>
372 pdowler.cadc 3232 </column>
373     <column>
374     <name>field </name>
375 major.brian 3764 <dataType xsi:type="vs:TAP" size="2">adql:VARCHAR </dataType>
376 pdowler.cadc 3232 </column>
377     <column>
378     <name>pointing </name>
379 major.brian 3764 <dataType xsi:type="vs:TAP" size="6">adql:VARCHAR </dataType>
380 pdowler.cadc 3232 </column>
381     <column>
382     <name>selectionFilter </name>
383 major.brian 3764 <dataType xsi:type="vs:TAP" size="2">adql:VARCHAR </dataType>
384 pdowler.cadc 3232 </column>
385     </table>
387     <table type="output">
388     <name>TAP_SCHEMA.keys </name>
389     <column>
390     <name>key_id </name>
391 msdemlei 3389 <description>unique key to join to TAP_SCHEMA.key_columns
392     </description>
393 major.brian 3764 <dataType xsi:type="vs:TAP" size="64">adql:VARCHAR </dataType>
394 pdowler.cadc 3232 </column>
395     <column>
396     <name>from_table </name>
397     <description>the table with the foreign key </description>
398 major.brian 3764 <dataType xsi:type="vs:TAP" size="64">adql:VARCHAR </dataType>
399 pdowler.cadc 3232 </column>
400     <column>
401     <name>target_table </name>
402     <description>the table with the primary key </description>
403 major.brian 3764 <dataType xsi:type="vs:TAP" size="64">adql:VARCHAR </dataType>
404 pdowler.cadc 3232 </column>
405     </table>
407     </schema>
409     </vosi:tableset>
410     \end{lstlisting}
412 major.brian 3455 \subsection{Example 3: Tables, minimum detail}
413 msdemlei 3389
414 major.brian 3455 A sample response from a tables resource with no Column or ForeignKey elements.
415 pdowler.cadc 3233
416     \begin{lstlisting}[language=XML]
417     <?xml version="1.0" encoding="UTF-8"?>
418     <vosi:tableset
419     xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
420     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
421 major.brian 3764 xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
422     version="1.1">
423 pdowler.cadc 3233
424     <schema>
425     <name>cfht </name>
426     <table type="output">
427     <name>cfht.deepU </name>
428     </table>
429     </schema>
431     <schema>
432     <name>TAP_SCHEMA</schema>
433     <table type="output">
434     <name>TAP_SCHEMA.tables </name>
435     </table>
436     <table type="output">
437     <name>TAP_SCHEMA.columns </name>
438     </table>
439     <table type="output">
440     <name>TAP_SCHEMA.keys </name>
441     </table>
442     <table type="output">
443     <name>TAP_SCHEMA.key_columns </name>
444     </table>
445     </schema>
447     </vosi:tableset>
448     \end{lstlisting}
450 msdemlei 3389 \subsection{Example 4: Child table resource}
452 pdowler.cadc 3233 A sample response from a child table resource (e.g. http://example.net/srv/tables/TAP\_SCHEMA.columns).
454     \begin{lstlisting}[language=XML]
455     <?xml version="1.0" encoding="UTF-8"?>
456     <vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
457 major.brian 3764 xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
458     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
459     type="output" version="1.1">
460 pdowler.cadc 3233 <name>TAP_SCHEMA.columns</name>
461     <column>
462     <name>table_name</name>
463     <description>the table this column belongs to</description>
464 major.brian 3764 <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
465 pdowler.cadc 3233 </column>
466     <column>
467     <name>column_name</name>
468     <description>the column name</description>
469 major.brian 3764 <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
470 pdowler.cadc 3233 </column>
471     <column>
472     <name>utype</name>
473     <description>lists the utypes of columns in the tableset</description>
474 major.brian 3764 <dataType xsi:type="vs:TAPType" size="512">VARCHAR</dataType>
475 pdowler.cadc 3233 </column>
476     <column>
477     <name>ucd</name>
478     <description>lists the UCDs of columns in the tableset</description>
479 major.brian 3764 <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
480 pdowler.cadc 3233 </column>
481     <column>
482     <name>unit</name>
483     <description>lists the unit used for column values in the tableset</description>
484 major.brian 3764 <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
485 pdowler.cadc 3233 </column>
486     <column>
487     <name>description</name>
488     <description>describes the columns in the tableset</description>
489 major.brian 3764 <dataType xsi:type="vs:TAPType" size="512">VARCHAR</dataType>
490 pdowler.cadc 3233 </column>
491     <column>
492     <name>datatype</name>
493     <description>lists the ADQL datatype of columns in the tableset</description>
494 major.brian 3764 <dataType xsi:type="vs:TAPType" size="64">VARCHAR</dataType>
495 pdowler.cadc 3233 </column>
496     <column>
497     <name>size</name>
498     <description>lists the size of variable-length columns in the tableset</description>
499 major.brian 3764 <dataType xsi:type="vs:TAPType">INTEGER</dataType>
500 pdowler.cadc 3233 </column>
501     <column>
502     <name>principal</name>
503     <description>a principal column; 1 means 1, 0 means 0</description>
504 major.brian 3764 <dataType xsi:type="vs:TAPType">INTEGER</dataType>
505 pdowler.cadc 3233 </column>
506     <column>
507     <name>indexed</name>
508     <description>an indexed column; 1 means 1, 0 means 0</description>
509 major.brian 3764 <dataType xsi:type="vs:TAPType">INTEGER</dataType>
510 pdowler.cadc 3233 </column>
511     <column>
512     <name>std</name>
513     <description>a standard column; 1 means 1, 0 means 0</description>
514 major.brian 3764 <dataType xsi:type="vs:TAPType">INTEGER</dataType>
515 pdowler.cadc 3233 </column>
516     <foreignKey>
517     <targetTable>TAP_SCHEMA.tables</targetTable>
518     <fkColumn>
519     <fromColumn>table_name</fromColumn>
520     <targetColumn>table_name</targetColumn>
521     </fkColumn>
522     </foreignKey>
523     </vosi:table>
524     \end{lstlisting}
526 msdemlei 3389 \subsection{Example 5: Availability}
528 pdowler.cadc 3233 A sample response from an availability resource.
530     \begin{lstlisting}[language=XML]
531     <vosi:availability xmlns:vosi="http://www.ivoa.net/xml/VOSIAvailability/v1.0">
532     <vosi:available>true</vosi:available>
533     <vosi:note>service is accepting queries</vosi:note>
534     </vosi:availability>
535     \end{lstlisting}
537 pdowler.cadc 3232 \appendix
539     \section{The Complete VOSICapabilities Schema}
540 major.brian 3306 \label{appendix:capabilities}
541 pdowler.cadc 3232 \begin{lstlisting}[language=XML]
542     <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
543     xmlns:tns="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
544     xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
545     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
546     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
547     elementFormDefault="qualified"
548     attributeFormDefault="unqualified"
549 major.brian 3764 version="1.1">
550 pdowler.cadc 3232
551     <xsd:annotation>
552     <xsd:documentation>
553     A schema for formatting service capabilities as returned by a
554     capabilities resource, defined by the IVOA Support Interfaces
555     specification (VOSI).
557     See http://www.ivoa.net/Documents/latest/VOSI.html.
558     </xsd:documentation>
559     </xsd:annotation>
561     <xsd:import namespace="http://www.ivoa.net/xml/VOResource/v1.0"
562     schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0" />
564     <!--
565     - the root element for a VOSI capabilities metadata (section 3.1)
566     -->
568     <xsd:element name="capabilities">
569     <xsd:annotation>
570     <xsd:documentation>
571     A listing of capabilities supported by a service
572     </xsd:documentation>
573     </xsd:annotation>
575     <xsd:complexType>
576     <xsd:sequence>
577     <xsd:element name="capability" type="vr:Capability"
578     form="unqualified" minOccurs="0" maxOccurs="unbounded">
580     <xsd:annotation>
581     <xsd:documentation>
582     A capability supported by the service.
583     </xsd:documentation>
585     <xsd:documentation>
586     A protocol-specific capability is included by specifying a
587     vr:Capability sub-type via an xsi:type attribute on this
588     element.
589     </xsd:documentation>
590     </xsd:annotation>
592     </xsd:element>
594     </xsd:sequence>
596     </xsd:complexType>
598     </xsd:element>
600     </xsd:schema>
601     \end{lstlisting}
603     \section{The Complete VOSIAvailability Schema}
604 major.brian 3306 \label{appendix:availability}
605 pdowler.cadc 3232 \begin{lstlisting}[language=XML]
606     <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
607     xmlns:tns="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
608     xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
609     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
610     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
611     elementFormDefault="qualified"
612     attributeFormDefault="unqualified"
613 major.brian 3764 version="1.1">
614 pdowler.cadc 3232
615     <xsd:annotation>
616     <xsd:documentation>
617     A schema for formatting availability metadata as returned by an
618     availability resource defined in the IVOA Support Interfaces
619     specification (VOSI).
621     See http://www.ivoa.net/Documents/latest/VOSI.html.
622     </xsd:documentation>
623     </xsd:annotation>
625     <!--
626     - the root element for a VOSI availability (section 3.3)
627     -->
628     <xsd:element name="availability" type="tns:Availability"/>
630     <xsd:complexType name="Availability">
631     <xsd:sequence>
633     <xsd:element name="available" type="xsd:boolean">
634     <xsd:annotation>
635     <xsd:documentation>
636     Indicates whether the service is currently available.
637     </xsd:documentation>
638     </xsd:annotation>
639     </xsd:element>
641     <xsd:element name="upSince" type="xsd:dateTime" minOccurs="0">
642     <xsd:annotation>
643     <xsd:documentation>
644     The instant at which the service last became available.
645     </xsd:documentation>
646     </xsd:annotation>
647     </xsd:element>
649     <xsd:element name="downAt" type="xsd:dateTime" minOccurs="0">
650     <xsd:annotation>
651     <xsd:documentation>
652     The instant at which the service is next scheduled to become
653     unavailable.
654     </xsd:documentation>
655     </xsd:annotation>
656     </xsd:element>
658     <xsd:element name="backAt" type="xsd:dateTime" minOccurs="0">
659     <xsd:annotation>
660     <xsd:documentation>
661     The instant at which the service is scheduled to become available
662     again after a period of unavailability.
663     </xsd:documentation>
664     </xsd:annotation>
665     </xsd:element>
667     <xsd:element name="note" type="xsd:string"
668     minOccurs="0" maxOccurs="unbounded">
669     <xsd:annotation>
670     <xsd:documentation>
671     A textual note concerning availability.
672     </xsd:documentation>
673     </xsd:annotation>
674     </xsd:element>
676     </xsd:sequence>
678     </xsd:complexType>
680     </xsd:schema>
681     \end{lstlisting}
683     \section{The Complete VOSITables Schema}
684 major.brian 3306 \label{appendix:tables}
685 pdowler.cadc 3232 \begin{lstlisting}[language=XML]
686     <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSITables/v1.0"
687     xmlns:tns="http://www.ivoa.net/xml/VOSITables/v1.0"
688     xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
689     xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
690     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
691     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
692     elementFormDefault="qualified"
693     attributeFormDefault="unqualified"
694 pdowler.cadc 3233 version="1.1">
695 pdowler.cadc 3232
696     <xsd:annotation>
697     < xsd:documentation>
698     A schema for formatting table metadata as returned by a
699     tables resource, defined by the IVOA Support Interfaces
700     specification (VOSI).
702     See http://www.ivoa.net/Documents/latest/VOSI.html.
703     </xsd:documentation>
704     </xsd:annotation>
706     <xsd:import namespace="http://www.ivoa.net/xml/VODataService/v1.1"
707     schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1" />
709     <!--
710 pdowler.cadc 3233 - the root element for a VOSI tableset metadata
711 pdowler.cadc 3232 -->
712     <xsd:element name="tableset" type="vs:TableSet" >
713     <xsd:annotation>
714     <xsd:documentation>
715     A description of the table metadata supported by the
716     service associated with a VOSI-enabled resource.
717     </xsd:documentation>
718     </xsd:annotation>
719     </xsd:element>
720 pdowler.cadc 3233
721     <!--
722     - single table root element for a VOSI table metadata
723     -->
724     <xsd:element name="table" type="vs:Table" >
725     <xsd:annotation>
726     <xsd:documentation>
727     A description of a single table supported by the
728     service associated with a VOSI-enabled resource.
729     </xsd:documentation>
730     </xsd:annotation>
731     </xsd:element>
732 pdowler.cadc 3232
733     </xsd:schema>
734     \end{lstlisting}
736     \section{Use Case for Capability Harvesting (non-normative)}
737 major.brian 3306 \label{appendix:harvesting}
738 pdowler.cadc 3232
739 major.brian 3306 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.
740 pdowler.cadc 3232
741 msdemlei 3389 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.
742 pdowler.cadc 3232
743 msdemlei 3389 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.
744 pdowler.cadc 3232
745     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.
747 msdemlei 3389 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?
748 pdowler.cadc 3232
749 msdemlei 3389 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.
750 pdowler.cadc 3232
751 msdemlei 3389 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.
752 pdowler.cadc 3232
753     \section{Changes from Previous Versions}
754 major.brian 3306 \label{appendix:changes}
755 pdowler.cadc 3232
756 major.brian 3303 \subsection{Changes since REC-VOSI-20110531}
757 pdowler.cadc 3233
758 major.brian 3306 Added alternate root element (table) to VOSITables schema.
759 pdowler.cadc 3233
760 major.brian 3455 Extended VOSITables REST binding to include detail level and parameter and child table resource for scalability.
761 major.brian 3306
762     Defined \#tables-1.1 standardID.
764     Removed references to SOAP bindings.
766 pdowler.cadc 3232 \subsection{Changes since PR-20101206}
768     Added Appendix B, use case discussion
770     Formatting comments from RFC addressed: typos, etc.
772     \subsection{Changes since PR-20100311}
774     Inclusion of IVOA Architecture text
776     Restructuring and clarification in response to RFC comments
778     Inclusion of VOSITables schema in appendix
780     Second example added for a TAP service response
782     \subsection{Changes since WD-20090825}
784     Mandate the use of VOSICapabilities to return capabilities
786     S2.1: added non-normative note about capability sub-types; added example capabilities metadata
788     Recommend the inclusion of VOSI interfaces in capability metadata
790     S2.5: When returning capabilities metadata, require VOSI (REST) accessURLs to have use="full"; recommend this use of ParamHTTP.
792     Rename Availability schema to VOSIAvailability; added VOSICapabilities schema.
794     \subsection{Changes since WD-20081030}
796     The REST binding is made mandatory for all kinds of service. Details of the SOAP binding, including its WSDL contract, are removed.
798     The definition of the root element for the table-metadata document is corrected. Instead of requiring the tableset element from VODataService 1.1 (which element does not exist in that schema), the text now requires an element of type TableSet.
801     \bibliography{ivoatex/ivoabib}
804     \end{document}

ViewVC Help
Powered by ViewVC 1.1.26