IVOA Proposed Recommendation - IVOA Support Interfaces

This document describes the minimum interface that a (SOAP- or REST-based) web service requires to participate in the IVOA.

Status of this Document

This is an IVOA Proposed Recommendation made available for public review.
It is appropriate to reference this document only as a recommended standard that is under review and which may be changed before it is accepted as a full recommendation.
The first release of this document was 2010 March 11 .

A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.

Acknowledgments

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.

Conformance related definitions

The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and "OPTIONAL" (in upper or lower case) used in this document are to be interpreted as described in IETF standard, RFC 2119 [0].

The Virtual Observatory (VO) is a general term for a collection of federated resources that can be used to conduct astronomical research, education, and outreach. The International Virtual Observatory Alliance (IVOA) 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.

1. Introduction

The web services that comprise much of the Virtual Observatory (VO) come in two forms: SOAP-based (Simple Object Access Protocol, [1]) ones such as footprint and spectrum services [2], SkyNodes and Open SkyQuery [3], registry interfaces [4] and CDS access [5]; and RESTful (REpresentational State Transfer, [6]) ones such as TAP [7] and other second generation data access (DAL) services, and VOSpace 2.0 [8]. This document describes a set of common basic functions that all these services should provide in the form of a standard support interface in order to support the effective management of the VO.

The IVOA Web Services Basic Profile [9] mandates that a compliant SOAP-based web service should have the interface defined in this specification, as expressed using the standard WSDL (Web Services Description Language, [10]) format. For RESTful services, the requirement for the support interface is stated in the specification for each kind of service. A contract for a RESTful service may specify extra constraints (e.g., on the form of the URIs) for the support interface.

1.2 The role in the IVOA Architecture

The IVOA Architecture [11] provides a high-level view of how IVOA standards work together to connect users and applications with providers of data and services, as depicted in the diagram in Fig. 1.

In this architecture, users employ a variety of tools (from the User Layer) to discover and access archives and services--that is, resources--of interest (represented in the Resource Layer). A registry plays a role in discovery by harvesting metadata that describe archives and services and making them searchable from a central service. The VOSI interface provides a means for a service to provide some of this metadata itself; this allows a registry to pull the metadata from the service rather than relying on a human to provide it (e.g. by typing the data into a registration form manually). This mechanism can make it easier to collect highly detailed metadata (e.g. descriptions of columns in a catalog) that might not be practically provided otherwise. As some of this metadata describes the service interface and how it behaves, other applications can use this information for controlling how they use the service. Even when the service is "discovered" through some means other than a registry, an application can still understand how to use the service by querying for this information directly.

Once a user discovers data and services of interest, she will want to use engage them in an analysis process. Success requires that the selected services are actually up and running properly as a down service can cause auotmated processing to fail completely. Registry and workflow services can assist with this by tracking the availability of services and alerting users about downtime. We envision that VOSI will allow VO projects to better track the overall health of the VO ecosystem.

2. Interface bindings

The standard interface returns metadata without changing the state of the service with which it is associated. This could, in principle, be implemented in any of three ways:

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 HTTP 405 "Method not allowed" status code.

The endpoints and interface types for the support interface shall be defined in the service's registration using one Capability element for each interface. The values of the standardID attribute for these Capabilitys are given in section 4.

When using the REST binding, any HTTP URLs may be used. The client must find the appropriate URLs from the service's entry in the VO registry and, in general, should not try and infer the URLs from any other URLs for that service. However, standards for specific services may put extra constraints on the form of the URLs.

3. Metadata specification

There are various classes of metadata that might be returned by a service through its standard interface:

This section defines how each of these classes is represented. The following typographic convention is used to represent a XML element defined within a particular namespace:

For example, {http://www.ivoa.net/xml/VOResource/v1.0}resource indicates a XML element named resource that is described in the XML schema associated with the 'http://www.ivoa.net/xml/VOResource/v1.0' namespace - in this case, this would be VOResource.xsd [12].

3.1 Capability metadata

This interface provides the service metadata in the form of a list of Capability descriptions. Each of these descriptions is an XML element that:

For example, one capability might describe a cone search function and another the TAP implementation but these two might well apply to the same service.

An entry for a service in the resource registry - i.e., its VOResource - contains the Dublin Core resource metadata (identifier, curation information, content description, etc.) followed by the service's capability descriptions (expressed as a series of {http://www.ivoa.net/xml/VOResource/v1.0}Capability elements). Effectively, the resource metadata describes the service to human users and the capability list describes it to software. Therefore, the latter list has two uses:

The service metadata shall be represented as an XML document with the root element {http://www.ivoa.net/xml/VOSICapabilities/v1.0}capabilities. (See Appendix A.1 for the definition of the VOSICapabilities XML schema.) This element must contain one or more child capability elements that describe the capabilities of the service. Given that the capability element is defined to be of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability, a capability element may be represented by a legal sub-type of {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]).

The VOResource list of capabilities should include capabilities describing VOSI endpoints as specified in section 4.

In the REST binding, the service metadata shall be a single web resource with a registered URL. The date and time at which the metadata last changed shall be obtained from the Last-Modified HTTP Header keyword sent in the response to a GET or HEAD request to the registered URI.

3.2 Non-service metadata (non-normative)

There may be other metadata associated with a service than the capability metadata described above.

None of these are explicitly provided for in this version of VOSI. Some might be covered in later versions of VOSI.

3.3 Availability metadata

This interface indicates whether the service is operable and the reliability of the service for extended and scheduled requests. The availability shall be represented as an XML document in which the root element is {http://www.ivoa.net/xml/Availability/v1.0}availability. This element shall contain child elements providing the following information.

The elements upSince, downAt, backAt and note 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 A.2 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 checks fail, the service should set available to false in the availability output.

If a service is to be online but unavailable for work (e.g., when a service with a work queue intends to shut down after draining the queue) then the service should set available to false.

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.

In the REST binding, the availability shall be a single web resource with a registered URL

3.4 Table metadata

Some services deal with tabular data. These data may be the target of ADQL queries, as in TAP [7], or they may be the output of other operations, as in SIAP queries. In each case, it is useful if the service describes the details of the tables concerned. It is more useful if this description can be captured in the resource registry.

The VODataService standard [14] defines XML elements for describing a set of tables. These elements can be included in a resource document for a service.

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.

4. Registration of VOSI endpoints

The endpoints for the service and availability metadata shall be included in the registration of each service that provides them.

Endpoint type	standardID value
availability	ivo://ivoa.net/std/VOSI#availability
capabilties	ivo://ivoa.net/std/VOSI#capabilities
tables	ivo://ivoa.net/std/VOSI#tables

An availability endpoint shall be represented by an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability (defined by the standard VOResource XML schema [12]). The value of the standardID attribute of the capability shall be ivo://ivoa.net/std/VOSI#availability.

A capabilities endpoint should be represented by an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability. If such a capability is provided then the value of the standardID attribute must be ivo://ivoa.net/std/VOSI#capabilities.

A tables endpoint should be represented by an element named capability, of type {http://www.ivoa.net/xml/VOResource/v1.0}Capability. If such a capability is provided then the value of the standardID attribute must be ivo://ivoa.net/std/VOSI#tables.

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).

5. Example VOSI responses

Example 1:

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&amp; </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>

Example 2:

A sample response from a tables resource describing a TAP service.

<?xml version="1.0" encoding="UTF-8"?>
<vosi:tableset
  xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">
  <schema>
    <name>cfht </name>
    <table type="output">
      <name>cfht.deepU </name>
      <column>
        <name>cfhtlsID </name>
        <dataType xsi:type="vod:TAP" size="30">adql:VARCHAR </dataType>
      </column>
      <column>
        <name>survey </name>
        <dataType xsi:type="vod:TAP" size="6">adql:VARCHAR </dataType>
      </column>
      <column>
        <name>field </name>
        <dataType xsi:type="vod:TAP" size="2">adql:VARCHAR </dataType>
      </column>
      <column>
        <name>pointing </name>
        <dataType xsi:type="vod:TAP" size="6">adql:VARCHAR </dataType>
      </column>
      <column>
        <name>selectionFilter </name>
        <dataType xsi:type="vod:TAP" size="2">adql:VARCHAR </dataType>
      </column>
    </table>
    <table type="output">
      <name>TAP_SCHEMA.keys </name>
      <column>
        <name>key_id </name>
        <description>unique key to join to TAP_SCHEMA.key_columns </description>
        <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>
      </column>
      <column>
        <name>from_table </name>
        <description>the table with the foreign key </description>
        <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>
      </column>
      <column>
        <name>target_table </name>
        <description>the table with the primary key </description>
        <dataType xsi:type="vod:TAP" size="64">adql:VARCHAR </dataType>
      </column>
    </table>
  </schema>
</vosi:tableset>

Appendix A: VOSI XML schemas

Applendix B: Changes from previous versions

Changes since PR-20100311

Changes since WD-20090825

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.

IVOA Support Interfaces
Version 1.00-20101206

IVOA WG Proposed Recommendation 2010 December 6

Abstract

Status of this Document

Acknowledgments

Conformance related definitions

Contents

1. Introduction

1.2 The role in the IVOA Architecture

2. Interface bindings

3. Metadata specification

3.1 Capability metadata

3.2 Non-service metadata (non-normative)

3.3 Availability metadata

3.4 Table metadata

4. Registration of VOSI endpoints

5. Example VOSI responses

Appendix A: VOSI XML schemas

A.1. The Complete VOSICapabilities Schema

A.2. The Complete VOSIAvailability Schema

A.3. The Complete VOSITables Schema

Applendix B: Changes from previous versions

Changes since PR-20100311

Changes since WD-20090825

Changes since WD-20081030

References

IVOA Support Interfaces Version 1.00-20101206

IVOA WG Proposed Recommendation 2010 December 6

A.1. The Complete VOSICapabilities Schema

A.2. The Complete VOSIAvailability Schema

A.3. The Complete VOSITables Schema

Changes since PR-20100311

Changes since WD-20090825

Changes since WD-20081030

IVOA Support Interfaces
Version 1.00-20101206