VODataService: a VOResource Schema Extension for Describing Collections and Services
Version 1.01

Status of this document

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

Acknowledgements

This document has been developed with support from the National Science Foundation's Information Technology Research Program under Cooperative Agreement AST0122449 with The Johns Hopkins University, from the UK Particle Physics and Astronomy Research Council (PPARC), and from the Eurpean Commission's Sixth Framework Program via the Optical Infrared Coordination Network (OPTICON).

The Virtual Observatory (VO) is 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.

XML document validation is a software process that checks that an XML document is not only well-formed XML but also conforms to the syntax rules defined by the applicable schema. Typically, when the schema is defined by one or more XML Schema [schema] documents (see next section), validation refers to checking for conformance to the syntax described in those Schema documents. This document describes additional syntax constraints that cannot be enforced solely by the rules of XML Schema; thus, in this document, use of the term validation includes the extra checks that goes beyond common Schema-aware parsers which ensure conformance with this document.

The eXtensible Markup Language, or XML, is document syntax for marking textual information with named tags and is defined by the World Wide Web Consortium (W3C) Recommendation, XML 1.0 [XML]. The set of XML tag names and the syntax rules for their use is referred to as the document schema. One way to formally define a schema for XML documents is using the W3C standard known as XML Schema [schema].

This document defines the VOResource schema using XML Schema. The full Schema document is listed in Appendix A. Parts of the schema appear within the main sections of this document; however, documentation nodes have been left out for the sake of brevity.

Reference to specific elements and types defined in the VOResource schema include the namespaces prefix, vr, as in vr:Resource (a type defined in the VOResource schema). Reference to specific elements and types defined in the VODataService extension schema include the namespaces prefix, vs, as in vs:DataCollection (a type defined in the VODataService schema). Use of the vs prefix in compliant instance documents is strongly recommended, particularly in the applications that involve IVOA Registries (see [RI], section 3.1.2). Elsewhere, the use is not required.

Contents

• Abstract
• Status of this document
• Acknowledgments
• Conformance-related definitions
• Syntax Notation Using XML Schema
• 1. Introduction
• 2. The VOResource Data Model
  • 2.1. The Schema Namespace and Location
  • 2.2. Summary of Metadata Concepts
• 3. The VODataService Metadata
  • 3.1. Resource Type Extensions
  • 3.2. Coverage
  • 3.3. Tabular Data
  • 3.4. Interface Type Extension: ParamHTTP
• Appendix A: the VODataService XML Schema
• Appendix B: Compatibility Issues with VODataService 1.0
• Appendix C: Change History
• References

1. Introduction

The VOResource standard [VOR] provides a means of encoding IVOA Resource Metadata [RM] in XML. VOResource uses XML Schema [schema] define most of the XML syntax rules (while a few of the syntax rules are outside the scope of Schema). VOResource also describes mechanisms for creating extensions to the core VOResource metadata. This allows for the standardization of new metadata for describing specialized kinds of resources in piecemeal way without deprecating the core schema or other extensions. This document defines one such extension referred to as VODataService.

The purpose of this extension is to define common XML Schema types--particularly new resource types--that are useful for describing data collections and services that access data. In particular, it allows one to describe the data's coverage: the parts of the sky the data is associated with and the time and frequency ranges that were observed or modeled to create the data. It also allows one to describe tables in detail. In particular, one can describe each of the columns of a table--providing, for example, its name, type, UCD, and textual description. When this metadata is part of a resource description in a registry [VOR], it becomes possible to discover tables that contains particular kinds of data.

It is intended that VODataService will be central to describing services that support standard IVOA data access layer protocols such as Simple Image Access [SIA] and Simple Cone Search [SCS]. While other VOResource extensions would define the protocol-specific metadata (encapsulated as a standard capability [VOR]), the general service resource description would share the common data concepts such as coverage and tabular data. Note, however, that a service described using the VODataService schema need not support any standard protocols. With the VODataService extension schema plus the core VOResource schema, it is possible to describe a custom service interface that accesses data.

As a legal extension of VOResource [VOR], the use of VODataService is subject to the rules and recommendations for XML [xml], XML Schema [schema], and VOResource itself.

The VODataService extension in general enables the description of two types of resources: data collections and services that access data. Here's an example of a VOResource document (abbreviated for the purposes of illustration) that describes a service from the NASA Extragalactic Database (NED) that provides measured redshifts for a given object.

2 



1
1
1

3
3
3
3
3
3

4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4

4
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
4

6
6
6
6
6
6
6
6
6

6
6
6

7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7
7

<?xml version="1.0" encoding="UTF-8"?>
<ri:Resource xmlns="" 
             xsi:type="vs:CatalogService" status="active" 
             updated="2008-04-29T14:51:54Z" created="2005-10-14T01:46:00Z"
             xmlns:ri="http://www.ivoa.net/xml/RegistryInterface/v1.0" 
             xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0" 
             xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1" 
             xmlns:stc="http://www.ivoa.net/xml/STC/stc-v1.30.xsd" 
             xmlns:xlink="http://www.w3.org/1999/xlink" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0
                                 http://www.ivoa.net/xml/VOResource/v1.0
                                 http://www.ivoa.net/xml/VODataService/v1.1
                                 http://www.ivoa.net/xml/VODataService/v1.1
                                 http://www.ivoa.net/xml/STC/stc-v1.30.xsd
                                 http://www.ivoa.net/xml/STC/stc-v1.30.xsd">

  <title>The NASA/IPAC Extragalactic Database</title>
  <shortName>NED_redshift</shortName>
  <identifier>ivo://ned.ipac/Redshift_By_Object_Name</identifier>
  <curation>
    <publisher>The NASA/IPAC Extragalactic Database</publisher>
    <contact>
      <name>Olga Pevunova</name>
      <email>contact@datacenter.edu</email>
    </contact>
  </curation>
  <content>
    <subject>redshift</subject>
    <subject>galaxies</subject>
    <description>
      NED is built around a master list of extragalactic objects for
      which cross-identifications of names have been established,
      accurate positions and redshifts entered to the extent possible,
      and some basic data collected. This service will return recorded 
      redshifts for a given object.
    </description>
    <referenceURL>http://nedwww.ipac.caltech.edu/help/data_help.html#zdat</referenceURL>
    <type>BasicData</type>
    <contentLevel>Research</contentLevel>
  </content>

  <capability>
    <interface xsi:type="vs:ParamHTTP">
      <accessURL use="base">
         http://nedwww.ipac.caltech.edu/cgi-bin/nph-datasearch?search_type=Redshifts&
      </accessURL>
      <queryType>GET</queryType>
      <resultType>application/xml+votable</resultType>
      <param use="required">
        <name>objname</name>
        <description>Name of object</description>
        <dataType>string</dataType>
      </param>
      <param use="required">
        <name>of</name>
        <description>Output format parameter, must be "xml_main" for VOTable output.</description>
        <dataType>string</dataType>
      </param>
    </interface>
  </capability>

  <coverage>
    <stc:STCResourceProfile>
       <stc:AstroCoordSystem xlink:type="simple"
                             xlink:href="ivo://STClib/CoordSys#UTC-FK5-TOPO" 
                             id="UTC-FK5-TOPO"/> 
       <stc:AstroCoordArea coord_system_id="UTC-FK5-TOPO">
          <stc:AllSky/>
       </stc:AstroCoordArea>
    </stc:STCResourceProfile>
    
    <waveband>Radio</waveband>
    <waveband>Optical</waveband>
  </coverage>

  <tableset>
    <schema>
      <name>default</name>
      <table role="out">
        <qualifiedName>default</qualifiedName>
        <column>
          <name>No.</name>
          <description>
             A sequential data-point number applicable to this list only.
          </description>
          <ucd>meta.number</ucd>
          <dataType>int</dataType>
        </column>
        <column>
          <name>Name in Publication</name>
          <description>
             The object's name in NED's standard format, of the object to which the data apply.
          </description>
          <ucd>meta.id;name</ucd>
          <dataType>string</dataType>
        </column>
        <column>
          <name>Published Velocity</name>
          <description>
            The radial velocity , derived from derived from the shift of some spectral feature, in km/sec
          </description>
          <unit>km/sec</unit>
          <ucd>src.spect.dopplerVeloc</ucd>
          <dataType>int</dataType>
        </column>
      </table>
    <schema>
  </tableset>
</ri:Resource>

1. the extra namespaces associated with VODataService metadata; if STC coverage information is not included, then only the VODataService namespaced is needed.
2. the specific type of resource indicated by the value of the xsi:type attribute; in this case vs:CatalogService indicates that this is describing a service that accesses tabular data.
3. the location of the VOResource-related schema documents used by this description,
4. the core VOResource metadata,
5. an interface described by the VODataService interface type, vs:ParamHTTP; this type can indicate input arguments it supports.
6. a description of the coverage, including an STC description plus waveband keywords.
7. a description of the table that is returned by the service.

2.1. The Schema Namespace and Location

The namespace associated with VODataService extensions is "http://www.ivoa.net/xml/VODataService/v1.1". Just like the namespace URI for the VOResource schema, the VODataService namespace URI can be interpreted as a URL. Resolving it will return the XML Schema document (given in Appendix A) that defines the VODataService schema.

Authors of VOResource instance documents may choose to provide a location for the VOResource XML Schema document and its extensions using the xsi:schemaLocation attribute. While the choice of the location value is the choice of the author, this specification recommends using the VODataService namespace URI as its location URL (as illustrated in the example above), as in,

xsi:schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1
                    http://www.ivoa.net/xml/VODataService/v1.1"

Note: The IVOA Registry Interface standard [RI] actually requires that the VOResource records it shares with other registries provide location URLs via xsi:schemaLocation for the VOResource schema and all legal extension schemas that are used in the records. This rule would apply to the VODataService schema.

The prefix, vs, is used by convention as the prefix defined for the VODataService schema; however, instance documents may use any prefix of the author's choosing. In applications where common use of prefixes is recommended (such as with the Registry Interface specification [RI]), use of the vs prefix is recommended. Note also that in this document, the vr prefix is used to label, as shorthand, a type or element name that is defined in the VOResource schema, as in vr:Resource.

Note: One reason one may not be able to use vs to represent the VODataService schema, version 1.1, is because it is already in defined to represent VODataService v1.0 and cannot be overridden. At this writing, there are no IVOA applications in which this is the case. Consult Appendix B for more details on compatibility issues.

As recommend by the VOResource standard [VOR], the VODataService schema sets elementFormDefault="unqualified". This means that it is not necessary to qualify element names defined in this schema with a namespace prefix (as there are no global elements defined). The only place it is usually needed is as a qualifier to a VODataService type name given as the value of an xsi:type attribute.

The VODataService extension defines four new types of resources. Two inherit directly from vr:Resource:

vs:DataCollection

This resource declares the existence of a collection of data, what it represents, and how to get it. The access to the data may be limited to access a human-readable web page (given by content/referenceURL); however, if the constituents of the collection are available statically via a URL (e.g. an FTP URL to a directory containing all the files), that URL can be provided. It can also provide pointers to other IVOA registered services that can be used to access the data.

vs:StandardSTC

This resource type declares one or more coordinate systems describe using STC [STC] such that each can be assigned a globally unique identifier (based on the IVOA identifier for the resource record itself). This identifier can then be referenced in any other STC description in lieu of a fully described coordinate system. Coordinate system described in this way become reusable standards once they are registered in an IVOA registry.

The other two resource types represent specialized services:

vs:DataService

Inheriting from vr:Service, this type is for services that access astronomical data. It adds the ability to describe the data's coverage of the sky, frequency, and time.

vs:CatalogService

Inheriting from vs:DataService, this type specifically refers to a service that accesses tabular data. In addition to the coverage information, this type adds the ability to describe the tables and their columns. This is intended for describing services that support the "simple" IVOA data access layer protocols such as Simple Image Access [SIA] and Simple Cone Search [SCS].

Coverage (handled via the vs:Coverage type) has two parts to it. The first allows a full STC profile description (via the imported STC element, <stc:STCResourceProfile>). The second part captures key coverage metadata defined in the IVOA Resource Metadata standard [RM]. The RM-derived coverage elements can be considered summarizing metadata for many of the details that may appear within the STC description, and enables simpler searching of high-level coverage information.

The detailed STC profile contained within the <stc:STCResourceProfile> element is capable of describing coverage not only in space, time, and frequency but also velocity and redshift. The profile contains up to three types of component descriptions ([STC], section 4.1): coordinate systems, coordinate values, and coordinate areas or ranges. The first component describes the coordinate systems that coordinate values, areas, and regions are referenced to. While any arbitrary system can be described in this first part, it is expected that most VODataService instances will provide a simple pointer to a predefined system in a registered vs:StandardSTC record (using the mechanism summarized in section 3.1.2 below). The coordinate values part will usually be used to describe the coordinate resolution, errors, or typical sizes. The coordinate areas part describes the actual coverage over any of the coordinates.

Table descriptions appear in one or more vs:tableset elements in which a table set represents a set of logically related tables. There is no assumption a table set has any relationship to an underlying database catalogs or schemas (as defined in [SQLGuide]); in some cases, such as when describing the table that is returned from an SIA service, these terms may have no relevance.

For each table in a table set, one can describe each of the columns, providing such information as its name, type, UCD [UCD], units, and a textual description. Providing this information makes it possible to select a resource based on the kind data contained in its tables.

Finally, the VODataService defines specialized interface type (inheriting from vr:Interface) called vs:ParamHTTP. This interface is used to describe an interface that is invoked over HTTP as either a GET or a POST [HTTP] in which the arguments are encoded as name=value pairs. In addition to the access URL, it can include not only the mime-type of the returned response, it can also enumerate the input arguments that are supported by the service implementation. Much like table columns, one can indicate for each argument the name, the UCD, the data type, the units, whether it is required, and a textual description the argument. Note that this does not capture any interdependencies between arguments. For example, it cannot indicate if one argument only makes sense in the presence of another argument.

This section enumerates the types and elements defined in the VODataService extension schema and describes their meaning. Where a term matches a term in the RM, its meaning is given in terms of the RM definition.

A data collection, which is describable with the vs:DataCollection resource type, is a logical group of data which, in general, is composed of one or more accessible datasets. A collection can contain any combination of images, spectra, catalogs, time-series, or other data. (In contrast, we talk about a dataset as being a collection of digitally-encoded data that is normally accessible as a single unit, e.g. a file.)

The vs:DataCollection type adds seven additional metadata elements beyond the core VOResource metadata [VO].

<xs:complexType name="DataCollection">
   <xs:complexContent>
      <xs:extension base="vr:Resource">
         <xs:sequence>

           <xs:element name="facility" type="vr:ResourceName" 
                       minOccurs="0" maxOccurs="unbounded"/>
           <xs:element name="instrument" type="vr:ResourceName" 
                       minOccurs="0" maxOccurs="unbounded"/>
           <xs:element name="rights" type="vr:Rights" 
                       minOccurs="0" maxOccurs="unbounded"/>
           <xs:element name="format" type="vs:Format" 
                       minOccurs="0" maxOccurs="unbounded"/>
           <xs:element name="coverage" type="vs:Coverage" minOccurs="0"/>
           <xs:element name="tableset" type="vs:TableSet" minOccurs="0"/>
           <xs:element name="accessURL" type="vr:AccessURL" minOccurs="0"/>

         </xs:sequence>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

All of the child elements except <tableset> derive from RM terms. Four of the elements are reuses of elements defined in the core VOResource schema: <facility> and <instrument> are also children of the vr:Organisation resource type, and <rights> and <accessURL> are used in describing generic services. The element definitions here in vs:DataCollection are identical in syntax that in the VOResource schema, and their meaning differs only in that describe the origins the data in the data collection.

vs:DataCollection Extension Metadata Elements
Element	Definition
facility	RM Name: Facility Value type: string with optional ID attribute: vr:ResourceName Semantic Meaning: the observatory or facility used to collect the data contained or managed by this resource. Occurrences: optional; multiple occurrences allowed
instrument	RM Name: Instrument Value type: string with optional ID attribute: vr:ResourceName Semantic Meaning: the instrument used to collect the data contained or managed by this resource. Occurrences: optional; multiple occurrences allowed
rights	RM Name: Rights Value type: string, controlled vocabulary: xs:token Semantic Meaning: Information about rights held in and over the resource. Occurrences: optional; multiple occurrences allowed Allowed Values: public unrestricted, public access is allowed without authentication. secure authenticated, public access is allowed. proprietary only proprietary access is allowed with authentication.
format	RM Name: Format Value type: string with optional isMIMEType attribute, vs:Format Semantic Meaning: The physical or digital manifestation of the information supported by a resource. Occurrences: optional; multiple occurrences allowed Comments: MIME types should be used for network-retrievable, digital data. Non-MIME type values are used for media that cannot be retrieved over the network--e.g. CDROM, poster, slides, video cassette, etc.
coverage	RM Name: Coverage Value type: composite; vs:Coverage Semantic Meaning: Extent of the content of the resource over space, time, and frequency. Occurrences: optional
tableset	Value type: composite; vs:TableSet Semantic Meaning: A description of a set of logically related tables. Occurrences: optional; multiple occurrences allowed
accessURL	RM Name: Service.AccessURL Value type: URL with optional use attribute: vr:AccessURL Semantic Meaning: The URL can be used to download the data contained in this data collection. Occurrences: required; multiple occurrences allowed.

The vs:StandardSTC resource type is used to register standard coordinate systems, positions, or regions using the Space-Time Coordinate (STC, [STC]) standard schema so that they can by uniquely referenced by name by other resource descriptions or applications. This resource type extends the core metadata with a single element, <stcDefinitions>, which contains the STC definitions.

<xs:complexType name="StandardSTC">
   <xs:complexContent>
      <xs:extension base="vr:Resource">
         <xs:sequence>
            <xs:element name="stcDefinitions"
                        type="stc:STCResourceProfile"
                        minOccurs="0" maxOccurs="unbounded"/>
         </xs:sequence>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

The curation metadata that is part of the core VODataService should generally refer to the publishing organization and persons that are responsible for defining the systems, updating the definitions as needed, and responding to user questions about the definitions. The content metadata, in particular the textual contents of the <description> element, should describe the purpose of the definition where references to the defined systems, positions, or regions may be used.

vs:StandardSTC Extension Metadata Elements
Element	Definition
stcDefintions	Value type: composite; stc:stcDescriptionType Semantic Meaning: the definitions of systems, positions, and regions that are available for referencing. Occurrences: required; multiple occurrences allowed Comments: Each system, position, and region description should have an XML ID assigned to it.

The content of the <stcDefinitions> element is controlled by the STC schema. Because that schema uses the elementFormDefault="true" and most of the STC elements are defined to be global [schema], <stcDefinitions> child elements must be qualified as being in the STC namespace (http://www.ivoa.net/xml/STC/stc-v1.30.xsd), by either setting the default namespace (via the xmlns attribute) or via explicit qualification via a prefix (see example).

The vs:DataService resource type is for describing a service that provides access to astronomical data. This service adds to the core VOResource service metadata the ability to associate an observing facility and/or instrument with the data as well as describe the coordinate coverage of data via its child <coverage> element. Note that while these elements are all optional, resource of this type still implies access to astronomical data.

<xs:complexType name="DataService">
   <xs:complexContent>
      <xs:extension base="vr:Service">
         <xs:sequence>
           <xs:element name="facility" type="vr:ResourceName" 
                       minOccurs="0" maxOccurs="unbounded"/>
           <xs:element name="instrument" type="vr:ResourceName" 
                       minOccurs="0" maxOccurs="unbounded"/>
           <xs:element name="coverage" type="vs:Coverage" minOccurs="0"/>
         </xs:sequence>
      </xs:extension>
   </xs:complexContent>
</xs:complexType>

The use and meaning of the <facility> and <instrument> elements are the same as for vs:DataCollection.

vs:DataCollection Extension Metadata Elements
Element	Definition
facility	RM Name: Facility Value type: string with optional ID attribute: vr:ResourceName Semantic Meaning: the observatory or facility used to collect the data contained or managed by this resource. Occurrences: optional; multiple occurrences allowed
instrument	RM Name: Instrument Value type: string with optional ID attribute: vr:ResourceName Semantic Meaning: the instrument used to collect the data contained or managed by this resource. Occurrences: optional; multiple occurrences allowed
coverage	RM Name: Coverage Value type: composite; vs:Coverage Semantic Meaning: Extent of the content of the resource over space, time, and frequency. Occurrences: optional

The contents of the <coverage> element is detailed in section 3.2.

References

[RFC 2119]

Bradner, S. 1997. Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, http://www.ietf.org/rfc/rfc2119.txt

[RM]

Hanisch, Robert (ed.) 2004. Resource Metadata for the Virtual Observatory, Version 1.01, IVOA Recommendation, http://www.ivoa.net/Documents/REC/ResMetadata/RM-20040426.htm

[xml]

Bray, Tim, Paoli, Jean, Sperberg-McQueen, C. M., Maler, Eve, Yergeau, Francois (editors) 2004, Extensible Markup Language (XML) 1.0 (Third Edition), W3C Recommendation 04 February 2004, http://www.w3.org/TR/REC-xml

[schema]

Fallside, David C., Walmsley, Priscilla (editors) 2004, XML Schema Part 0: Primer Second Edition, W3C Recommendation 28 October 2004, http://www.w3.org/TR/xmlschema-0/

[VOR]

Plante, Raymond, Benson, Kevin, Graham, Matthew, Greene, Gretchen, Harrison, Paul, Lemson, Gerard, Linde, Tony, Rixon, Guy, Stébé, Aurélien 2008, VOResource: an XML Encoding Schema for Resource Metadata, v1.03, IVOA Recommendation, http://www.ivoa.net/Documents/REC/ReR/VOResource-20080222.html

[SIA]

Tody, Doug and Plante, Ray 1997, Simple Image Access Specification Version 1.0, IVOA Working Draft, http://www.ivoa.net/Documents/WD/SIA/sia-20040524.html.

[RI]

Benson, Kevin, Plante, Ray, Auden, Elizabeth, Graham, Matthew, Greene, Gretchen, Hill, Martin, Linde, Tony, Morris, Dave, O'Mullane, Wil, Rixon, Guy, Andrews, Kona 2008, IVOA Registry Interfaces, v1.02, IVOA Recommendation, http://www.ivoa.net/Documents/latest/ResourceInterface.html

[STC]

Rots, Arnold, Space-Time Coordinate Metadata for the Virtual Observatory, v1.33, IVOA Recommendation, href="http://www.ivoa.net/Documents/REC/STC/STC-20071030.html">

[SQLGuide]

Date, C.J. and Darwin, Hugh 1997, A Guide to the SQL Standard, Fourth Edition, (Addison-Wesley, Longman Inc.: Reading), p 24.