This document describes the minimum required interface to participate in the IVOA as a web service.
This is a Working Draft. The first release of this document was 2008 Oct 30.
This is an IVOA Working Draft for review by IVOA members and other interested parties.
It is a draft document and may be updated, replaced, or obsoleted by other documents at any time.
It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than "work in progress.
A list of
current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.
This work is based on discussions and actions from the 2003 IVOA
meeting in Strasbourg and further discussions on registry
functionality at JHU late in 2003. Later inputs came from a local
meeting at JHU in Sept. 2004. William O'Mullane and Ani Thakar were the editors and primary authors for these early versions.
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.
Much of the Virtual Observatory (VO) is made up of web services in
SOAP and REST forms. It is felt there are some basic functions that
all these services should provide in order to support management of
the VO.
These standard interfaces are mandated by the VO basic profile for SOAP services and hence should appear in all SOAP services, using the standard WSDL extract in this specification. For REST services, the requirement for the support interfaces is stated in the specification for each kind of service. A contract for a REST service may specify extra constraints (e.g. on the form of the URIs) for the support interfaces.
In the normal requirements manner the words "should" and "shall" are used to convey the level of necessity of the interface.
The standard interfaces all return metadata without changing the
state of the service to which they apply. They could, in principle be
implemented in any of three ways.
- As extra SOAP operations on an existing SOAP endpoint of the service to which they apply. This would be a 'SOAP binding' of VOSI.
- As SOAP operations on a separate SOAP endpoint. This would be an alternate form of the SOAP binding.
- As web resources with distinct URLs, without using the SOAP protocol. This is the 'REST binding' for the standard interfaces.
This standard requires the REST binding of VOSI even when applied to
services that otherwise use SOAP. No details of the SOAP binding are
given in this version of the standard.
In the REST binding, the support interfaces shall have distinct URLs in the HTTP scheme and shall be accessible by the GET operation in the HTTP protocol. The response to an HTTP POST, PUT or DELETE to these resources is not defined by this specification. However, if an implementation has no special action to perform for these requests, the normal response would be a 405 "Method not allowed" error.
The endpoints and interface types for the support interfaces shall be defined in the service's registration using one Capability element for each interface. The standardId values for these Capabilities are given in section 2.4.
When using the REST binding, any HTTP URLs may be used. The client must find the appropriate URLs from the registration 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.
This interface provides the service metadata in the form of a list of Capability descriptions. Each of these descriptions is an XML element that
- states that the service provides a particular, IVOA-standard function;
- lists the interfaces for invoking that function;
- records any details of the implementation of the function that
are not fixed in the standard for that function.
E.g., one capability might describe a cone-search function and another the table-access-protocol implementation; these two might well be apply to the same service.
An entry for a service in the resource registry - i.e. its VOResource - contains the Dublin-core resource metadata (identifier, curation information, content description etc.) followed by the service's capability descriptions. Effectively, the resource metadata describe the service to human users and the capability list describes it to software. Therefore, the capability list alone has two uses.
- It may be read by a client application to find out how to drive the service. This presumes that the service has been already been selected and the VOSI endpoint located.
- 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.
The service metadata shall be represented as an XML document with the
root element
{http://www.ivoa.net/xml/VOSICapabilities/v1.0}capabilities.
(See Appendix A.1 for the definition the
VOSICapabilities schema.) This element must contain one or more child
capability elements that describe the capabilities of the
service. Given that the capability element is defined to be of type
{http://www.ivoa.net/xml/VOResource/v1.0}Capability, a capability
element may be represented by a legal sub-type of
{http://www.ivoa.net/xml/VOResource/v1.0}Capability, in which
case, the capability element must use an xsi:type
attribute to identify the sub-type (see section 2.2.1 of
[1]).
- Note:
- The value of the capability element's standardID attribute is used
to indicate the service's support for particular standard protocols
(such as Simple Image Access, Simple Cone Search, etc.). In the
case of some protocols, the support for the standard is further
characterized by additional metadata provided by a standard Capability
extension for that protocol. The extension metadata is enabled by
adding a xsi:type attribute to the capability element set to the
Capability sub-type for that protocol (see example below).
|
The list of capabilities should include capabilities describing VOSI
endpoints as specified in section 2.5.
a sample response from a capabilities
resource describing an SIA service.
<?xml version="1.0" encoding="UTF-8"?>
<vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0"
xmlns:sia="http://www.ivoa.net/xml/SIA/v1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ivoa.net/xml/VOSI/v1.0
http://www.ivoa.net/xml/VOSI/v1.0
http://www.ivoa.net/xml/VOResource/v1.0
http://www.ivoa.net/xml/VOResource/v1.0
http://www.ivoa.net/xml/VODataService/v1.0
http://www.ivoa.net/xml/VODataService/v1.0
http://www.ivoa.net/xml/SIA/v1.0
http://www.ivoa.net/xml/SIA/v1.0">
<!-- a generic capability (for custom, non-standard interfaces) -->
<capability>
<interface xsi:type="vr:WebBrowser">
<accessURL use="full"> http://adil.ncsa.uiuc.edu/siaform.html </accessURL>
</interface>
</capability>
<!-- the SIA capability -->
<capability xsi:type="sia:SimpleImageAccess" standardID="ivo://ivoa.net/std/SIA">
<interface xsi:type="vs:ParamHTTP" role="std">
<accessURL> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f& </accessURL>
</interface>
<imageServiceType>Pointed</imageServiceType>
<maxQueryRegionSize>
<long>360.0</long>
<lat>180.0</lat>
</maxQueryRegionSize>
<maxImageExtent>
<long>360.0</long>
<lat>180.0</lat>
</maxImageExtent>
<maxImageSize>
<long>5000</long>
<lat>5000</lat>
</maxImageSize>
<maxFileSize>100000000</maxFileSize>
<maxRecords>5000</maxRecords>
</capability>
<!-- the interface that returns this document -->
<capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
<interface xsi:type="vs:ParamHTTP" role="std">
<accessURL use="full"> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/capabilities </accessURL>
</interface>
</capability>
<!-- the interface that returns this document -->
<capability standardID="ivo://ivoa.net/std/VOSI#availability">
<interface xsi:type="vs:ParamHTTP" role="std">
<accessURL use="full"> http://adil.ncsa.uiuc.edu/cgi-bin/voimquery/availability </accessURL>
</interface>
</capability>
</vosi:capabilities>
In the REST binding, the service metadata shall be a single web-resource with a registered URL. The data and time at which the metadata last changed shall be obtained the Last-Modified HTTP-header sent in the response to a GET or HEAD request to the registered URI.
All VO services should provide this interface.
There may be other metadata associated with a service than the capability metadata described above.
- Every service has the Dublin-core "resource" metadata.
- Some services are associated with registered applications.
- Some services are associated with registered data collections.
None of these are explicitly provided for in this version of VOSI. Some might be covered in later versions of VOSI.
This interface indicates whether the service is operable and the reliability of the service for extended and scheduled requests.
The availability shall be represented as an XML document in which the
root element is {http://www.ivoa.net/xml/Availability/v0.4}availability. This element
shall contain child elements providing the following information.
- available - whether the service is currently accepting requests;
- upSince - duration for which the service has been continuously available
- downAt - the instant at which the service is next scheduled to be unavailable
- backAt - the instant at which the service is scheduled to become available again after down time;
- note - textual note, e.g. explaining the reason for unavailaility.
The elements upSince, downAt, backAt and notes are optional. The available element is mandatory. There may be more than one note element.
The XML document shall conform to the schema given in appendix 1 of this specification.
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 check fail, the service should set available to false in the availability output.
If a service wishes to be on-line but unavailable for work (e.g. when a service with a work queue intends to shut down after draining the queue) then the service should set available to false.
There are no special elements in the availability document for the contact details of the service operator. These details may be given as a note element if they are known to the service.
Ultimately some portals may track these heartbeats and compile uptime statistics. With the location we could have 3D global maps of services and availability.
In the REST binding, the availability shall be a single web-resource with a registered URIL
All VO services shall provide this interface.
Some services deal with tabular data. These data may be the target of ADQL queries, as in the Table Access Protocol, 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.
The VODataService standard [2] defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.
A service which uses tables in its interface should define a VOSI endpoint from which table metadata can be read. The table metadata shall be represented as an XML document of which the root element is of type {http://www.ivoa.net/xml/VODataService/v1.1}TableSet. This element may contain any mix of elements allowed by the VODataService XML-schema.
In the REST binding, the table metadata shall be a single web-resource with a registered URL.
The endpoints for the service and availability metadata shall be
included in the registration of each service that provides them.
An availability endpoint shall be represented by an element named
capability, of type
{http://www.ivoa.net/xml/VOResource/v1.0}Capability (defined by
the standard VOResource XML schema [1]). The
value of the standardID attribute of the capability
shall be ivo://ivoa.net/std/VOSI#availability (sic; note the
use of the document fragment to identify one part of the VOSI
standard).
A capabilities endpoint should be represented an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability. If such a capability is provided then the value its standardID attribute must be ivo://ivoa.net/std/VOSI#capabilities.
A tables endpoint should be represented an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability. If such a capability is provided then the value its standardID attribute must be ivo://ivoa.net/std/VOSI#tables.
With all three VOSI functions, the capability element that describes
the function must contain an interface element of a type semantically
appropriate for the binding of the function to the service; the
accessURL element within the interface element indicates the
endpoint for the VOSI function. For the REST binding, this
accessURL element must set the use attribute to "full".
Furthermore, for the REST binding, this document recommends using the
{http://www.ivoa.net/xml/VODataService/v1.1}ParamHTTP interface
type to encode VOSI endpoints (see example given in section 2.1).
A.1. The Complete VOSICapabilities Schema
<xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
xmlns:tns="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.0rc1">
<xsd:annotation>
<xsd:documentation>
A schema for formatting service capabilities as returned by a
capabilities resource, defined by the IVOA Support Interfaces
specification (VOSI).
See http://www.ivoa.net/Documents/latest/VOSI.html.
</xsd:documentation>
</xsd:annotation>
<xsd:import namespace="http://www.ivoa.net/xml/VOResource/v1.0"
schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0" />
<!--
- the root element for a VOSI capabilities metadata (section 2.1)
-->
<xsd:element name="capabilities">
<xsd:annotation>
<xsd:documentation>
A listing of capabilities supported by a service
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="capability" type="vr:Capability"
form="unqualified" minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>
A capability supported by the service.
</xsd:documentation>
<xsd:documentation>
A protocol-specific capability is included by specifying a
vr:Capability sub-type via an xsi:type attribute on this
element.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
A.2. The Complete VOSIAvailability Schema
<xsd:schema targetNamespace="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
xmlns:tns="http://www.ivoa.net/xml/VOSIAvailability/v1.0"
xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.0rc1">
<xsd:annotation>
<xsd:documentation>
A schema for formatting availability metadata as returned by an
availability resource defined in the IVOA Support Interfaces
specification (VOSI).
See http://www.ivoa.net/Documents/latest/VOSI.html.
</xsd:documentation>
</xsd:annotation>
<!--
- the root element for a VOSI availability (section 2.3)
-->
<xsd:element name="availability" type="tns:Availability"/>
<xsd:complexType name="Availability">
<xsd:sequence>
<xsd:element name="available" type="xsd:boolean">
<xsd:annotation>
<xsd:documentation>
Indicates whether the service is currently available.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="upSince" type="xsd:dateTime" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
The instant at which the service last became available.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="downAt" type="xsd:dateTime" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
The instant at which the service is next scheduled to become
unavailable.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="backAt" type="xsd:dateTime" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
The instant at which the service is scheduled to become available
again after a period of unavailability.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="note" type="xsd:string"
minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>
A textual note concerning availability.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
Changes since WD-20090825
- Mandate the use of VOSICapabilities to return capabilities
- S2.1: added non-normative note about capability sub-types; added
example capabilities metadata
- Recommend the inclusion of VOSI interfaces in capability metadata
- S2.5: When returning capabilities metadata, require VOSI (REST)
accessURLs to have use="full"; recommend this use of ParamHTTP.
- Rename Availability schema to VOSIAvailability; added
VOSICapabilities schema.
Changes since WD-20081030
The REST binding is made mandatory for all kinds of service. Details of the SOAP binding, including its WSDL contract, are removed.
The definition of the root element for the table-metadata document is corrected. Instead of requiring the tableset element from VODataService 1.1 (which element does not exist in that schema), the text now requires an element of type TableSet.
- [1]
- Plante, R., Benson, K., Graham, M., Greene,
G., Harrison, P., Lemson, G., Linde, T., Rixon,
G., Stébé, A. 2008,
VOResource: an XML Encoding Schema for Resource Metadata,
v1.03, IVOA Recommendation,
http://www.ivoa.net/Documents/cover/VOResource-20080222.html
- [2]
- Plante, R., Stébé, A., Benson, K., Dowler, P.,
Graham, M., Greene, G., Harrison, P., Lemson, G., Linde, T.,
Rixon, G. 2008,
VODataService: a VOResource Schema Extension for Describing
Collections and Services,
v1.1, IVOA Proposed Recommendation,
http://www.ivoa.net/Documents/VODataService/20090903/
