DescribingServicesVORv09 < IVOA

<h1>Describing Services with VOResource v0.9 </h1>
<h3>Ray Plante</h3>

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

In this summary, I will explain:

<dl>
  <dd> <a href="model">1.  The Basic Model: Capability and
       Interface</a> </dd>
  <dd> <a href="#interface">2.  Using the Interface</a>  
       <dl>
         <dd> <a href="#accessURL">2.1.  the <nop>AccessURL and the different
              types of Interfaces</a> </dd>
         <dd> <a href="#inputs">2.2.  Describing Inputs</a> </dd>
         <dd> <a href="#outputs">2.3.  Describing Outputs</a> </dd>
       </dl>
  </dd>
  <dd> <a href="#tables">3.  Describing Tabular Output</a> </dd>
</dl>

<a name="model">
<h2>1. The Basic Model: Capability and Interface</h2></a>

The <a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Service">Service</a>
element extends the generic Resource element; that is,
"<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Service">Service</a>" is in the
"<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Resource">Resource"</a>
substitution group, and Service's type, "<nop>ServiceType" is an extension
of "<nop>ResourceType".  Services adds two complex elements to the core
metadata:  Capability and Interface.  <p> 

<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Capability">Capability</a>
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:  <nop>ConeSearch-v0.2.xsd defines the <nop>ConeSearch element, and
SIA-v0.6.xsd defines the <nop>SimpleImageAccess element.  <p>

<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Capability">Capability</a>
has two optional metadata terms that can apply to any service.  The
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_StandardID">StandardID</a>
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 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_StandardURL">StandardURL</a>
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.  <p>

The <a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Interface">Interface</a>
element describes how to use the service.  The category of interface
is given with the
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Invocation">Invocation</a>
element; this value determines how the <nop>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 <nop>AccessURL is mandatory, all services
are assumed to be web-based.  <p>

In this document, we will examine an example of a description of an
Simple Image Access (SIA) service, [[%ATTACHURL%/sia.xml][sia.xml]].  As an SIA service, it
utilizes the VOResource extension,
<a href="http://www.ivoa.net/xml/SIA/SIA-v0.6.xsd">SIA-v0.6.xsd</a>.
This schema provides an extension of the 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Capability">Capability</a>
element called
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_SimpleImageAccess">SimpleImageAccess</a>
which contains SIA-specific metadata about this particular
implementation.  

   

<a name="interface">
<h2>2.  Using the Interface</h2></a>

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

<a name="accessURL">
<h3>2.1.  the <nop>AccessURL and the different types of Interfaces</h3></a>

<table width="100%" border="2" cellpadding="2">
  <tr>
    <th valign="top"><a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Invocation">Invocation</a></th>
    <th valign="top" width="40%">Meaning</th>
    <th valign="top" width="40%"><a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_AccessURL">AccessURL</a> refers to...</th>
  </tr>
  <tr>
    <td valign="top"><nop>WebService</td>
    <td valign="top">The interface is a Web Service described by a WSDL document</td>
    <td valign="top">the WSDL document.  <br>
        <em>There is discussion that the <nop>AccessURL
        in this case should point to the Web Service endpoint.  </em>
  </tr>

<tr>
    <td valign="top"><nop>WebBrowser</td>
    <td valign="top">The interface is an interactive form accessed via a web browser</td>
    <td valign="top">the URL for the web form.</em>
  </tr>

  <tr>
    <td valign="top"><nop>GLUService</td>
    <td valign="top">A service that is described in a GLU registry</td>
    <td valign="top">the URL to the GLU record</td>
  </tr>

  <tr>
    <td valign="top">Extended</td>
    <td valign="top">A service that is described using an extension of
                     the
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Interface">Interface</a>
                     element.  The
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_ParamHTTP">ParamHTTP</a> element,
                     defined in the <nop>VODataService schema, is an
                     example that handles interfaces like Cone Search
                     and SIA.  </td>
    <td valign="top">The specific extension should indicate what it refers to.
                     The "role" attribute of the
                     <a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_AccessURL">AccessURL</a>
indicates whether it is a base URL, a full URL pointing to a document,
or a full URL pointing to a directory.</em> 
  </tr>

  <tr>
    <td valign="top">Custom</td>
    <td valign="top">A service that doesn't fit into any of the above
                     categories</td>
    <td valign="top">The Description element should indicate what the
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_AccessURL">AccessURL</a>
                     refers to.  The "role" attribute of the
                     <a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_AccessURL">AccessURL</a>
indicates whether it is a base URL, a full URL pointing to a document,
or a full URL pointing to a directory.</em>
  </tr>

</table> <p>

Looking at our [[%ATTACHURL%/sia.xml][example]], SIA is a traditional URL-based query service
(i.e. using HTTP GET); thus, it uses the 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_ParamHTTP">ParamHTTP</a>
extension to describe the interface:

<pre>
<font size="-1">    &lt;ParamHTTP qtype="GET" xmlns="http://www.ivoa.net/xml/VODataService/v0.4"&gt;
      &lt;vr:Invocation&gt;Extended&lt;/vr:Invocation&gt;
      &lt;vr:AccessURL use="base"&gt;http://adil.ncsa.uiuc.edu/vocone?&lt;/vr:AccessURL&gt;
      ...
    &lt;/ParamHTTP&gt;</font>
</pre> 

The use of the "base" attribute to 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_AccessURL">AccessURL</a>
indicates that the URL given is a base URL.  It is implicit in the
definition of
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_ParamHTTP">ParamHTTP</a>
(with qtype="GET") that input parameters should be appended with the
pattern <em>name=value</em>&amp;<em>name=value</em>....   

<a name="inputs">
<h3>2.2 Describing Inputs</h3></a>

How inputs are described depends the type of interface.  For Web
Services, we depend on the WSDL document pointed to by the
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_AccessURL">AccessURL</a>
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.)  <p>

Traditional GET and POST services should be described by the 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_ParamHTTP">ParamHTTP</a>
extension to the
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Interface">Interface</a>
element.  
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_ParamHTTP">ParamHTTP</a>
assumes simple <em>name=value</em> inputs.  To describe these, it
allows zero or more 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_Param">Param</a>
elements to describe the input parameters.  Each parameter is
described by a Name, Description, <nop>DataType, Unit, and UCD.  <p>

<em>Needed: we need to indicate which parameters are required and
which are optional.</em>  <p>

In our [[%ATTACHURL%/sia.xml][example]], the SIA service uses 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_Param">Param</a>
elements to describe the supported input parameters.

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

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

<a name="outputs">
<h3>2.3.  Describing Outputs</h3></a>

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

For traditional GET and POST services, the output is described in the
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_ParamHTTP">ParamHTTP</a>
element's
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_HTTPResults">HTTPResults</a>,
which simply is a MIME-type string.  <p>

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 <nop>TabularSkyService.  This is discussed below.  <p>

In our [[%ATTACHURL%/sia.xml][example]], the 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_HTTPResults">HTTPResults</a>
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.

<pre>
<font size="-1">    &lt;ParamHTTP qtype="GET" xmlns="http://www.ivoa.net/xml/VODataService/v0.4"&gt;
      &lt;vr:Invocation&gt;Extended&lt;/vr:Invocation&gt;
      <b>&lt;vr:AccessURL use="base"&gt;http://adil.ncsa.uiuc.edu/vocone?&lt;/vr:AccessURL&gt;</b>
      ...
    &lt;/ParamHTTP&gt;</font>
</pre>

<a name="tables">
<h2>3.  Describing Tabular Output</h2></a>

A service that returns a table should described with the Resource
sub-type called
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_TabularSkyService">TabularSkyService</a>.
This resource type (which is actually a sub-class of
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VOResource-v0.9.html#element_Service">Service</a>)
adds the
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_Table">Table</a>
element that describes each of the columns.  The
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_Column">Column</a>
element is of the same type as
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_Param">Param</a>
element; thus, you can give things like Name, Description, <nop>Datatype,
Unit, and UCD.  <p>

In our [[%ATTACHURL%/sia.xml][example]], we see the table contents described within the 
<a href="http://nvo.ncsa.uiuc.edu/VO/schemas/vomdoc-v0.9/VODataService-v0.4.html#element_Table">Table</a>
element:

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

  


   






<br><br><br>
<!--
      * Set ALLOWTOPICRENAME = IVOA.TWikiAdminGroup
-->
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
xml	sia.xml	r1	manage	8.6 K	2004-05-18 - 17:14	RayPlante	full example refered to in text
This topic: IVOA > WebHome > IvoaResReg > IVOARegWp03 > DescribingServicesVORv09
Topic revision: r3 - 2004-05-19 - MarcoLeoni