Describing Services with VOResource v0.9

Ray Plante

This document summarizes how Services are described with the VOResource version 0.9 and its related extensions. This document was motivated by AstroGrid research into a generic service description model that supports automated work flows (known as the Common Execution Architecture, CEA). It is hoped that this description will help clarify the requirements for a revision of the service description model. This version is not intended to be a tutorial for developers; however, it could easily evolve into one.

In this summary, I will explain:

1. The Basic Model: Capability and Interface

2. Using the Interface

2.1. the AccessURL and the different types of Interfaces

2.2. Describing Inputs

2.3. Describing Outputs

3. Describing Tabular Output

1. The Basic Model: Capability and Interface

The Service element extends the generic Resource element; that is, "Service" is in the "Resource" substitution group, and Service's type, "ServiceType" is an extension of "ResourceType". Services adds two complex elements to the core metadata: Capability and Interface.

Capability describes how the service behaves; in particular, it tells what its limitations are. This description is mainly in terms of metadata that is specific to the type of service. For example, Cone Search services must give the maximum search radius they support. Thus, every service standard (e.g. Cone Search, SIA) should extend this element to add the metadata that implementations can use to describe how they behave. So far, this has been done for Cone Search and SIA: ConeSearch-v0.2.xsd defines the ConeSearch element, and SIA-v0.6.xsd defines the SimpleImageAccess element.

Capability has two optional metadata terms that can apply to any service. The StandardID is an IVOA identifier for the standard it complies to; this, then, is an unambiguous way of identifying services that comply to a particular standard (or version of the standard). If no such standard exists (either an IVOA standard or a local standard), this term can be omitted. The StandardURL gives a URL for the human-readable document that describes the standard the service implements. This allows developers to discover how to use a standard service in general (like SIA) the first time they encounter one in a registry.

The Interface element describes how to use the service. The category of interface is given with the Invocation element; this value determines how the AccessURL should be interpreted, which is explained in the next below. Interface also allows an optional Description for human-readable text about the interface. Obviously, since the AccessURL is mandatory, all services are assumed to be web-based.

In this document, we will examine an example of a description of an Simple Image Access (SIA) service, sia.xml. As an SIA service, it utilizes the VOResource extension, SIA-v0.6.xsd. This schema provides an extension of the Capability element called SimpleImageAccess which contains SIA-specific metadata about this particular implementation.

2. Using the Interface

A Registry will contain a variety of different kinds of services which will include traditional "CGI" type services along side of modern Web Services. A principle behind the Interface model was not to duplicate information available through standard mechanisms associated with the interface type. The relevant types are Web Services and GLU Services which have their own ways to describe themselves.

2.1. the AccessURL and the different types of Interfaces

Looking at our example, SIA is a traditional URL-based query service (i.e. using HTTP GET); thus, it uses the ParamHTTP extension to describe the interface:

    <ParamHTTP qtype="GET" xmlns="http://www.ivoa.net/xml/VODataService/v0.4">
      <vr:Invocation>Extended</vr:Invocation>
      <vr:AccessURL use="base">http://adil.ncsa.uiuc.edu/vocone?</vr:AccessURL>
      ...
    </ParamHTTP>

The use of the "base" attribute to AccessURL indicates that the URL given is a base URL. It is implicit in the definition of ParamHTTP (with qtype="GET") that input parameters should be appended with the pattern name=value&name=value....

2.2 Describing Inputs

How inputs are described depends the type of interface. For Web Services, we depend on the WSDL document pointed to by the AccessURL to describe the inputs in the usual. It was expected that information beyond input types (e.g. UCDs) could be incorporated into the WSDL via either the XSD appinfo elements or WSDL extension mechanisms. GLU Services are fully described by GLU records from the GLU registry. (To date, we do not have any practical experience with registering GLU services.)

Traditional GET and POST services should be described by the ParamHTTP extension to the Interface element. ParamHTTP assumes simple name=value inputs. To describe these, it allows zero or more Param elements to describe the input parameters. Each parameter is described by a Name, Description, DataType, Unit, and UCD.

Needed: we need to indicate which parameters are required and which are optional.

In our example, the SIA service uses Param elements to describe the supported input parameters.

    <ParamHTTP qtype="GET" xmlns="http://www.ivoa.net/xml/VODataService/v0.4">
      <vr:Invocation>Extended</vr:Invocation>
      <vr:AccessURL use="base">http://adil.ncsa.uiuc.edu/vocone?</vr:AccessURL>
      <HTTPResults>text/xml</HTTPResults>
      <!-- 
           These are the supported input parameters taken from the ADIL
           SIA service's "Metadata" operation.  
         -->
      <Param>
        <vr:Name>POS</vr:Name>
        <vr:Description>Search Position in the form "ra,dec" where ra and dec are given in decimal degrees in the ICRS coordinate system.</vr:Description>
        <DataType arraysize="2">float</DataType>
        <Unit>degrees</Unit>
      </Param>
      <Param>
        <vr:Name>SIZE</vr:Name>
        <vr:Description>Size of search region in the RA and Dec. directions.</vr:Description>
        <DataType arraysize="2">float</DataType>
        <Unit>degrees</Unit>
      </Param>
      ...
      <Param>
        <vr:Name>FREQ</vr:Name>
        <vr:Description>Frequency of observation.</vr:Description>
        <DataType>float</DataType>
      </Param>
    </ParamHTTP>

While "POS" and "SIZE" (and others not shown) are required input parameters, "FREQ" is not; thus, this listing allows us to discover the support for this parameter.

2.3. Describing Outputs

Like the inputs, the outputs from a Web Service or a GLU Service are described by the WSDL and GLU record, respectively.

For traditional GET and POST services, the output is described in the ParamHTTP element's HTTPResults, which simply is a MIME-type string.

For Cone Search and SIA, the output is actually a VOTable that includes a particular set of columns. The columns returned are not described as part of the Interface description, but rather outside of it in the context of a TabularSkyService. This is discussed below.

In our example, the HTTPResults element indicates that the output is XML. Implicit in the definition of SIA is the assumption that this is a VOTable. (If a MIME type is available specifically for VOTable, this could be used instead.) The details regarding the contents of that table is handled separately, as described below.

    <ParamHTTP qtype="GET" xmlns="http://www.ivoa.net/xml/VODataService/v0.4">
      <vr:Invocation>Extended</vr:Invocation>
      <vr:AccessURL use="base">http://adil.ncsa.uiuc.edu/vocone?</vr:AccessURL>
      ...
    </ParamHTTP>

3. Describing Tabular Output

A service that returns a table should described with the Resource sub-type called TabularSkyService. This resource type (which is actually a sub-class of Service) adds the Table element that describes each of the columns. The Column element is of the same type as Param element; thus, you can give things like Name, Description, Datatype, Unit, and UCD.

In our example, we see the table contents described within the Table element:

  <vs:TabularSkyService>
    ...
    <Table xmlns="http://www.ivoa.net/xml/VODataService/v0.4">
       <Column>
          <vr:Name>Codename</vr:Name>
          <vr:Description>ADIL Image Identifier - Unique identifier for image, as assigned by the ADIL</vr:Description>
          <DataType arraysize="*">char</DataType>
       </Column>
       <Column>
          <vr:Name>Image Name</vr:Name>
          <vr:Description>Image Filename, as provide by author</vr:Description>
          <DataType arraysize="*">char</DataType>
       </Column>
       <Column>
          <vr:Name>Source Name</vr:Name>
          <vr:Description>Target Source of Image</vr:Description>
          <DataType arraysize="*">char</DataType>
          <UCD>ID_MAIN</UCD>
       </Column>
       <Column>
          <vr:Name>RA (Center)</vr:Name>
          <vr:Description>RA of Image Center (J2000)</vr:Description>
          <DataType>float</DataType>
          <Unit>degrees</Unit>
          <UCD>POS_EQ_RA_MAIN</UCD>
       </Column>
       ...
    </Table>
  </vs:TabularSkyService>