/[volute]/trunk/projects/grid/VOSI/rc/PR-VOSI-1.00-20101206.html
ViewVC logotype

Contents of /trunk/projects/grid/VOSI/rc/PR-VOSI-1.00-20101206.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1458 - (show annotations)
Tue May 10 20:29:48 2011 UTC (9 years, 4 months ago) by rplante@ncsa.uiuc.edu
File MIME type: text/html
File size: 44953 byte(s)
added 20101206 release as rc; copied to working pr
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html>
4 <head>
5 <style type="text/css">
6 .issue {background-color: yellow}
7 .postponedissue {background-color: yellow}
8 .def code
9 .future {background-color: pink}
10 .draftedit {background-color: white}
11 .draftdelete {background-color: white}
12 .note { margin-left: 4em }
13 code { font-weight: bold;
14 font-family: monospace }
15
16 div.exampleInner pre { margin-left: 1em;
17 margin-top: 0em; margin-bottom: 0em}
18 div.exampleOuter {border: 4px double gray;
19 margin: 0em; padding: 0em}
20 div.exampleInner { border-top-width: 4px;
21 border-top-style: double;
22 border-top-color: white;
23 border-bottom-width: 4px;
24 border-bottom-style: double;
25 border-bottom-color: white;
26 padding: 0px; margin: 0em }
27 div.exampleWrapper { margin: 4px }
28 div.exampleHeader { font-weight: bold;
29 margin: 4px}
30
31 div.schemaInner pre { margin-left: 1em;
32 margin-top: 0em; margin-bottom: 0em;
33 }
34 div.schemaOuter {border: 4px double gray; padding: 0em}
35 div.schemaInner { background-color: #eeeeee;
36 border-top-width: 4px;
37 border-top-style: double;
38 border-top-color: #d3d3d3;
39 border-bottom-width: 4px;
40 border-bottom-style: double;
41 border-bottom-color: #d3d3d3;
42 padding: 4px; margin: 0em }
43 div.schemaHeader { font-weight: bold;
44 margin: 4px}
45 </style>
46 <title>IVOA Proposed Recommendation - IVOA Support Interfaces</title>
47 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
48 <meta name="keywords" content="IVOA, International, Virtual, Observatory, Alliance" />
49 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
50 <meta name="maintainedBy" content="IVOA Document Coordinator, ivoadoc@ivoa.net" />
51 <link rel="stylesheet" href="http://ivoa.net/misc/ivoa_pr.css" type="text/css" />
52 </head>
53
54 <body>
55 <div class="head">
56 <a href="http://www.ivoa.net/"><img alt="IVOA" src="http://www.ivoa.net/pub/images/IVOA_wb_300.jpg" width="300" height="169"/></a>
57 <h1>IVOA Support Interfaces<br/>
58 Version 1.00-20101206</h1>
59 <h2>IVOA WG Proposed Recommendation 2010 December 6 </h2>
60
61 <dl>
62 <dt>This version:</dt>
63 <dd><a href="http://www.ivoa.net/Documents/VOSI/20101206/">
64 http://www.ivoa.net/Documents/VOSI/20101206/</a></dd>
65
66 <dt>Latest version:</dt>
67 <dd><a href="http://www.ivoa.net/Documents/latest/VOSI.html">
68 http://www.ivoa.net/Documents/latest/VOSI.html</a></dd>
69
70 <dt>Previous versions:</dt>
71 <dd>PR: <a href="http://www.ivoa.net/Documents/VOSI/20100311/">
72 http://www.ivoa.net/Documents/VOSI/20100311/</a> <br />
73 WD: <a href="http://www.ivoa.net/Documents/VOSI/20090825/">
74 http://www.ivoa.net/Documents/VOSI/20090825/</a> <br />
75 WD: <a href="http://www.ivoa.net/Documents/VOSI/20081030/">
76 http://www.ivoa.net/Documents/VOSI/20081030/</a></dd>
77 </dl>
78
79 <dl>
80 <dt>Working Group:</dt>
81 <dd><a
82 href="http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices">
83 http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices</a></dd>
84
85 <dt>Editors:</dt>
86 <dd><a
87 href="http://www.ivoa.net/twiki/bin/view/IVOA/MatthewGraham">Matthew
88 Graham</a><br/>
89 <a
90 href="http://www.ivoa.net/twiki/bin/view/IVOA/GuyRixon">Guy Rixon</a></dd>
91 <dt>Author(s):</dt>
92 <dd>
93 <a
94 href="http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices">Grid and Web
95 Services Working Group</a><br/>
96 <a href="http://www.ivoa.net/twiki/bin/view/IVOA/"></a>
97 </dd>
98 </dl>
99 <hr/></div>
100
101 <h2><a name="abstract" id="abstract">Abstract</a></h2>
102
103 <p>
104 This document describes the minimum interface that a (SOAP- or REST-based) web service requires to participate in the IVOA.
105 </p>
106
107 <div class="status">
108 <h2><a name="status" id="status">Status of this Document</a></h2>
109
110 <!-- Choose one of the following (and remove the rest)-->
111 <!--Note-->
112 <!--
113 <p>This is an IVOA Note expressing suggestions from and opinions of the authors.<br/>
114 It is intended to share best practices, possible approaches, or other perspectives on interoperability with the Virtual Observatory.
115 It should not be referenced or otherwise interpreted as a standard specification.</p>
116 <p>This is an IVOA Working Draft for review by IVOA members and other interested parties.<br/>
117 It is a draft document and may be updated, replaced, or obsoleted by other documents at any time.
118 It is inappropriate to use IVOA Working Drafts as reference materials -->
119 <!--or to cite them as other than "work in progress.</p>
120 -->
121 <!--Proposed Recommendation-->
122 <p>This is an IVOA Proposed Recommendation made available for public review.<br/>
123 It is appropriate to reference this document only as a recommended standard that is under review and which may be changed
124 before it is accepted as a full recommendation.<br/>
125 The first release of this document was 2010 March 11 .
126 </p>
127 <!--Recommendation
128 <p>This document has been produced by the IVOA "WG Name" Working Group.<br/>
129 It has been reviewed by IVOA Members and other interested parties, and has been endorsed by the IVOA Executive Committee as an IVOA Recommendation.
130 It is a stable document and may be used as reference material or cited as a normative reference from another document. IVOA's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment.
131 This enhances the functionality and interoperability inside the Astronomical Community.</p>
132 -->
133
134 A list of <a href="http://www.ivoa.net/Documents/">current IVOA Recommendations and other technical documents</a> can be found at http://www.ivoa.net/Documents/.
135
136 </div><br />
137
138 <h2><a name="acknowledgments" id="acknowledgments">Acknowledgments</a></h2>
139 <p>This document has been developed with support from the
140 <a href="http://www.nsf.gov/">National Science Foundation's</a>
141 Information Technology Research Program under Cooperative Agreement
142 AST0122449 with The Johns Hopkins University, from the
143 <a href="http://www.pparc.ac.uk/">UK Particle Physics and Astronomy
144 Research Council (PPARC)</a>, from the European Commission's (EC)
145 <a href="http://cordis.europa.eu/fp6/">Sixth
146 Framework Programme</a> via the <a href="http://www.astro-opticon.org/">
147 Optical Infrared Coordination Network (OPTICON)</a>, and from EC's
148 <a href="http://cordis.europa.eu/fp7/">Seventh Framework Programme</a>
149 via its
150 <a href="http://cordis.europa.eu/fp7/ict/e-infrastructure/home_en.html">
151 eInfrastructure Science Repositories initiative</a>. </p>
152
153 <p>This work is based on discussions and actions from the 2003 IVOA
154 meeting in Strasbourg and further discussions on registry
155 functionality at JHU late in 2003. Later inputs came from a local
156 meeting at JHU in Sept. 2004. William O'Mullane and Ani Thakar were the editors and primary authors for these early versions.</p>
157 <p>
158 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.
159 </p>
160
161 <h2><a name="conformance" id="conformance">Conformance related definitions</a></h2>
162 <p>The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and "OPTIONAL" (in upper or lower case) used in this document are to be interpreted as described in IETF standard, RFC 2119 [0].</p><p>
163 The <strong>Virtual Observatory (VO)</strong> is a general term for a
164 collection of federated resources that can be used to conduct
165 astronomical research, education, and outreach. The <strong>International Virtual Observatory Alliance (IVOA)</strong> is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications. The International Virtual Observatory (IVO) application is an application that takes advantage of IVOA standards and infrastructure to provide some VO service.
166 </p>
167
168 <h2><a id="contents" name="contents">Contents</a></h2>
169 <div class="head">
170 <ul class="toc">
171 <li><a href="#abstract">Abstract</a></li>
172 <li><a href="#status">Status</a></li>
173 <li><a href="#acknowledgments">Acknowledgments</a></li>
174 <li><a href="#contents">Contents</a></li>
175 <li><a href="#sec1">1. Introduction</a></li>
176 <ul class="toc"><li><a href="#sec1_1">1.1 The role in the IVOA Architecture</a></li></ul>
177 <li><a href="#sec2">2. Interface bindings</a></li>
178 <li><a href="#sec3">3. Metadata specification</a></li>
179 <ul class="toc">
180 <li><a href="#sec3_1">2.1 Capability metadata</a></li>
181 <li><a href="#sec3_2">2.2 Non-service metadata (non-normative)</a></li>
182 <li><a href="#sec3_3">2.3 Availability metadata</a></li>
183 <li><a href="#sec3_4">2.4 Table metadata</a></li>
184 </ul>
185 <li><a href="#sec4">4. Registration of VOSI endpoints</a></li>
186 <li><a href="#sec5">5. Example VOSI responses</a></li>
187 <br/>
188 <li><a href="#appA">Appendix A: VOSI XML schemas</a></li>
189 <li><a href="#appB">Appendix B: Changes from previous versions</a></li>
190 <li><a href="#ref">References</a></li>
191 </ul>
192 </div>
193 <hr/>
194
195
196 <br/>
197 <h2><a name="sec1">1. Introduction</a></h2>
198 <p>The web services that comprise much of the Virtual Observatory (VO)
199 come in two forms: SOAP-based (Simple Object Access Protocol, [1])
200 ones such as footprint and spectrum services [2], SkyNodes and Open
201 SkyQuery [3], registry interfaces [4] and CDS access [5]; and RESTful
202 (REpresentational State Transfer, [6]) ones such as TAP [7] and other
203 second generation data access (DAL) services, and VOSpace 2.0
204 [8]. This document describes a set of common basic functions that all
205 these services should provide in the form of a standard support interface
206 in order to support the effective management of the VO.
207 </p>
208 <p>
209 The IVOA Web Services Basic Profile [9] mandates that a compliant
210 SOAP-based web service should have the interface defined in this
211 specification, as expressed using the standard WSDL (Web Services
212 Description Language, [10]) format. For RESTful services, the
213 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. </p>
214
215
216 <h3><a name="sec1_2">1.2 The role in the IVOA Architecture</a></h3>
217 <p>The IVOA Architecture [11] provides a high-level view of how IVOA
218 standards work together to connect users and applications with
219 providers of data and services, as depicted in the diagram in Fig. 1.
220 </p>
221
222 <p>
223 <center>
224 <font size="-1">
225 <img src="vosi-in-arch.png" width="756"/> <br />
226 <blockquote>
227 <strong>Figure 1. VOSI in the IVOA Architecture.</strong>
228 VOSI is the standard that defines the basic functions that all VO
229 services should provide in order to support management of the VO.
230 </blockquote>
231 </font>
232 </center>
233 </p>
234
235 <p>In this architecture, users employ a variety of tools (from the
236 User Layer) to discover and access archives and services--that is,
237 resources--of interest (represented in the Resource Layer). A
238 registry plays a role in discovery by harvesting metadata that
239 describe archives and services and making them searchable from a
240 central service. The VOSI interface provides a means for a service to
241 provide some of this metadata itself; this allows a registry to pull
242 the metadata from the service rather than relying on a human to
243 provide it (e.g. by typing the data into a registration form
244 manually). This mechanism can make it easier to collect highly
245 detailed metadata (e.g. descriptions of columns in a catalog) that
246 might not be practically provided otherwise. As some of this metadata
247 describes the service interface and how it behaves, other applications
248 can use this information for controlling how they use the service.
249 Even when the service is "discovered" through some means other than a
250 registry, an application can still understand how to use the service
251 by querying for this information directly.
252 </p>
253
254 <p>
255 Once a user discovers data and services of interest, she will want to
256 use engage them in an analysis process. Success requires that the selected
257 services are actually up and running properly as a down service can
258 cause auotmated processing to fail completely. Registry and workflow
259 services can assist with this by tracking the availability of
260 services and alerting users about downtime. We envision that VOSI
261 will allow VO projects to better track the overall health of the VO
262 ecosystem.
263 </p>
264
265
266 <h2><a name="sec2">2. Interface bindings</a></h2>
267 <p>The standard interface returns metadata without changing the
268 state of the service with which it is associated. This could, in principle, be
269 implemented in any of three ways:</p>
270 <ol type="1">
271 <li> As extra SOAP operations on an existing SOAP endpoint of the
272 service with which it is associated. This would be a 'SOAP binding' of VOSI.
273 <li> As SOAP operations on a separate SOAP endpoint. This would be an alternate form of the SOAP binding.
274 <li> As web resources with distinct URLs, without using the SOAP protocol. This is the 'REST binding' for the standard interface.
275 </ol><p>
276 This standard requires the REST binding of VOSI even when applied to
277 services that otherwise use SOAP. No details of the SOAP binding are
278 given in this version of the standard. </p>
279 <p>
280 In the REST binding, the support interfaces shall have distinct URLs
281 in the HTTP scheme and shall be accessible by the GET operation in the
282 HTTP protocol. The response to an HTTP POST, PUT or DELETE to these
283 resources is not defined by this specification. However, if an
284 implementation has no special action to perform for these requests,
285 the normal response would be a HTTP 405 "Method not allowed" status code. </p><p>
286 The endpoints and interface types for the support interface shall be
287 defined in the service's registration using one <i>Capability</i> element for
288 each interface. The values of the <i>standardID</i> attribute for these <i>Capability</i>s are given in section 4.</p><p>
289 When using the REST binding, any HTTP URLs may be used. The client
290 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.</p>
291 </p>
292
293
294 <h2><a name="sec3">3. Metadata specification</a></h2>
295 <p>
296 There are various classes of metadata that might be returned by a
297 service through its standard interface:</p>
298 <ul>
299 <li> those describing its functional capabilities
300 <li> those describing its operational behaviour - availability,
301 reliability, etc.
302 <li> those describing tabular data handled by the service
303 <li> those describing other aspects of the service
304 </ul>
305 <p>This section defines how each of these classes is represented. The
306 following typographic convention is used to represent a XML element defined
307 within a particular namespace:</p>
308 <pre>
309 {http://some.name.space}elementName
310 </pre>
311 <p>For example,
312 <i>{http://www.ivoa.net/xml/VOResource/v1.0}resource</i> indicates a
313 XML element named <i>resource</i> that is described in the XML schema
314 associated with the 'http://www.ivoa.net/xml/VOResource/v1.0'
315 namespace - in this case, this would be VOResource.xsd [12].
316 </p>
317
318 <h3><a name="sec3_1">3.1 Capability metadata</a></h3>
319
320 <p></p
321 <blockquote>
322 <table bgcolor="#dddddd" border="2" cellpadding="5"><tbody><tr><td>
323 <dl style="margin-top: 0pt; margin-bottom: 0pt">
324 <dt> <strong>Note:</strong> </dt>
325 <dd>'Capability' is unfortunately an overloaded term in the VO
326 referring to both a functional aspect of a service
327 and also particular pieces of metadata defined by various XML
328 schema. When referring to an XML element called 'capability', it
329 shall be be put in italics. Its parent namespace may also be
330 included (using the syntax described above) if it is ambiguous
331 which XML schema is being referred to.
332 </dd>
333 </dl>
334 </td></tr></tbody></table>
335 </blockquote>
336 <p></p>
337
338 <p>This interface provides the service metadata in the form of a list
339 of <i>Capability</i> descriptions. Each of these descriptions is an XML element that: </p>
340 <ul>
341 <li> states that the service provides a particular, IVOA-standard function;
342 <li> lists the interfaces for invoking that function;
343 <li> records any details of the implementation of the function that
344 are not defined as default or constant in the standard for that function.
345 </ul>
346 <p>
347 For example, one capability might describe a cone search function and
348 another the TAP implementation but these two might well apply to the same service.</p><p>
349 An entry for a service in the resource registry - i.e., its VOResource
350 - contains the Dublin Core resource metadata (identifier, curation
351 information, content description, etc.) followed by the service's
352 capability descriptions (expressed as a series of
353 <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i> 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:</p>
354 <ul><li>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.
355 <li>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.
356 </ul></p>
357
358 <p>
359 The service metadata shall be represented as an XML document with the
360 root element
361 <i>{http://www.ivoa.net/xml/VOSICapabilities/v1.0}capabilities</i>.
362 (See <a href="#appA1">Appendix A.1</a> for the definition of the
363 VOSICapabilities XML schema.) This element must contain one or more child
364 <i>capability</i> elements that describe the capabilities of the
365 service. Given that the <i>capability</i> element is defined to be of type
366 <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i>, a <i>capability</i>
367 element may be represented by a legal sub-type of
368 <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i>, in which
369 case, the <i>capability</i> element must use an <i>xsi:type</i>
370 attribute to identify the sub-type (see section 2.2.1 of
371 [<a href="#ref:vor">1</a>]).
372 </p>
373
374 <p></p
375 <blockquote>
376 <table bgcolor="#dddddd" border="2" cellpadding="5"><tbody><tr><td>
377 <dl style="margin-top: 0pt; margin-bottom: 0pt">
378 <dt> <strong>Note:</strong> </dt>
379 <dd> The value of the <i>capability</i> element's standardID attribute is used
380 to indicate the service's support for particular standard protocols
381 (such as Simple Image Access, Simple Cone Search, etc.). In the
382 case of some protocols, the support for the standard is further
383 characterized by additional metadata provided by a standard XML
384 schema extension of <i>Capability</i> for that protocol. The extension metadata is enabled by
385 adding a <i>xsi:type</i> attribute to the <i>capability</i> element set to the
386 <i>Capability</i> sub-type value defined in the extension schema for that protocol (see example below). </dd>
387 </dl>
388 </td></tr></tbody></table>
389 </blockquote>
390 <p></p>
391
392 <p>
393 The VOResource list of capabilities should include capabilities describing VOSI
394 endpoints as specified in section 4.
395 </p>
396
397
398 <p>
399 In the REST binding, the service metadata shall be a single web
400 resource with a registered URL. The date and time at which the
401 metadata last changed shall be obtained from the <i>Last-Modified</i>
402 HTTP Header keyword sent in the response to a GET or HEAD request to the registered URI.</p><p>
403 All VO services should provide this interface.
404 </p>
405
406 <h3><a name="sec3_2">3.2 Non-service metadata (non-normative)</a></h3>
407 <p>There may be other metadata associated with a service than the capability metadata described above.
408 <ul><li> Every service has the Dublin Core resource metadata [13].
409 <li> Some services are associated with registered applications.
410 <li> Some services are associated with registered data collections.
411 </ul></p><p>None of these are explicitly provided for in this version of VOSI. Some might be covered in later versions of VOSI.
412 </p>
413
414 <h3><a name="sec3_3">3.3 Availability metadata</a></h3>
415 <p>This interface indicates whether the service is operable and the reliability of the service for extended and scheduled requests.
416 The availability shall be represented as an XML document in which the
417 root element is <i>{http://www.ivoa.net/xml/Availability/v1.0}availability</i>. This element
418 shall contain child elements providing the following information.</p>
419 <ul>
420 <li> <i>available</i> - whether the service is currently accepting requests
421 <li> <i>upSince</i> - duration for which the service has been continuously available
422 <li> <i>downAt</i> - the instant at which the service is next scheduled to be unavailable
423 <li> <i>backAt</i> - the instant at which the service is scheduled to become available again after down time;
424 <li> <i>note</i> - textual note, e.g. explaining the reason for unavailaility.
425 </ul><p>
426 The elements <i>upSince</i>, <i>downAt</i>, <i>backAt</i> and <i>note</i> are optional. The <i>available</i> element is mandatory. There may be more than one <i>note</i> element.</p><p>
427 The XML document shall conform to the schema given in appendix A.2 of this specification.</p><p>
428 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 <i>available</i> to false in the availability output.</p><p>
429 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 <i>available</i> to false.</p><p>
430 There are no special elements in the availability document for the
431 contact details of the service operator. These details may be given as
432 a <i>note</i> element if they are known to the service.</p>
433 <p>
434 In the REST binding, the availability shall be a single web resource with a registered URL</p><p>
435 All VO services shall provide this interface.
436 </p>
437
438 <h3><a name="sec3_4">3.4 Table metadata</a></h3>
439 <p>
440 Some services deal with tabular data. These data may be the target of
441 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.</p><p>
442 The <i>VODataService</i> standard [<a href="#ref:14">14</a>] defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.</p><p>
443 A service which uses tables in its interface should define a VOSI
444 endpoint from which table metadata can be read. The table metadata
445 shall be represented as an XML document of which the root element is
446 of type
447 <i>{http://www.ivoa.net/xml/VODataService/v1.1}TableSet</i>. This
448 element may contain any mix of elements allowed by the VODataService
449 XML schema.</p><p>
450 In the REST binding, the table metadata shall be a single web resource with a registered URL.
451 </p>
452
453 <h2><a name="sec4">4. Registration of VOSI endpoints</a></h2>
454 <p>
455 The endpoints for the service and availability metadata shall be
456 included in the registration of each service that provides them.
457 </p>
458 <center>
459 <table>
460 <tr><th align="left">Endpoint type</th><th align="left">standardID value</th></tr>
461 <tr><td>availability</td><td>ivo://ivoa.net/std/VOSI#availability</td></tr>
462 <tr><td>capabilties</td><td>ivo://ivoa.net/std/VOSI#capabilities</td></tr>
463 <tr><td>tables</td><td>ivo://ivoa.net/std/VOSI#tables</td></tr>
464 </table>
465 </center>
466 <p>
467 An availability endpoint shall be represented by an element named
468 <i>capability</i>, of type
469 <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i> (defined by
470 the standard VOResource XML schema [<a href="ref:12">12</a>]). The
471 value of the <i>standardID</i> attribute of the <i>capability</i>
472 shall be <i>ivo://ivoa.net/std/VOSI#availability</i>.
473 </p>
474
475 <p>
476 A capabilities endpoint should be represented by an element named
477 <i>capability</i>, of type
478 <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i>. If such
479 a <i>capability</i> is provided then the value of the <i>standardID</i> attribute must be <i>ivo://ivoa.net/std/VOSI#capabilities.</i></p><p>
480 A tables endpoint should be represented by an element named
481 <i>capability</i>, of type
482 <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i>. If such
483 a <i>capability</i> is provided then the value of the <i>standardID</i> attribute must be <i>ivo://ivoa.net/std/VOSI#tables</i>.
484 </p>
485
486 <p>
487 With all three VOSI functions, the capability element that describes
488 the function must contain an interface element of a type semantically
489 appropriate for the binding of the function to the service; the
490 <i>accessURL</i> element within the interface element indicates the
491 endpoint for the VOSI function. For the REST binding, this
492 <i>accessURL</i> element must set the <i>use</i> attribute to "full".
493 Furthermore, for the REST binding, this document recommends using the
494 <i>{http://www.ivoa.net/xml/VODataService/v1.1}ParamHTTP</i> interface
495 type to encode VOSI endpoints (see example given in section 2.1).
496 </p>
497
498
499 <h2><a name="sec5">5. Example VOSI responses</a></h2>
500
501 <!-- Space to push page break in PDF version
502 <br />
503 <br />
504 -->
505
506 <div class="exampleOuter">
507 <a name="ex:caps">
508 </a><div class="exampleHeader">Example 1:</div>
509 <div class="exampleWrapper">A sample response from a capabilities
510 resource describing an SIA service. </div>
511 <div class="exampleInner" style="background-color: rgb(213, 222, 227);">
512 <pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
513 &lt;vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
514 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
515 xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0"
516 xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0"
517 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
518 xsi:schemaLocation="http://www.ivoa.net/xml/VOSI/v1.0
519 http://www.ivoa.net/xml/VOSI/v1.0
520 http://www.ivoa.net/xml/VOResource/v1.0
521 http://www.ivoa.net/xml/VOResource/v1.0
522 http://www.ivoa.net/xml/VODataService/v1.0
523 http://www.ivoa.net/xml/VODataService/v1.0
524 http://www.ivoa.net/xml/SIA/v1.0
525 http://www.ivoa.net/xml/SIA/v1.0"&gt;
526
527 &lt;!-- a generic capability (for custom, non-standard interfaces) --&gt;
528 &lt;capability&gt;
529 &lt;interface xsi:type="vr:WebBrowser"&gt;
530 &lt;accessURL use="full"&gt; http://adil.ncsa.uiuc.edu/siaform.html &lt;/accessURL&gt;
531 &lt;/interface&gt;
532 &lt;/capability&gt;
533
534 &lt;!-- the SIA capability --&gt;
535 &lt;capability xsi:type="sia:SimpleImageAccess" standardID="ivo://ivoa.net/std/SIA"&gt;
536 &lt;interface xsi:type="vs:ParamHTTP" role="std"&gt;
537 &lt;accessURL&gt; http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f&amp;amp; &lt;/accessURL&gt;
538 &lt;/interface&gt;
539
540 &lt;imageServiceType&gt;Pointed&lt;/imageServiceType&gt;
541 &lt;maxQueryRegionSize&gt;
542 &lt;long&gt;360.0&lt;/long&gt;
543 &lt;lat&gt;180.0&lt;/lat&gt;
544 &lt;/maxQueryRegionSize&gt;
545 &lt;maxImageExtent&gt;
546 &lt;long&gt;360.0&lt;/long&gt;
547 &lt;lat&gt;180.0&lt;/lat&gt;
548 &lt;/maxImageExtent&gt;
549 &lt;maxImageSize&gt;
550 &lt;long&gt;5000&lt;/long&gt;
551 &lt;lat&gt;5000&lt;/lat&gt;
552 &lt;/maxImageSize&gt;
553 &lt;maxFileSize&gt;100000000&lt;/maxFileSize&gt;
554 &lt;maxRecords&gt;5000&lt;/maxRecords&gt;
555 &lt;/capability&gt;
556
557 &lt;!-- the interface that returns this document --&gt;
558 &lt;capability standardID="ivo://ivoa.net/std/VOSI#capabilities"&gt;
559 &lt;interface xsi:type="vs:ParamHTTP" role="std"&gt;
560 &lt;accessURL use="full"&gt; http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/capabilities &lt;/accessURL&gt;
561 &lt;/interface&gt;
562 &lt;/capability&gt;
563
564 &lt;!-- the interface that returns this document --&gt;
565 &lt;capability standardID="ivo://ivoa.net/std/VOSI#availability"&gt;
566 &lt;interface xsi:type="vs:ParamHTTP" role="std"&gt;
567 &lt;accessURL use="full"&gt; http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/availability &lt;/accessURL&gt;
568 &lt;/interface&gt;
569 &lt;/capability&gt;
570 &lt;/vosi:capabilities&gt;
571 </pre>
572 </div></div>
573 <br/>
574 <div class="exampleOuter">
575 <a name="ex:caps">
576 </a><div class="exampleHeader">Example 2:</div>
577 <div class="exampleWrapper">A sample response from a tables
578 resource describing a TAP service. </div>
579 <div class="exampleInner" style="background-color: rgb(213, 222, 227);">
580 <pre>
581 &lt;?xml version="1.0" encoding="UTF-8"?>
582 &lt;vosi:tableset
583 xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
584 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
585 xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">
586 &lt;schema>
587 &lt;name>cfht &lt;/name>
588 &lt;table type="output">
589 &lt;name>cfht.deepU &lt;/name>
590 &lt;column>
591 &lt;name>cfhtlsID &lt;/name>
592 &lt;dataType xsi:type="vod:TAP" size="30">adql:VARCHAR &lt;/dataType>
593 &lt;/column>
594 &lt;column>
595 &lt;name>survey &lt;/name>
596 &lt;dataType xsi:type="vod:TAP" size="6">adql:VARCHAR &lt;/dataType>
597 &lt;/column>
598 &lt;column>
599 &lt;name>field &lt;/name>
600 &lt;dataType xsi:type="vod:TAP" size="2">adql:VARCHAR &lt;/dataType>
601 &lt;/column>
602 &lt;column>
603 &lt;name>pointing &lt;/name>
604 &lt;dataType xsi:type="vod:TAP" size="6">adql:VARCHAR &lt;/dataType>
605 &lt;/column>
606 &lt;column>
607 &lt;name>selectionFilter &lt;/name>
608 &lt;dataType xsi:type="vod:TAP" size="2">adql:VARCHAR &lt;/dataType>
609 &lt;/column>
610 &lt;/table>
611 &lt;table type="output">
612 &lt;name>TAP_SCHEMA.keys &lt;/name>
613 &lt;column>
614 &lt;name>key_id &lt;/name>
615 &lt;description>unique key to join to TAP_SCHEMA.key_columns &lt;/description>
616 &lt;dataType xsi:type="vod:TAP" size="64">adql:VARCHAR &lt;/dataType>
617 &lt;/column>
618 &lt;column>
619 &lt;name>from_table &lt;/name>
620 &lt;description>the table with the foreign key &lt;/description>
621 &lt;dataType xsi:type="vod:TAP" size="64">adql:VARCHAR &lt;/dataType>
622 &lt;/column>
623 &lt;column>
624 &lt;name>target_table &lt;/name>
625 &lt;description>the table with the primary key &lt;/description>
626 &lt;dataType xsi:type="vod:TAP" size="64">adql:VARCHAR &lt;/dataType>
627 &lt;/column>
628 &lt;/table>
629 &lt;/schema>
630 &lt;/vosi:tableset>
631 </pre>
632 </div></div>
633
634
635 <br/>
636 <h2><a name="appA">Appendix A: VOSI XML schemas</a></h2>
637
638 <a name="appA1">
639 <h3>A.1. The Complete VOSICapabilities Schema</h3></a>
640
641 <pre>&lt;xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
642 xmlns:tns="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
643 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
644 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
645 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
646 elementFormDefault="qualified"
647 attributeFormDefault="unqualified"
648 version="1.0rc1"&gt;
649
650 &lt;xsd:annotation&gt;
651 &lt;xsd:documentation&gt;
652 A schema for formatting service capabilities as returned by a
653 capabilities resource, defined by the IVOA Support Interfaces
654 specification (VOSI).
655 See http://www.ivoa.net/Documents/latest/VOSI.html.
656 &lt;/xsd:documentation&gt;
657 &lt;/xsd:annotation&gt;
658
659 &lt;xsd:import namespace="http://www.ivoa.net/xml/VOResource/v1.0"
660 schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0" /&gt;
661
662 &lt;!--
663 - the root element for a VOSI capabilities metadata (section 3.1)
664 --&gt;
665 &lt;xsd:element name="capabilities"&gt;
666 &lt;xsd:annotation&gt;
667 &lt;xsd:documentation&gt;
668 A listing of capabilities supported by a service
669 &lt;/xsd:documentation&gt;
670 &lt;/xsd:annotation&gt;
671
672 &lt;xsd:complexType&gt;
673 &lt;xsd:sequence&gt;
674
675 &lt;xsd:element name="capability" type="vr:Capability"
676 form="unqualified" minOccurs="0" maxOccurs="unbounded"&gt;
677 &lt;xsd:annotation&gt;
678 &lt;xsd:documentation&gt;
679 A capability supported by the service.
680 &lt;/xsd:documentation&gt;
681 &lt;xsd:documentation&gt;
682 A protocol-specific capability is included by specifying a
683 vr:Capability sub-type via an xsi:type attribute on this
684 element.
685 &lt;/xsd:documentation&gt;
686 &lt;/xsd:annotation&gt;
687 &lt;/xsd:element&gt;
688
689 &lt;/xsd:sequence&gt;
690 &lt;/xsd:complexType&gt;
691 &lt;/xsd:element&gt;
692
693 &lt;/xsd:schema&gt;
694 </pre>
695
696 <a name="appA2">
697 <h3>A.2. The Complete VOSIAvailability Schema</h3></a>
698
699 <pre>&lt;xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
700 xmlns:tns="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
701 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
702 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
703 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
704 elementFormDefault="qualified"
705 attributeFormDefault="unqualified"
706 version="1.0rc1"&gt;
707
708 &lt;xsd:annotation&gt;
709 &lt;xsd:documentation&gt;
710 A schema for formatting availability metadata as returned by an
711 availability resource defined in the IVOA Support Interfaces
712 specification (VOSI).
713 See http://www.ivoa.net/Documents/latest/VOSI.html.
714 &lt;/xsd:documentation&gt;
715 &lt;/xsd:annotation&gt;
716
717 &lt;!--
718 - the root element for a VOSI availability (section 3.3)
719 --&gt;
720 &lt;xsd:element name="availability" type="tns:Availability"/&gt;
721
722 &lt;xsd:complexType name="Availability"&gt;
723 &lt;xsd:sequence&gt;
724
725 &lt;xsd:element name="available" type="xsd:boolean"&gt;
726 &lt;xsd:annotation&gt;
727 &lt;xsd:documentation&gt;
728 Indicates whether the service is currently available.
729 &lt;/xsd:documentation&gt;
730 &lt;/xsd:annotation&gt;
731 &lt;/xsd:element&gt;
732
733 &lt;xsd:element name="upSince" type="xsd:dateTime" minOccurs="0"&gt;
734 &lt;xsd:annotation&gt;
735 &lt;xsd:documentation&gt;
736 The instant at which the service last became available.
737 &lt;/xsd:documentation&gt;
738 &lt;/xsd:annotation&gt;
739 &lt;/xsd:element&gt;
740
741 &lt;xsd:element name="downAt" type="xsd:dateTime" minOccurs="0"&gt;
742 &lt;xsd:annotation&gt;
743 &lt;xsd:documentation&gt;
744 The instant at which the service is next scheduled to become
745 unavailable.
746 &lt;/xsd:documentation&gt;
747 &lt;/xsd:annotation&gt;
748 &lt;/xsd:element&gt;
749
750 &lt;xsd:element name="backAt" type="xsd:dateTime" minOccurs="0"&gt;
751 &lt;xsd:annotation&gt;
752 &lt;xsd:documentation&gt;
753 The instant at which the service is scheduled to become available
754 again after a period of unavailability.
755 &lt;/xsd:documentation&gt;
756 &lt;/xsd:annotation&gt;
757 &lt;/xsd:element&gt;
758
759 &lt;xsd:element name="note" type="xsd:string"
760 minOccurs="0" maxOccurs="unbounded"&gt;
761 &lt;xsd:annotation&gt;
762 &lt;xsd:documentation&gt;
763 A textual note concerning availability.
764 &lt;/xsd:documentation&gt;
765 &lt;/xsd:annotation&gt;
766 &lt;/xsd:element&gt;
767
768 &lt;/xsd:sequence&gt;
769 &lt;/xsd:complexType&gt;
770
771 &lt;/xsd:schema&gt;
772 </pre>
773
774 <a name="appA3">
775 <h3>A.3. The Complete VOSITables Schema</h3></a>
776 <pre>
777 &lt;xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
778 xmlns:tns="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
779 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
780 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
781 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
782 elementFormDefault="qualified"
783 attributeFormDefault="unqualified"
784 version="1.0">
785
786 &lt;xsd:annotation>
787 &lt; xsd:documentation>
788 A schema for formatting table metadata as returned by a
789 tables resource, defined by the IVOA Support Interfaces
790 specification (VOSI).
791 See http://www.ivoa.net/Documents/latest/VOSI.html.
792 &lt;/xsd:documentation>
793 &lt;/xsd:annotation>
794
795 &lt;xsd:import namespace="http://www.ivoa.net/xml/VODataService/v1.1"
796 schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1" />
797
798 &lt;!--
799 - the root element for a VOSI table metadata (section 3.4)
800 -->
801 &lt;xsd:element name="tableset" type="vs:TableSet" >
802 &lt;xsd:annotation>
803 &lt;xsd:documentation>
804 A description of the table metadata supported by the
805 service associated with a VOSI-enabled resource.
806 &lt;/xsd:documentation>
807 &lt;/xsd:annotation>
808 &lt;/xsd:element>
809
810 &lt;/xsd:schema>
811 </pre>
812 <br/>
813 <h2><a name="appB">Applendix B: Changes from previous versions</a></h2>
814
815 <h4>Changes since PR-20100311</h4>
816 <ul>
817 <li>Inclusion of IVOA Architecture text </li>
818 <li>Restructuring and clarification in response to RFC comments</li>
819 <li>Inclusion of VOSITables schema in appendix</li>
820 <li>Second example added for a TAP service response</li>
821 </ul>
822
823 <h4>Changes since WD-20090825</h4>
824
825 <ul>
826 <li> Mandate the use of VOSICapabilities to return capabilities </li>
827 <li> S2.1: added non-normative note about capability sub-types; added
828 example capabilities metadata </li>
829 <li> Recommend the inclusion of VOSI interfaces in capability metadata</li>
830 <li> S2.5: When returning capabilities metadata, require VOSI (REST)
831 accessURLs to have use="full"; recommend this use of ParamHTTP. </li>
832 <li> Rename Availability schema to VOSIAvailability; added
833 VOSICapabilities schema. </li>
834 </ul>
835
836 <h4>Changes since WD-20081030</h4>
837
838 <p>The REST binding is made mandatory for all kinds of service. Details of the SOAP binding, including its WSDL contract, are removed.</p><p>
839 The definition of the root element for the table-metadata document is corrected. Instead of requiring the <i>tableset</i> element from <i>VODataService 1.1</i> (which element does not exist in that schema), the text now requires an element of type <i>TableSet</i>.
840 </p>
841
842 <br/>
843 <h2><a name="ref">References</a></h2>
844
845 <dl>
846
847
848 <dt> <a name="ref:0">[0]</a> </dt>
849 <dd> <cite>
850 <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a></cite>,
851 <code>http://www.ietf.org/rfc/rfc2119.txt</code>
852 </dd>
853
854
855 <dt> <a name="ref:1">[1]</a> </dt>
856 <dd> <cite>
857 <a href="http://www.w3.org/TR/soap">Simple Object Access
858 Protocol (SOAP)</a></cite>,
859 <code>http://www.w3.org/TR/soap</code>
860 </dd>
861
862
863 <dt> <a name="ref:2">[2]</a> </dt>
864 <dd> <cite>
865 <a href="http://voservices.net">Footprint and spectrum services</a></cite>,
866 <code>http://voservices.net</code>
867 </dd>
868
869 <dt> <a name="ref:3">[3]</a> </dt>
870 <dd> <cite>
871 <a href="http://openskyquery.net">Skynodes and Open SkyQuery</a></cite>,
872 <code>http://openskyquery.net</code>
873 </dd>
874
875 <dt> <a name="ref:4">[4]</a></dt><dd>Benson, K., Plante, R., Auden, E.,
876 Graham, M., Greene, G., Hill, M., Linde, T., Morris, D., O'Mullane,
877 W., Rixon, G., St&eacute;b&eacute;, A., Andrews, K., 2009, <cite>
878 <a href="http://www.ivoa.net/Documents/RegistryInterface">IVOA
879 Registry Interfaces</a></cite>, v1.0, IVOA Recommendation,
880 <code>http://www.ivoa.net/Documents/RegistryInterface</code>
881 </dd>
882
883 <dt> <a name="ref:5">[5]</a> </dt>
884 <dd> <cite>
885 <a href="http://cdsweb.u-strasbg.fr/cdsws.gml">CDS web services</a></cite>,
886 <code>http://cdsweb.u-strasbg.fr/cdsws.gml</code>
887 </dd>
888
889 <dt> <a name="ref:6">[6]</a> </dt>
890 <dd> <cite>
891 <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REpresentational State Transfer (REST)</a></cite>,
892 <code>http://en.wikipedia.org/wiki/Representational_State_Transfer</code>
893 </dd>
894
895 <dt> <a name="ref:7">[7]</a> </dt>
896 <dd> Dowler, P., Rixon, G., Tody, D., 2010, <cite>
897 <a
898 href="http://www.ivoa.net/Documents/TAP/20100327/REC-TAP-1.0.html">Table
899 Access Protocol</a></cite>, v1.0, IVOA Recommmendation,
900 <code>http://www.ivoa.net/Documents/TAP/20100327/REC-TAP-1.0.html</code>
901 </dd>
902
903 <dt> <a name="ref:8">[8]</a> </dt>
904 <dd> Graham, M., Morris, D., Rixon, G., Dowler, P., Schaaff, A.,
905 Tody, D., 2010, <cite>
906 <a
907 href="http://www.ivoa.net/Documents/VOSpace/20101112/WD-VOSpace-2.0-20101112.html">VOSpace
908 specification</a></cite>, v2.00, IVOA Working Draft,
909 <code>http://www.ivoa.net/Documents/VOSpace/20101112/WD-VOSpace-2.0-20101112.html</code>
910 </dd>
911
912 <dt> <a name="ref:9">[9]</a> </dt>
913 <dd> Grid and Web Services Working Group, 2010, <cite>
914 <a
915 href="http://www.ivoa.net/Documents/VOSI/20100311/PR-VOSI-1.0-20100311.html">IVOA
916 Support Interfaces</a></cite>, v1.00, IVOA Proposed Recommendation,
917 <code>http://www.ivoa.net/Documents/VOSI/20100311/PR-VOSI-1.0-20100311.html</code>
918 </dd>
919
920 <dt> <a name="ref:10">[10]</a> </dt>
921 <dd> <cite>
922 <a href="http://www.w3.org/TR/WSDL">Web Services Description Language</a></cite>,
923 <code>http://www.w3.org/TR/WSDL</code>
924 </dd>
925
926 <dt> <a name="ref:11">[11]</a> </dt>
927 <dd> Arviset, C., Gaudet, S., IVOA Technical Coordination Group,
928 2010, <cite>
929 <a
930 href="http://www.ivoa.net/Documents/Notes/IVOAArchitecture/20101123/IVOAArchitecture-1.0-20101123.pdf">IVOA
931 Architecture</a></cite>, v1.0, IVOA Note,
932 <code>http://www.ivoa.net/Documents/Notes/IVOAArchitecture/20101123/IVOAArchitecture-1.0-20101123.pdf</code>
933 </dd>
934
935 <dt> <a name="ref:12">[12]</a> </dt>
936 <dd> Plante, R., Benson, K., Graham, M., Greene,
937 G., Harrison, P., Lemson, G., Linde, T., Rixon,
938 G., St&eacute;b&eacute;, A., 2008, <cite>
939 <a href="http://www.ivoa.net/Documents/cover/VOResource-20080222.html">
940 VOResource: an XML Encoding Schema for Resource Metadata</a></cite>,
941 v1.03, IVOA Recommendation,
942 <code>http://www.ivoa.net/Documents/cover/VOResource-20080222.html</code>
943 </dd>
944
945 <dt> <a name="ref:13">[13]</a> </dt>
946 <dd> Hanisch, R., IVOA Registry Working Group, NVO Metadata Working
947 Group, 2007, <cite>
948 <a
949 href="http://www.ivoa.net/Documents/REC/ResMetadata/RM-20070302.html">Resource
950 Metadata for the Virtual Observatory</a></cite>, v.1.12, IVOA Recommendation
951 <code>http://www.ivoa.net/Documents/REC/ResMetadata/RM-20070302.html</code>
952 </dd>
953
954 <dt> <a name="ref:14">[14]</a> </dt>
955 <dd>Plante, R., St&eacute;b&eacute;, A., Benson, K., Dowler, P., Graham, M., Greene,
956 G., Harrison, P., Lemson, G., Linde, T., Rixon,
957 G., IVOA Registry Working Group, 2010, <cite>
958 <a href="http://www.ivoa.net/Documents/VODataService/20100916/PR-VODataService-1.1-20100916.html">VODataService: a VOResource Schema Extension
959 for Describing Collections and Services</a></cite>, v1.1, IVOA
960 Proposed Recommendation,
961 <code>http://www.ivoa.net/Documents/VODataService/20100916/PR-VODataService-1.1-20100916.html</code>
962 </dd>
963
964 </dl>
965
966
967
968 </body></html>

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