ViewVC logotype

Annotation of /trunk/projects/grid/VOSI/VOSI-v1.0pr.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1457 - (hide annotations)
Tue May 10 20:24:45 2011 UTC (10 years, 4 months ago) by rplante@ncsa.uiuc.edu
File MIME type: text/html
File size: 41197 byte(s)
Undoing change committed in r1456
1 rplante@ncsa.uiuc.edu 1457 <?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 }
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}
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>
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-20101213</h1>
59     <h2>IVOA WG Proposed Recommendation 2010 December 13 </h2>
61     <dl>
62     <dt>This version:</dt>
63     <dd><a href="http://www.ivoa.net/Documents/VOSI/20101213/">
64     http://www.ivoa.net/Documents/VOSI/20101213/</a></dd>
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>
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>
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>
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>
101     <h2><a name="abstract" id="abstract">Abstract</a></h2>
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>
107     <div class="status">
108     <h2><a name="status" id="status">Status of this Document</a></h2>
110     <!-- Choose one of the following (and remove the rest)-->
111     <!--Note-->
112 rplante@ncsa.uiuc.edu 1376 <!--
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 rplante@ncsa.uiuc.edu 1457 It is inappropriate to use IVOA Working Drafts as reference materials -->
119 rplante@ncsa.uiuc.edu 1376 <!--or to cite them as other than "work in progress.</p>
120 rplante@ncsa.uiuc.edu 1457 -->
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 rplante@ncsa.uiuc.edu 1376 <!--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 rplante@ncsa.uiuc.edu 1457 -->
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/.
136     </div><br />
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>
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>
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 [RFC 2119].</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>
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. Interfaces bindings</a></li>
178     <li><a href="#sec3">3. Metadata specification</a>
179     <ul class="toc">
180     <li><a href="#sec3_1">3.1 Capability metadata</a></li>
181     <li><a href="#sec3_2">3.2 Non-service metadata (non-normative)</a></li>
182     <li><a href="#sec3_3">3.3 Availability metadata</a></li>
183     <li><a href="#sec3_4">3.4 Table metadata</a></li>
184     </ul></li>
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/>
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>
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>
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>
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 aake 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>
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>
265     <h2><a name="sec2">2. Interface bindings</a></h2>
266     <p>The standard interface returns metadata without changing the
267     state of the service with which it is associated. This could, in principle, be
268     implemented in any of three ways:</p>
269     <ol type="1">
270     <li> As extra SOAP operations on an existing SOAP endpoint of the
271     service with which it is associated. This would be a 'SOAP binding' of VOSI.
272     <li> As SOAP operations on a separate SOAP endpoint. This would be an alternate form of the SOAP binding.
273     <li> As web resources with distinct URLs, without using the SOAP protocol. This is the 'REST binding' for the standard interface.
274     </ol><p>
275     This standard requires the REST binding of VOSI even when applied to
276     services that otherwise use SOAP. No details of the SOAP binding are
277     given in this version of the standard. </p>
278     <p>
279     In the REST binding, the support interfaces shall have distinct URLs
280     in the HTTP scheme and shall be accessible by the GET operation in the
281     HTTP protocol. The response to an HTTP POST, PUT or DELETE to these
282     resources is not defined by this specification. However, if an
283     implementation has no special action to perform for these requests,
284     the normal response would be a HTTP 405 "Method not allowed" status code. </p><p>
285     The endpoints and interface types for the support interface shall be
286     defined in the service's registration using one <i>Capability</i> element for
287     each interface. The values of the <i>standardID</i> attribute for these <i>Capability</i>s are given in section 4.</p><p>
288     When using the REST binding, any HTTP URLs may be used. The client
289     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>
290     </p>
293     <h2><a name="sec3">3. Metadata specification</a></h2>
294     <p>
295     There are various classes of metadata that might be returned by a
296     service through its standard interface:</p>
297     <ul>
298     <li> those describing its functional capabilities
299     <li> those describing its operational behaviour - availability,
300     reliability, etc.
301     <li> those describing tabular data handled by the service
302     <li> those describing other aspects of the service
303     </ul>
304     <p>This section defines how each of these classes is represented. The
305     following typographic convention is used to represent a XML element defined
306     within a particular namespace:</p>
307     <pre>
308     {http://some.name.space}elementName
309     </pre>
310     <p>For example,
311     <i>{http://www.ivoa.net/xml/VOResource/v1.0}resource</i> indicates a
312     XML element named <i>resource</i> that is described in the XML schema
313     associated with the 'http://www.ivoa.net/xml/VOResource/v1.0'
314     namespace - in this case, this would be VOResource.xsd [12].
315     </p>
317     <h3><a name="sec3_1">3.1 Capability metadata</a></h3>
319     <p></p
320     <blockquote>
321     <table bgcolor="#dddddd" border="2" cellpadding="5"><tbody><tr><td>
322     <dl style="margin-top: 0pt; margin-bottom: 0pt">
323     <dt> <strong>Note:</strong> </dt>
324     <dd>'Capability' is unfortunately an overloaded term in the VO
325     referring to both a functional aspect of a service
326     and also particular pieces of metadata defined by various XML
327     schema. When referring to an XML element called 'capability', it
328     shall be be put in italics. Its parent namespace may also be
329     included (using the syntax described above) if it is ambiguous
330     which XML schema is being referred to.
331     </dd>
332     </dl>
333     </td></tr></tbody></table>
334     </blockquote>
335     <p></p>
337     <p>This interface provides the service metadata in the form of a list
338     of <i>Capability</i> descriptions. Each of these descriptions is an XML element that: </p>
339     <ul>
340     <li> states that the service provides a particular, IVOA-standard function;
341     <li> lists the interfaces for invoking that function;
342     <li> records any details of the implementation of the function that
343     are not defined as default or constant in the standard for that function.
344     </ul>
345     <p>
346     For example, one capability might describe a cone search function and
347     another the TAP implementation but these two might well apply to the same service.</p><p>
348     An entry for a service in the resource registry - i.e., its VOResource
349     - contains the Dublin Core resource metadata (identifier, curation
350     information, content description, etc.) followed by the service's
351     capability descriptions (expressed as a series of
352     <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>
353     <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.
354     <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.
355     </ul></p>
357     <p>
358     The service metadata shall be represented as an XML document with the
359     root element
360     <i>{http://www.ivoa.net/xml/VOSICapabilities/v1.0}capabilities</i>.
361     (See <a href="#appA1">Appendix A.1</a> for the definition of the
362     VOSICapabilities XML schema.) This element must contain one or more child
363     <i>capability</i> elements that describe the capabilities of the
364     service. Given that the <i>capability</i> element is defined to be of type
365     <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i>, a <i>capability</i>
366     element may be represented by a legal sub-type of
367     <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i>, in which
368     case, the <i>capability</i> element must use an <i>xsi:type</i>
369     attribute to identify the sub-type (see section 2.2.1 of
370     [<a href="#ref:vor">1</a>]).
371     </p>
373     <p></p
374     <blockquote>
375     <table bgcolor="#dddddd" border="2" cellpadding="5"><tbody><tr><td>
376     <dl style="margin-top: 0pt; margin-bottom: 0pt">
377     <dt> <strong>Note:</strong> </dt>
378     <dd> The value of the <i>capability</i> element's standardID attribute is used
379     to indicate the service's support for particular standard protocols
380     (such as Simple Image Access, Simple Cone Search, etc.). In the
381     case of some protocols, the support for the standard is further
382     characterized by additional metadata provided by a standard XML
383     schema extension of <i>Capability</i> for that protocol. The extension metadata is enabled by
384     adding a <i>xsi:type</i> attribute to the <i>capability</i> element set to the
385     <i>Capability</i> sub-type value defined in the extension schema for that protocol (see the examples in <a href="#sec5">section 5</a> below). </dd>
386     </dl>
387     </td></tr></tbody></table>
388     </blockquote>
389     <p></p>
391     <p>
392     The VOResource list of capabilities should include capabilities describing VOSI
393     endpoints as specified in <a href="#sec4">section 4</a>.
394     </p>
397     <p>
398     In the REST binding, the service metadata shall be a single web
399     resource with a registered URL. The date and time at which the
400     metadata last changed shall be obtained from the <i>Last-Modified</i>
401     HTTP Header keyword sent in the response to a GET or HEAD request to the registered URI.</p><p>
402     All VO services should provide this interface.
403     </p>
405     <h3><a name="sec3_2">3.2 Non-service metadata (non-normative)</a></h3>
406     <p>There may be other metadata associated with a service than the capability metadata described above.
407     <ul><li> Every service has the Dublin Core resource metadata [13].
408     <li> Some services are associated with registered applications.
409     <li> Some services are associated with registered data collections.
410     </ul></p><p>None of these are explicitly provided for in this version of VOSI. Some might be covered in later versions of VOSI.
411     </p>
413     <h3><a name="sec3_3">3.3 Availability metadata</a></h3>
414     <p>This interface indicates whether the service is operable and the reliability of the service for extended and scheduled requests.
415     The availability shall be represented as an XML document in which the
416     root element is <i>{http://www.ivoa.net/xml/Availability/v1.0}availability</i>. This element
417     shall contain child elements providing the following information.</p>
418     <ul>
419     <li> <i>available</i> - whether the service is currently accepting requests
420     <li> <i>upSince</i> - duration for which the service has been continuously available
421     <li> <i>downAt</i> - the instant at which the service is next scheduled to be unavailable
422     <li> <i>backAt</i> - the instant at which the service is scheduled to become available again after down time;
423     <li> <i>note</i> - textual note, e.g. explaining the reason for unavailaility.
424     </ul><p>
425     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>
426     The XML document shall conform to the schema given in appendix A.2 of this specification.</p><p>
427     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>
428     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>
429     There are no special elements in the availability document for the
430     contact details of the service operator. These details may be given as
431     a <i>note</i> element if they are known to the service.</p>
432     <p>
433     In the REST binding, the availability shall be a single web resource with a registered URL</p><p>
434     All VO services shall provide this interface.
435     </p>
437     <h3><a name="sec3_4">3.4 Table metadata</a></h3>
438     <p>
439     Some services deal with tabular data. These data may be the target of
440     ADQL queries, as in TAP [14], 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>
441     The <i>VODataService</i> standard [<a href="#ref:vos">2</a>] defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.</p><p>
442     A service which uses tables in its interface should define a VOSI
443     endpoint from which table metadata can be read. The table metadata
444     shall be represented as an XML document of which the root element is
445     of type
446     <i>{http://www.ivoa.net/xml/VODataService/v1.1}TableSet</i>. This
447     element may contain any mix of elements allowed by the VODataService
448     XML schema.</p><p>
449     In the REST binding, the table metadata shall be a single web resource with a registered URL.
450     </p>
452     <h2><a name="sec4">4. Registration of VOSI endpoints</a></h2>
453     <p>
454     The endpoints for the service and availability metadata shall be
455     included in the registration of each service that provides them.
456     </p>
457     <center>
458     <table>
459     <tr><th align="left">Endpoint type</th><th align="left">standardID value</th></tr>
460     <tr><td>availability</td><td>ivo://ivoa.net/std/VOSI#availability</td></tr>
461     <tr><td>capabilties</td><td>ivo://ivoa.net/std/VOSI#capabilities</td></tr>
462     <tr><td>tables</td><td>ivo://ivoa.net/std/VOSI#tables</td></tr>
463     </table>
464     </center>
465     <p>
466     An availability endpoint shall be represented by an element named
467     <i>capability</i>, of type
468     <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i> (defined by
469     the standard VOResource XML schema [<a href="ref:vor">1</a>]). The
470     value of the <i>standardID</i> attribute of the <i>capability</i>
471     shall be <i>ivo://ivoa.net/std/VOSI#availability</i>.
472     </p>
474     <p>
475     A capabilities endpoint should be represented by an element named
476     <i>capability</i>, of type
477     <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i>. If such
478     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>
479     A tables endpoint should be represented by an element named
480     <i>capability</i>, of type
481     <i>{http://www.ivoa.net/xml/VOResource/v1.0}Capability</i>. If such
482     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>.
483     </p>
485     <p>
486     With all three VOSI functions, the capability element that describes
487     the function must contain an interface element of a type semantically
488     appropriate for the binding of the function to the service; the
489     <i>accessURL</i> element within the interface element indicates the
490     endpoint for the VOSI function. For the REST binding, this
491     <i>accessURL</i> element must set the <i>use</i> attribute to "full".
492     Furthermore, for the REST binding, this document recommends using the
493     <i>{http://www.ivoa.net/xml/VODataService/v1.1}ParamHTTP</i> interface
494     type to encode VOSI endpoints (see examples given in
495     <a href="#sec5">section 5</a>).
496     </p>
499     <h2><a name="sec5">5. Example VOSI responses</a></h2>
501 rplante@ncsa.uiuc.edu 1376 <!-- Space to push page break in PDF version
502     <br />
503     <br />
504 rplante@ncsa.uiuc.edu 1457 -->
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;
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;
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;
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;
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;
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>
635     <br/>
636     <h2><a name="appA">Appendix A: VOSI XML schemas</a></h2>
638     <a name="appA1">
639     <h3>A.1. The Complete VOSICapabilities Schema</h3></a>
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;
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;
659     &lt;xsd:import namespace="http://www.ivoa.net/xml/VOResource/v1.0"
660     schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0" /&gt;
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;
672     &lt;xsd:complexType&gt;
673     &lt;xsd:sequence&gt;
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;
689     &lt;/xsd:sequence&gt;
690     &lt;/xsd:complexType&gt;
691     &lt;/xsd:element&gt;
693     &lt;/xsd:schema&gt;
694     </pre>
696     <a name="appA2">
697     <h3>A.2. The Complete VOSIAvailability Schema</h3></a>
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;
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;
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;
722     &lt;xsd:complexType name="Availability"&gt;
723     &lt;xsd:sequence&gt;
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;
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;
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;
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;
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;
768     &lt;/xsd:sequence&gt;
769     &lt;/xsd:complexType&gt;
771     &lt;/xsd:schema&gt;
772     </pre>
774     <a name="appA3">
775     <h3>A.3. The Complete VOSITables Schema</h3></a>
777     <pre>
778     &lt;xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
779     xmlns:tns="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
780     xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
781     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
782     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
783     elementFormDefault="qualified"
784     attributeFormDefault="unqualified"
785     version="1.0rc1"&gt;
787     &lt;xsd:annotation&gt;
788     &lt;xsd:documentation&gt;
789     A schema for formatting table metadata as returned by a
790     tables resource, defined by the IVOA Support Interfaces
791     specification (VOSI).
792     See http://www.ivoa.net/Documents/latest/VOSI.html.
793     &lt;/xsd:documentation&gt;
794     &lt;/xsd:annotation&gt;
796     &lt;xsd:import namespace="http://www.ivoa.net/xml/VODataService/v1.1"
797     schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1" /&gt;
799     &lt;!--
800     - the root element for a VOSI table metadata (section 3.4)
801     --&gt;
802     &lt;xsd:element name="tableset" type="vs:TableSet" &gt;
803     &lt;xsd:annotation&gt;
804     &lt;xsd:documentation&gt;
805     A description of the table metadata supported by the
806     service associated with a VOSI-enabled resource.
807     &lt;/xsd:documentation&gt;
808     &lt;/xsd:annotation&gt;
809     &lt;/xsd:element&gt;
811     &lt;/xsd:schema&gt;
812     </pre>
814     <h2><a name="appB">Applendix B: Changes from previous versions</a></h2>
816     <h4>Changes since PR-20100311</h4>
817     <ul>
818     <li>Inclusion of IVOA Architecture text </li>
819     <li>Restructuring and clarification in response to RFC comments</li>
820     <li>Inclusion of VOSITables schema in appendix</li>
821     <li>Second example added for a TAP service response</li>
822     </ul>
824     <h4>Changes since WD-20090825</h4>
826     <ul>
827     <li> Mandate the use of VOSICapabilities to return capabilities </li>
828     <li> S2.1: added non-normative note about capability sub-types; added
829     example capabilities metadata </li>
830     <li> Recommend the inclusion of VOSI interfaces in capability metadata</li>
831     <li> S2.5: When returning capabilities metadata, require VOSI (REST)
832     accessURLs to have use="full"; recommend this use of ParamHTTP. </li>
833     <li> Rename Availability schema to VOSIAvailability; added
834     VOSICapabilities schema. </li>
835     </ul>
837     <h4>Changes since WD-20081030</h4>
839     <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>
840     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>.
841     </p>
843     <br/>
844     <h2><a name="ref">References</a></h2>
846     <dl>
847     <dt> <a name="ref:vor">[1]</a> </dt>
848     <dd> Plante, R., Benson, K., Graham, M., Greene,
849     G., Harrison, P., Lemson, G., Linde, T., Rixon,
850     G., St&eacute;b&eacute;, A. 2008, <cite>
851     <a href="http://www.ivoa.net/Documents/cover/VOResource-20080222.html">
852     VOResource: an XML Encoding Schema for Resource Metadata</a></cite>,
853     v1.03, IVOA Recommendation,
854     <code>http://www.ivoa.net/Documents/cover/VOResource-20080222.html</code>
855     </dd>
857     <dt> <a name="ref:vos">[2]</a> </dt>
858     <dd> Plante, R., St&eacute;b&eacute;, A., Benson, K., Dowler, P.,
859     Graham, M., Greene, G., Harrison, P., Lemson, G., Linde, T.,
860     Rixon, G. 2008, <cite>
861     <a href="http://www.ivoa.net/Documents/VODataService/20090903/">
862     VODataService: a VOResource Schema Extension for Describing
863     Collections and Services</a></cite>,
864     v1.1, IVOA Proposed Recommendation,
865     <code>http://www.ivoa.net/Documents/VODataService/20090903/</code>
866     </dd>
867     </dl>
871     </body></html>

ViewVC Help
Powered by ViewVC 1.1.26