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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3303 - (show annotations)
Thu Apr 14 18:47:12 2016 UTC (4 years, 3 months ago) by major.brian
File MIME type: application/x-tex
File size: 42033 byte(s)
Changed VOSI 1.1 from WD to PR
1 \documentclass[11pt,letter]{ivoa}
2 \input tthdefs
3
4 \usepackage{listings}
5 \lstloadlanguages{XML}
6 \lstset{flexiblecolumns=true,basicstyle=\small,tagstyle=\ttfamily}
7
8 \title{IVOA Support Interfaces}
9
10 \ivoagroup{Grid and Web Services Working Group}
11
12 \author{Grid and Web Services Working Group}
13
14 \editor{Matthew Graham}
15 \editor{Guy Rixon}
16 \editor{Patrick Dowler}
17
18 \previousversion[http://www.ivoa.net/documents/VOSI/20110531/REC-VOSI-1.0-20110531.html]{VOSI-1.0}
19
20 \begin{document}
21 \begin{abstract}
22 This document describes the minimum interface that a (SOAP- or REST-based) 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.
23 \end{abstract}
24
25
26 \section*{Acknowledgments}
27
28 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.
29
30 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.
31
32 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.
33
34 \section*{Conformance-related definitions}
35
36 The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
37 ``OPTIONAL'' (in upper or lower case) used in this document are to be
38 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
39
40 The \emph{Virtual Observatory (VO)} is a
41 general term for a collection of federated resources that can be used
42 to conduct astronomical research, education, and outreach.
43 The \href{http://www.ivoa.net}{International
44 Virtual Observatory Alliance (IVOA)} is a global
45 collaboration of separately funded projects to develop standards and
46 infrastructure that enable VO applications.
47
48
49 \section{Introduction}
50
51 The web services that comprise much of the Virtual Observatory (VO) come in two forms: SOAP-based (Simple Object Access Protocol, [1]) ones such as footprint and spectrum services [2], SkyNodes and Open SkyQuery [3], registry interfaces [4] and CDS access [5]; and RESTful (REpresentational State Transfer, [6]) ones such as TAP [7] and other second generation data access (DAL) services, and VOSpace 2.0 [8]. This document describes a set of common basic functions that all these services should provide in the form of a standard support interface in order to support the effective management of the VO. It is agreed that 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.
52
53 The IVOA Web Services Basic Profile [9] mandates that a compliant SOAP-based web service should have the interface defined in this specification, as expressed using the standard WSDL (Web Services Description Language, [10]) format. For RESTful services, the requirement for the support interface is stated in the specification for each kind of service. A contract for a RESTful service may specify extra constraints (e.g., on the form of the URIs) for the support interface. Such a contract might be expressed using the WADL (Web Application Description Language, [15]) format.
54
55 \subsection{Role within the VO Architecture}
56
57 The IVOA Architecture [11] 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 Fig. 1.
58
59 \begin{figure}
60 \centering
61
62 % Get the architecture diagram from the TCG chair
63 % http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG
64 % If they give you a PDF, for now dumb it down to a png by
65 % convert -antialias -density 72x72 archdiag.pdf archdiag.png
66 % Oh -- Notes don't need this; you'd have to remove archdiag.png
67 % from FIGURES in the Makefile, too.
68
69 \includegraphics[width=0.9\textwidth]{archdiag.png}
70 \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.}
71 \label{fig:archdiag}
72 \end{figure}
73
74 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 B for a more detailed description of this use case.)
75
76 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.
77
78 \section{Interface bindings}
79
80 The standard interface returns metadata without changing the state of the service with which it is associated. This could, in principle, be implemented in any of three ways:
81
82 As extra SOAP operations on an existing SOAP endpoint of the service with which it is associated. This would be a 'SOAP binding' of VOSI.
83 As SOAP operations on a separate SOAP endpoint. This would be an alternate form of the SOAP binding.
84 As web resources with distinct URLs, without using the SOAP protocol. This is the 'REST binding' for the standard interface.
85
86 This standard requires the REST binding of VOSI even when applied to services that otherwise use SOAP. No details of the SOAP binding are given in this version of the standard.
87
88 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.
89
90 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 Capabilitys are given in section 4.
91
92 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.
93
94 \section{Metadata specification}
95
96 There are various classes of metadata that might be returned by a service through its standard interface:
97
98 \begin{itemize}
99 \item those describing its functional capabilities
100 \item those describing its operational behaviour - availability, reliability, etc.
101 \item those describing tabular data handled by the service
102 \item those describing other aspects of the service
103 \end{itemize}
104
105 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:
106
107 \begin{verbatim}
108 {http://some.name.space}elementName
109 \end{verbatim}
110
111 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 [12].
112
113 \subsection{Capability metadata}
114
115
116 Note:
117 '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.
118
119 This interface provides the service metadata in the form of a list of Capability descriptions. Each of these descriptions is an XML element that:
120
121 \begin{itemize}
122 \item states that the service provides a particular, IVOA-standard function;
123 \item lists the interfaces for invoking that function;
124 \item records any details of the implementation of the function that are not defined as default or constant in the standard for that function.
125 \end{itemize}
126
127 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.
128
129 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:
130
131 \begin{itemize}
132 \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.
133 \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.
134 \end{itemize}
135
136 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 A.1 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
137 {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 [12]).
138
139
140 Note:
141 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).
142
143 The VOResource list of capabilities should include capabilities describing VOSI endpoints as specified in section 4.
144
145 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.
146
147 All VO services should provide this interface.
148
149 \subsection{Non-service metadata (non-normative)}
150
151 There may be other metadata associated with a service than the capability metadata described above.
152
153 \begin{itemize}
154 \item Every service has the Dublin Core resource metadata [13].
155 \item Some services are associated with registered applications.
156 \item Some services are associated with registered data collections.
157 \end{itemize}
158
159 None of these are explicitly provided for in this version of VOSI. Some might be covered in later versions of VOSI.
160
161 \subsection{Availability metadata}
162
163 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.
164
165 \begin{itemize}
166 \item available - whether the service is currently accepting requests
167 \item upSince - duration for which the service has been continuously available
168 \item downAt - the instant at which the service is next scheduled to be unavailable
169 \item backAt - the instant at which the service is scheduled to become available again after down time;
170 \item note - textual note, e.g. explaining the reason for unavailaility.
171 \end{itemize}
172
173 The elements upSince, downAt, backAt and note are optional. The available element is mandatory. There may be more than one note element.
174
175 The XML document shall conform to the schema given in appendix A.2 of this specification.
176
177 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.
178
179 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.
180
181 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.
182
183 In the REST binding, the availability shall be a single web resource with a registered URL
184
185 All VO services shall provide this interface.
186
187 \subsection{Table metadata}
188
189 Some services deal with tabular data. These data may be the target of ADQL queries, as in TAP [7], 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.
190
191 The VODataService standard [14] defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.
192
193 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
194 {http://www.ivoa.net/xml/VODataService/v1.1}TableSet. The table metadata for a single table (see below) shall be represented as an
195 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.
196
197 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.
198
199 \begin{verbatim}
200 GET http://example.net/srv/tables?detail=min
201 \end{verbatim}
202
203 If the caller requests detail=min, the response (TableSet) document must not incude elements of type Column or ForeignKey; the tables described have names and optional descriptions but no column or foreigh key details).
204
205 The REST endpoint must also support a child resource for each table described in the TableSet document. The child resource must be
206 named with the fully-qualified table name and without any intervening schema name. For example:
207
208 \begin{verbatim}
209 GET http://example.net/srv/tables/ivoa.ObsCore
210 \end{verbatim}
211
212 would return a Table document describing the ivoa.ObsCore table.
213
214 Services with a large number of tables and/or columns cannot normally respond with a usable TableSet document. These services may
215 force the caller to accept the minimum detail level by redirecting requests without the detail=min parameter. The redirect should use HTTP status code 303 (See Other) with a (HTTP header) Location value that includes the detail=min parameter. Clients can make use of detail=min to get a list of available tables and then use the child table resource to get details about individual tables.
216
217
218 \section{Registration of VOSI endpoints}
219
220 The endpoints for the service and availability metadata shall be included in the registration of each service that provides them.
221
222 \begin{tabular}{l l l l l}
223 \label{tab:registration}
224 Endpoint type & standardID value \\
225 availability & ivo://ivoa.net/std/VOSI\#availability \\
226 capabilities & ivo://ivoa.net/std/VOSI\#capabilities \\
227 tables (1.0) & ivo://ivoa.net/std/VOSI\#tables \\
228 tables (1.1) & ivo://ivoa.net/std/VOSI\#tables-1.1 \\
229 \end{tabular}
230
231 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 [12]). The value of the standardID attribute of the capability shall be ivo://ivoa.net/std/VOSI\#availability.
232
233 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.
234
235 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.
236
237 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).
238
239 \section{Example VOSI responses}
240
241 Example 1:
242 A sample response from a capabilities resource describing an SIA service.
243
244 \begin{lstlisting}[language=XML]
245 <?xml version="1.0" encoding="UTF-8"?>
246 <vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
247 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
248 xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0"
249 xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0"
250 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
251 xsi:schemaLocation="http://www.ivoa.net/xml/VOSI/v1.0 http://www.ivoa.net/xml/VOSI/v1.0
252 http://www.ivoa.net/xml/VOResource/v1.0 http://www.ivoa.net/xml/VOResource/v1.0
253 http://www.ivoa.net/xml/VODataService/v1.0 http://www.ivoa.net/xml/VODataService/v1.0
254 http://www.ivoa.net/xml/SIA/v1.0 http://www.ivoa.net/xml/SIA/v1.0">
255
256 <!-- a generic capability (for custom, non-standard interfaces) -->
257 <capability>
258 <interface xsi:type="vr:WebBrowser">
259 <accessURL use="full"> http://adil.ncsa.uiuc.edu/siaform.html </accessURL>
260 </interface>
261 </capability>
262
263 <!-- the SIA capability -->
264
265 <capability xsi:type="sia:SimpleImageAccess" standardID="ivo://ivoa.net/std/SIA">
266 <interface xsi:type="vs:ParamHTTP" role="std">
267 <accessURL> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f&amp; </accessURL>
268 </interface>
269
270 <imageServiceType>Pointed</imageServiceType>
271
272 <maxQueryRegionSize>
273
274 <long>360.0</long>
275
276 <lat>180.0</lat>
277
278 </maxQueryRegionSize>
279
280 <maxImageExtent>
281
282 <long>360.0</long>
283
284 <lat>180.0</lat>
285
286 </maxImageExtent>
287
288 <maxImageSize>
289
290 <long>5000</long>
291
292 <lat>5000</lat>
293
294 </maxImageSize>
295
296 <maxFileSize>100000000</maxFileSize>
297
298 <maxRecords>5000</maxRecords>
299
300 </capability>
301
302 <!-- the interface that returns this capability -->
303 <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
304 <interface xsi:type="vs:ParamHTTP" role="std">
305 <accessURL use="full"> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/capabilities </accessURL>
306 </interface>
307 </capability>
308
309 <!-- the interface that returns this availability-->
310 <capability standardID="ivo://ivoa.net/std/VOSI#availability">
311 <interface xsi:type="vs:ParamHTTP" role="std">
312 <accessURL use="full"> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/availability </accessURL>
313 </interface>
314 </capability>
315
316 </vosi:capabilities>
317 \end{lstlisting}
318
319
320 Example 2:
321 A sample response from a tables resource describing a TAP service.
322
323 \begin{lstlisting}[language=XML]
324 <?xml version="1.0" encoding="UTF-8"?>
325 <vosi:tableset
326 xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
327 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
328 xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">
329
330 <schema>
331 <name>cfht </name>
332 <table type="output">
333 <name>cfht.deepU </name>
334 <column>
335 <name>cfhtlsID </name>
336 <dataType xsi:type="vod:TAP" size="30">adql:VARCHAR </dataType>
337 </column>
338 <column>
339 <name>survey </name>
340 <dataType xsi:type="vod:TAP" size="6">adql:VARCHAR </dataType>
341 </column>
342 <column>
343 <name>field </name>
344 <dataType xsi:type="vod:TAP" size="2">adql:VARCHAR </dataType>
345 </column>
346 <column>
347 <name>pointing </name>
348 <dataType xsi:type="vod:TAP" size="6">adql:VARCHAR </dataType>
349 </column>
350 <column>
351 <name>selectionFilter </name>
352 <dataType xsi:type="vod:TAP" size="2">adql:VARCHAR </dataType>
353 </column>
354 </table>
355
356 <table type="output">
357 <name>TAP_SCHEMA.keys </name>
358 <column>
359 <name>key_id </name>
360 <description>unique key to join to TAP_SCHEMA.key_columns </description>
361 <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>
362 </column>
363 <column>
364 <name>from_table </name>
365 <description>the table with the foreign key </description>
366 <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>
367 </column>
368 <column>
369 <name>target_table </name>
370 <description>the table with the primary key </description>
371 <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>
372 </column>
373 </table>
374
375 </schema>
376
377 </vosi:tableset>
378 \end{lstlisting}
379
380 Example 3:
381 A sample response from a tables resource with detail=min parameter (e.g. http://example.net/srv/tables?detail=min).
382
383 \begin{lstlisting}[language=XML]
384 <?xml version="1.0" encoding="UTF-8"?>
385 <vosi:tableset
386 xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
387 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
388 xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">
389
390 <schema>
391 <name>cfht </name>
392 <table type="output">
393 <name>cfht.deepU </name>
394 </table>
395 </schema>
396
397 <schema>
398 <name>TAP_SCHEMA</schema>
399 <table type="output">
400 <name>TAP_SCHEMA.tables </name>
401 </table>
402 <table type="output">
403 <name>TAP_SCHEMA.columns </name>
404 </table>
405 <table type="output">
406 <name>TAP_SCHEMA.keys </name>
407 </table>
408 <table type="output">
409 <name>TAP_SCHEMA.key_columns </name>
410 </table>
411 </schema>
412
413 </vosi:tableset>
414 \end{lstlisting}
415
416 Example 4:
417 A sample response from a child table resource (e.g. http://example.net/srv/tables/TAP\_SCHEMA.columns).
418
419 \begin{lstlisting}[language=XML]
420 <?xml version="1.0" encoding="UTF-8"?>
421 <vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
422 xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1"
423 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="output">
424 <name>TAP_SCHEMA.columns</name>
425 <column>
426 <name>table_name</name>
427 <description>the table this column belongs to</description>
428 <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
429 </column>
430 <column>
431 <name>column_name</name>
432 <description>the column name</description>
433 <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
434 </column>
435 <column>
436 <name>utype</name>
437 <description>lists the utypes of columns in the tableset</description>
438 <dataType xsi:type="vod:TAPType" size="512">VARCHAR</dataType>
439 </column>
440 <column>
441 <name>ucd</name>
442 <description>lists the UCDs of columns in the tableset</description>
443 <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
444 </column>
445 <column>
446 <name>unit</name>
447 <description>lists the unit used for column values in the tableset</description>
448 <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
449 </column>
450 <column>
451 <name>description</name>
452 <description>describes the columns in the tableset</description>
453 <dataType xsi:type="vod:TAPType" size="512">VARCHAR</dataType>
454 </column>
455 <column>
456 <name>datatype</name>
457 <description>lists the ADQL datatype of columns in the tableset</description>
458 <dataType xsi:type="vod:TAPType" size="64">VARCHAR</dataType>
459 </column>
460 <column>
461 <name>size</name>
462 <description>lists the size of variable-length columns in the tableset</description>
463 <dataType xsi:type="vod:TAPType">INTEGER</dataType>
464 </column>
465 <column>
466 <name>principal</name>
467 <description>a principal column; 1 means 1, 0 means 0</description>
468 <dataType xsi:type="vod:TAPType">INTEGER</dataType>
469 </column>
470 <column>
471 <name>indexed</name>
472 <description>an indexed column; 1 means 1, 0 means 0</description>
473 <dataType xsi:type="vod:TAPType">INTEGER</dataType>
474 </column>
475 <column>
476 <name>std</name>
477 <description>a standard column; 1 means 1, 0 means 0</description>
478 <dataType xsi:type="vod:TAPType">INTEGER</dataType>
479 </column>
480 <foreignKey>
481 <targetTable>TAP_SCHEMA.tables</targetTable>
482 <fkColumn>
483 <fromColumn>table_name</fromColumn>
484 <targetColumn>table_name</targetColumn>
485 </fkColumn>
486 </foreignKey>
487 </vosi:table>
488 \end{lstlisting}
489
490 Example 5:
491 A sample response from an availability resource.
492
493 \begin{lstlisting}[language=XML]
494 <vosi:availability xmlns:vosi="http://www.ivoa.net/xml/VOSIAvailability/v1.0">
495 <vosi:available>true</vosi:available>
496 <vosi:note>service is accepting queries</vosi:note>
497 </vosi:availability>
498 \end{lstlisting}
499
500 \appendix
501
502 \section{The Complete VOSICapabilities Schema}
503 \begin{lstlisting}[language=XML]
504 <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
505 xmlns:tns="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
506 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
507 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
508 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
509 elementFormDefault="qualified"
510 attributeFormDefault="unqualified"
511 version="1.0rc1">
512
513 <xsd:annotation>
514 <xsd:documentation>
515 A schema for formatting service capabilities as returned by a
516 capabilities resource, defined by the IVOA Support Interfaces
517 specification (VOSI).
518
519 See http://www.ivoa.net/Documents/latest/VOSI.html.
520 </xsd:documentation>
521 </xsd:annotation>
522
523 <xsd:import namespace="http://www.ivoa.net/xml/VOResource/v1.0"
524 schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0" />
525
526 <!--
527 - the root element for a VOSI capabilities metadata (section 3.1)
528 -->
529
530 <xsd:element name="capabilities">
531 <xsd:annotation>
532 <xsd:documentation>
533 A listing of capabilities supported by a service
534 </xsd:documentation>
535 </xsd:annotation>
536
537 <xsd:complexType>
538 <xsd:sequence>
539 <xsd:element name="capability" type="vr:Capability"
540 form="unqualified" minOccurs="0" maxOccurs="unbounded">
541
542 <xsd:annotation>
543 <xsd:documentation>
544 A capability supported by the service.
545 </xsd:documentation>
546
547 <xsd:documentation>
548 A protocol-specific capability is included by specifying a
549 vr:Capability sub-type via an xsi:type attribute on this
550 element.
551 </xsd:documentation>
552 </xsd:annotation>
553
554 </xsd:element>
555
556 </xsd:sequence>
557
558 </xsd:complexType>
559
560 </xsd:element>
561
562 </xsd:schema>
563 \end{lstlisting}
564
565 \section{The Complete VOSIAvailability Schema}
566 \begin{lstlisting}[language=XML]
567 <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
568 xmlns:tns="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
569 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
570 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
571 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
572 elementFormDefault="qualified"
573 attributeFormDefault="unqualified"
574 version="1.0rc1">
575
576 <xsd:annotation>
577 <xsd:documentation>
578 A schema for formatting availability metadata as returned by an
579 availability resource defined in the IVOA Support Interfaces
580 specification (VOSI).
581
582 See http://www.ivoa.net/Documents/latest/VOSI.html.
583 </xsd:documentation>
584 </xsd:annotation>
585
586 <!--
587 - the root element for a VOSI availability (section 3.3)
588 -->
589 <xsd:element name="availability" type="tns:Availability"/>
590
591 <xsd:complexType name="Availability">
592 <xsd:sequence>
593
594 <xsd:element name="available" type="xsd:boolean">
595 <xsd:annotation>
596 <xsd:documentation>
597 Indicates whether the service is currently available.
598 </xsd:documentation>
599 </xsd:annotation>
600 </xsd:element>
601
602 <xsd:element name="upSince" type="xsd:dateTime" minOccurs="0">
603 <xsd:annotation>
604 <xsd:documentation>
605 The instant at which the service last became available.
606 </xsd:documentation>
607 </xsd:annotation>
608 </xsd:element>
609
610 <xsd:element name="downAt" type="xsd:dateTime" minOccurs="0">
611 <xsd:annotation>
612 <xsd:documentation>
613 The instant at which the service is next scheduled to become
614 unavailable.
615 </xsd:documentation>
616 </xsd:annotation>
617 </xsd:element>
618
619 <xsd:element name="backAt" type="xsd:dateTime" minOccurs="0">
620 <xsd:annotation>
621 <xsd:documentation>
622 The instant at which the service is scheduled to become available
623 again after a period of unavailability.
624 </xsd:documentation>
625 </xsd:annotation>
626 </xsd:element>
627
628 <xsd:element name="note" type="xsd:string"
629 minOccurs="0" maxOccurs="unbounded">
630 <xsd:annotation>
631 <xsd:documentation>
632 A textual note concerning availability.
633 </xsd:documentation>
634 </xsd:annotation>
635 </xsd:element>
636
637 </xsd:sequence>
638
639 </xsd:complexType>
640
641 </xsd:schema>
642 \end{lstlisting}
643
644 \section{The Complete VOSITables Schema}
645 \begin{lstlisting}[language=XML]
646 <xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSITables/v1.0"
647 xmlns:tns="http://www.ivoa.net/xml/VOSITables/v1.0"
648 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
649 xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
650 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
651 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
652 elementFormDefault="qualified"
653 attributeFormDefault="unqualified"
654 version="1.1">
655
656 <xsd:annotation>
657 < xsd:documentation>
658 A schema for formatting table metadata as returned by a
659 tables resource, defined by the IVOA Support Interfaces
660 specification (VOSI).
661
662 See http://www.ivoa.net/Documents/latest/VOSI.html.
663 </xsd:documentation>
664 </xsd:annotation>
665
666 <xsd:import namespace="http://www.ivoa.net/xml/VODataService/v1.1"
667 schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1" />
668
669 <!--
670 - the root element for a VOSI tableset metadata
671 -->
672 <xsd:element name="tableset" type="vs:TableSet" >
673 <xsd:annotation>
674 <xsd:documentation>
675 A description of the table metadata supported by the
676 service associated with a VOSI-enabled resource.
677 </xsd:documentation>
678 </xsd:annotation>
679 </xsd:element>
680
681 <!--
682 - single table root element for a VOSI table metadata
683 -->
684 <xsd:element name="table" type="vs:Table" >
685 <xsd:annotation>
686 <xsd:documentation>
687 A description of a single table supported by the
688 service associated with a VOSI-enabled resource.
689 </xsd:documentation>
690 </xsd:annotation>
691 </xsd:element>
692
693 </xsd:schema>
694 \end{lstlisting}
695
696 \section{Use Case for Capability Harvesting (non-normative)}
697
698 In the section 1.2, we summarized the role that the metadata retrieval functions (sections 3.1 and 3.4) 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.
699
700 Some publishing registries [4] provide a publically 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.
701
702 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.
703
704 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.
705
706 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?
707
708 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.
709
710 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.
711
712 \section{Changes from Previous Versions}
713
714 \subsection{Changes since REC-VOSI-20110531}
715
716 Added alternate root element (table) to VOSITables schema. Extended VOSITables REST binding to include detail=min param and child table resource for scalability. Defined \#tables-1.1 standardID.
717
718 \subsection{Changes since PR-20101206}
719
720 Added Appendix B, use case discussion
721
722 Formatting comments from RFC addressed: typos, etc.
723
724 \subsection{Changes since PR-20100311}
725
726 Inclusion of IVOA Architecture text
727
728 Restructuring and clarification in response to RFC comments
729
730 Inclusion of VOSITables schema in appendix
731
732 Second example added for a TAP service response
733
734 \subsection{Changes since WD-20090825}
735
736 Mandate the use of VOSICapabilities to return capabilities
737
738 S2.1: added non-normative note about capability sub-types; added example capabilities metadata
739
740 Recommend the inclusion of VOSI interfaces in capability metadata
741
742 S2.5: When returning capabilities metadata, require VOSI (REST) accessURLs to have use="full"; recommend this use of ParamHTTP.
743
744 Rename Availability schema to VOSIAvailability; added VOSICapabilities schema.
745
746 \subsection{Changes since WD-20081030}
747
748 The REST binding is made mandatory for all kinds of service. Details of the SOAP binding, including its WSDL contract, are removed.
749
750 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.
751
752
753 \bibliography{ivoatex/ivoabib}
754
755
756 \end{document}

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