ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

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

ViewVC Help
Powered by ViewVC 1.1.26