VODataService: A VOResource Schema Extension for Describing Collections and Services

Official bibliographic entry for published version [VODataService1.2].

Status:

VODataService 1.3 WD 2024-11-13

Acknowledgments

Versions 1.0 and 1.1 of this document have 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), from the European Commission’s (EC) Sixth Framework Programme via the Optical Infrared Coordination Network (OPTICON), and from EC’s Seventh Framework Programme via its eInfrastructure Science Repositories initiative.

Version 1.2 of this document was developed in part with support from the German federal ministry for research and education’s e-inf-astro project (BMBF FKZ 05A17VH2).

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 RFC2119 [].

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.

Syntax Notation Using XML Schema

The eXtensible Markup Language, or XML, is a document syntax for marking textual information with named tags and is defined by . 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 [].

The XML Schemas of VODataService as well as VOResource and its other extensions are available from the IVOA schema repository [1] at any time. Parts of the schema appear within the main sections of this document; however, documentation nodes have been left out for the sake of brevity. Where the content of the pieces of schema embedded in this text diverges from the schema document in the IVOA document repository, the version in the schema repository is authoritative.

References to specific elements and types defined in the VOResource schema include the namespace prefix as in (a type defined in the VOResource schema).

1 Introduction

The VOResource standard [VOResource1.1] provides a means of encoding resource metadata as defined by DataCite [] and the VO-specific IVOA Resource Metadata [RM1.1] in XML. VOResource uses XML Schema [] to 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 a modular way without deprecating the core schema or other extensions.

This document defines one such extension referred to as VODataService. It provides types to define data services, their underlying tabular structures, their service interfaces, and the location of the data served in space, time, and energy.

The remainder of the document introduces the use cases addressed by this specification, then provides a high-level overview over the concepts and usage patterns in sect. 2 The VODataService Data Model and finally discusses the concrete classes in sect. 3 The VODataService Metadata.

1.1 The Role in the IVOA Architecture

Fig. VODataService:fig:archdiag shows the role VODataService plays within the IVOA Architecture [IVOAArchitecture2.0].

VODataService directly depends on the following other VO standards (unless specified otherwise, the dependency is on the major version of the cited standard rather than on the exact version):

VOResource, v1.1 [VOResource1.1]

VOResource gives the fundamental types and structures extended here.

STC, v1.33 [STC1.3]

The deprecated mechanism for declaring coverage through STCResourceProfile still uses concepts from version 1 of the IVOA data model for Space-Time Coordinates. The updated mechanism has no such dependence any more.

VODataService is closely related to the following other VO standards:

VOSI, v1.1 [VOSI1.1]

VODataService defines the schema for the responses on the table metadata endpoint. It also defines the ParamHTTP interface type currently used in the capabilities of most standard protocols.

RegTAP, v1.1 [RegTAP1.1]

RegTAP maps the concepts defined here into a relational structure. In that sense it is the user interface to what is specified here. RegTAP will need an update to support the space-time constraints added here.

MOC, v2.0 [MOC1.1]

Multi-Order coverage maps are used by VODataService to communicate spatial coverage.

1.2 Purpose

The purpose of this extension is to define common XML Schema types – in particular new resource types – that are useful for describing data collections and services that access data. One aspect of such a description is the resource’s coverage: the parts of the sky with which the data is associated and the time and frequency ranges that were observed or modeled to create the data. Another important aspect is the detailed metadata for tables underlying the resource, including names, types, UCDs [UCD1+1.5], units, and textual descriptions for the columns making them up.

Resource records using VODataService types are commonly used to register services that support standard IVOA data access layer protocols such as Simple Image Access [SIA2.0] and Simple Cone Search ref. As of October 2018, there are more than 20000 resources of type in the VO Registry.

While other VOResource extensions define the protocol-specific metadata (encapsulated as a standard capability from VOResource), the general service resource description shares 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, the use of VODataService is subject to the rules and recommendations for XML [], XML Schema [], and VOResource itself.

1.3 Additional Use Cases for Version 1.2

In the following, we collect use cases that guided the development of VODataService to its version 1.2. We do not formally derive requirements from them but briefly note which new features enable or facilitate the specific use case.

A few of the changes in version 1.2 are necessary for consistency with other standards such as TAP (extendedType interpretation, requirement to use ADQL delimited identifier literals in names where appropriate) or VOTable (arraysize interpretation). These were obviously not guided by specific use cases.

What services have data for the Crab nebula covering the H\(\boldsymbol\alpha\) line taken in the second half of 2015?

In version 1.1, this use case would have been covered by the type, which, however, was never properly standardised or widely adopted. In the current version, the , , and children of enable discovery by coverage on the various axes. It is worth noting that the spectral coverage is for the solar system barycenter, so this use case does not immediately enable the discovery of, say, H\(\alpha\) images of remote galaxies. Redshift correction has to be applied by the client based on knowledge about the object(s) investigated. At the time of writing, coverage also does not directly address non-celestial reference systems, although in particular planetary surfaces are considered in scope, and the coverage element’s attribute is defined to ensure non-ICRS coverages can safely be declared as the need arises.

Find all ObsCore services publishing data taken at the Telescope X.

This use case could be satisfied in version 1.1 through the use of records and relationships to the respective TAP services. However, this scheme led to error-prone query patterns, and few such data collections were actually registered; see the IVOA Note on discovering data collections [discovercollections1.1] for details. To better support the scheme proposed there, version 1.2 adds the and types that identify a resource as data-like but permits the addition of various capabilities to the record (which did not). An analogous use case would be “Find all TAP services publishing tables from Gaia DR2”.

Find a large-scale survey of sources between 20 and 40 GHz.

While the spectral constraint is easily satisfied by the new coverage children, the “large-scale” part is much harder to operationalize. However, the plain table size often is a useful proxy in such discovery problems. The new child of communicates it.

1.4 Additional Use Case for Version 1.3

Find services serving time series.

In the previous registry model, searches for a certain kind of data product were linked to searches for certain kinds of services. For instance, clients looking for spectra were querying the registry for SSAP services. This model was severely outdated after ObsTAP services offered – say – spectra, too. Also SSAP services increasingly served time series as well. Thus, when the IVOA product type vocabulary [2] became available, its adoption by VODataService was natural. It is now used to let data collections and services explicitly declare which sort of data they contain or serve.

1.5 Additional Use Cases for Future Versions

The following use cases were originally envisioned for VODataService 1.2, but were postponed because building multiply implemented solutions for them seemed likely to unnecessarily delay the standardisation of, in particular, the STC part of the present document. They will likely be addressed by future versions of VODataService.

Find a resource that has sources in M51 down to 27 mag in V.

The constraint about finding a resource that has V magnitudes for M51 is expressible using spatial coverage and the column’s UCDs. To express something like “down to \(27^{\rm m}\)” one would at least need VOTable-style children for columns; however, metadata sufficient to address the next use case would certainly be sufficient here as well.

Plan a cross-service query.

Systems like OGSA-DAI [] perform orchestration of SQL-like queries between multiple services automatically, in particular cross-service JOINs. In order to work efficiently, such services need column statistics like histograms and the percentage of NULL values.

Facilitate discovery of full DALI services.

The issue here is that DALI forsees synchronous and asynchronous endpoints as the standard case for many protocols – it already is standard for TAP. Also, several auxiliary endpoints (mostly defined in VOSI) are declared as separate capabilities and need to be matched with the functional endpoints. This matching is becoming a problem when multiple authentication schemes or mirror sites necessitate multiple sync/async pairs. A longer treatment of this problem has been published while this document was in WD [], but at the time of writing the process of finding consensus has just begun, so again a normative solution has to be deferred to a later version of this standard.

2 The VODataService Data Model

The VODataService extension in general enables the description of two types of resources: Services that access data on the one side, and data being accessed through services on the other.

For simple services just publishing a simple resource – still a fairly common pattern – the metadata of the data published can be folded into the service record. Here is an example of such a record (abbreviated for the purposes of illustration) that describes a service from the NASA Extragalactic Database (NED) that provides measured redshifts for a given object.

<ri:Resource xsi:type="vs:CatalogService" status="active"
             updated="2018-10-25T12:22:25" created="2005-10-14T01:46:00"
             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: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">

  <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&amp;
      </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>
    <spatial>0/0-11</spatial>
    <!-- arbitrary upper temporal limit for "ongoing acquisition" -->
    <temporal>33282 100000</temporal>
    <!-- Only radio and optical redshifts, here -->
    <spectral>4e-28 3e-23</spectral>
    <spectral>2.4e-19 5e-19</spectral>
    <waveband>Radio</waveband>
    <waveband>Optical</waveband>
  </coverage>

  <tableset>
    <schema>
      <name>default</name>
      <table type="output">
        <name>default</name>
        <column>
          <name>No.</name>
          <description>
             A sequential data-point number applicable to this list only.
          </description>
          <ucd>meta.number</ucd>
          <dataType xsi:type="vs:VOTableType">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</ucd>
          <dataType xsi:type="vs:VOTableType" arraysize="*">char</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>spect.dopplerVeloc</ucd>
          <dataType xsi:type="vs:VOTableType">int</dataType>
        </column>
      </table>
    </schema>
  </tableset>
</ri:Resource>

This example illustrates some of the features of the VODataService extension:

1. The specific type of resource indicated by the value of the attribute; in this case indicates that this is describing a service that accesses tabular data (line 1).

2. The extra namespace declaration for VODataService metadata with the canonical prefix (line 5).

3. The location of the VOResource-related schema documents used by this description (line 7ff.)

4. The core VOResource metadata (line 12ff.)

5. An interface described by the VODataService type ; this type can indicate input arguments the service supports (line 40ff.)

6. A description of the coverage, including quantitative coverage plus waveband keywords (line 62ff.)

7. A description of the table that is returned by the service (line 73ff.)

2.1 The Schema Namespace and Location

The namespace associated with VODataService extensions is

\[\mbox{\texttt{http://www.ivoa.net/xml/VODataService/v1.1}}.\]

As required by the IVOA schema versioning policies [XMLVers1.0], this namespace is identical to the one associated with version 1.1 of this document. It is regrettable that a misleading minor version is present in the namespace URI, but dropping it would break existing software for creating and processing VODataService instance documents. Hence, the namespace URI ending in 1.1 is also used for schema versions 1.2, 1.3, and so forth.

Resolving the VODataService namespace URI will redirect to a schema document having the actual version number (for the schema associated with this document version, this will end in VODataService-1.3.xsd). Following the schema versioning policies, the minor version will be declared in the attribute of this file’s root element. This information should not in general be used in production software; all versions with the above schema URI are compatible with each other in the sense defined in the IVOA schema versioning policies.

Authors of VOResource instance documents may choose to provide a location for the VOResource XML Schema document and its extensions using the attribute. While authors are free to choose a location (as long as it resolves to the schema document), 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"

The canonical prefix for VODataService is ; this means, in particular, that in non-XML contexts (e.g., relational mappings like RegTAP) the VODataService types must be qualified with vs:.

As recommended by the VOResource standard, the VODataService schema sets to unqualified. This means that element names defined in this schema may not be used with a namespace prefix. The only place the namespace prefix must be used is the type names given as the value of an attribute.

2.2 Summary of Metadata Concepts

VODataService defines several resource types and some auxiliary classes necessary to describe resources of these new types.

2.2.1 Auxiliary Classes

The VODataService type allows the declaration of the physical coverage of a resource on the sky (or on spherical bodies), in time, and in the energy of the messenger particle. In addition, the element should contain a rough indication of the messenger type (e.g., “Optical”), and it can contain a link to a footprint endpoint and an indication of the spatial resolution within a service.

VODataService has several classes for the declaration of the tabular structure underlying a service; this can be the tables in a TAP-accessible resource, or it can relate to the data structure returned by the service. This metadata is held in -typed elements consisting of one or more (possibly anonymous) instances. These have some very basic metadata (name, title, description, utype) and otherwise contain instances. These in turn have simple metadata, but mainly give column metadata (including UCDs and units) in -typed children. These are the basis for enabling discovery queries like “find all resources having redshifts and far infrared fluxes”.

Note that table and schema metadata is deliberately shallow. If the main resource metadata is not enough to discover the table – as is fairly typical when a TAP service contains multiple unrelated tables –, data providers should define separate records for them as described in sect. 2.2.3 Discovering Data Within Other Services.

VODataService further defines a specialized interface type called . It inherits from . This type is used to describe straightforward HTTP interfaces directly operating on arguments encoded as name=value pairs. Such interface declarations can enumerate a service’s input arguments, which enables clients to generate simple user interfaces from VOSI capabilities responses.

To be able to express the types of table columns and service arguments alike, VODataService defines several type systems. All of these are basically just enumerations of type names, possibly with some additional metadata like VOTable-style array sizes. In new resource records, only (for ParamHTTP parameters on non-DALI interfaces) and (for table columns) should be used.

2.2.2 VODataService Resource Classes

While no common VO service discovery pattern relies on the XSD type of the resource, [3] resource record authors should nevertheless choose appropriate types for their resources. At the very least, this helps Registry maintenance.

VODataService provides four major resource classes; their derivation tree is shown in Fig. VODataService:fig:rescls. The vertical distinction in that figure reflects whether a resource has an associated tableset (DataX vs. CatalogX); you would typically use the DataX types when a resource does not naturally admit a relational structure. The classical example for this would be a collection of files on an FTP server. CatalogX, on the other hand, has an associated tableset. That does not mean that it is limited to what is conventionally thought of as a “catalogue”, i.e., a table of data on astronomical objects. On the contrary, CatalogX should also be used for collections of images, spectra, time series, etc, as long as their metadata is sufficiently structured. That a data collection is published through the standard IVOA discovery protocols (ObsCore, SIAP, SSAP) certainly is a strong indication that this requirement is satisfied.

The horizontal distinction (XResource vs. XService) is somewhat more subtle and will be discussed in sect. 2.2.3 Discovering Data Within Other Services.

Two further resource classes defined VODataService 1.1, and , are deprecated in version 1.2. Resource record authors are requested to migrate or discard resource records using these deprecated types. If all such records have disappeared from the VO by version 1.4 of this specification, their type declarations may be removed from the schema.

2.2.3 Discovering Data Within Other Services

The content models of CatalogResource and CatalogService are identical. To understand why the two classes are present nevertheless, a short historical excursion is in order. A full treatment of this is found in the IVOA Endorsed Note on discovering data collections within services [discovercollections1.1], hereafter referred to as DDC.

In the early VO, there was almost throughout a \(1:1\) relationship between data collections and services. For instance, a catalogue of variable stars had a single cone search interface, and the spectra from a given spectrograph had a single SSA interface. This is the model reflected by the CatalogService class, and it was, by and large, sufficient for IVOA’s “simple” protocols (SCS, SIAP, SSAP, SLAP), although even these protocols have facilities for multi-collection services.

With the advent of services very naturally publishing what clearly are multiple different resources – TAP, with its multiple tables, and Obscore building on top of it are the prime examples –, this model proved inadequate; furthermore, publishers increasingly offered data through multiple interfaces: An object catalogue now quite typically is published as both a cone search service and within a TAP service; an image collection could have both SIAP and Obscore interfaces.

Thus, the relationship between data collections and services gradually became \(n:m\). With this came the realisation that two classes of discovery need to be supported; for all-VO queries, validation, and the like, an enumeration of all services (“give me all SSAP services…”) needs to be performed. For data discovery (“Where are images from instrument X of object Y?”), a selection over all collections needs to be made.

The solution eventually adopted for these problems is auxiliary capabilities as introduced in DDC. They provide stubs merely identifying an access protocol – at the same time identifying the capability as an auxiliary one – and access URLs, delegating all further service metadata to a separate record, linked to the original resource through an isServedBy relationship.

Thus, CatalogService-typed records should be used

• when a service serves a single data collection, in which case the metadata on the record describes the data collection (e.g., “These are observations of…”).

• for a service serving multiple data collections, in which case the metadata on the record describes the service (e.g., “This is the TAP service of…”’).

CatalogResource-typed records should be used for resources that only have auxiliary capabilities.

Here is a sketch of a resource record of a table within a TAP service:

.. code:: xml

<ri:Resource

xsi:type=”vs:CatalogResource” <title>Sample Table</title> <identifier>ivo://example/sample</identifier> <curation>…</curation> <content> …

<relationship>

<relationshipType>IsServedBy</relationshipType> <relatedResource ivo-id=”ivo://example/tap”

>Example TAP service</relatedResource>

</relationship>

</content> <capability standardID=”ivo://ivoa.net/std/TAP#aux”>

<interface role=”std” xsi:type=”vs:ParamHTTP”>

<accessURL use=”base”

>http://example.org/svcs/tap</accessURL>

</interface>

</capability>

<coverage>…</coverage> <tableset>

<schema>

<name>someschema</name> <table>

<name>someschema.sample</name>… …

</table>

</schema>

</tableset>

</ri:Resource>

A complete example can be found in DDC.

Note that it is legal to add auxiliary capabilities to CatalogService records as well. The classical example could be a cone search service serving a single catalogue that is also queriable within a larger TAP service.

Analogous considerations would apply to DataResource versus DataService, although at this point no obvious use cases have been identified; DataResource was included mainly for symmetry with CatalogResource.

3 The VODataService Metadata

This section enumerates the types and elements defined in the VODataService extension schema and describes their meaning.

3.1 VODataService Resource Types

Sect. 2.2.2 VODataService Resource Classes already gave a general overview of the systematics of the following resource types.

3.1.1 DataResource

The resource type is used to describe a resource containing generic astronomical data without a dominating tabular structure. An example might be a largely unstructured archive of various observations. Resources that have structured metadata tables (like most VO services) or are tabular in nature (like usual astronomical catalogues) should use .

The type is derived from , which means that instances can have capabilities. For , only auxiliary capabilities (e.g., DataServices serving multiple DataResources) or plain capabilities with interfaces should be given. Resources with a primary access mode dedicated to the resource’s data content should use -typed resources.

In addition to ’s content, DataResource adds elements for declaring the observing facilities and/or instruments used to obtain the data, and it supports the declaration of the physical coverage of data via the element.

3.1.2 DataService

The resource type has the same content model as . It should be used instead of when the resource’s capabilities give access to (essentially) only the resource’s data, as for instance “ftp service for the XY instrument”, or for a service giving access to multiple resources; in this latter case, the resource-level metadata should pertain to the service itself rather than any specific data collection served by it.

As with , instances SHOULD declare the metadata of the table(s) underlying the service or delivered by it in a element.

Whenever the service operates on clearly definable tabular data, the resource should use the resource type in preference to , and that tabular structure should be given in a table set.

DataService’s content model is exactly the one of ; please refer to sect. 3.1.1 DataResource for the motivation of this duplication.

3.1.3 CatalogResource

The resource type is used to describe a resource containing astronomical data or metadata in a set of one or more tables. It extends and thus has metadata on coverage as well as the facilities and instruments that produced the resource. Additionally, instances SHOULD declare of the metadata of the table(s) making up the data element.

As with , this type should only be used if all capabilities declared in the resource are either auxiliary or nonstandard. This is typically the case for catalogues or data collections within larger TAP, ObsTAP, or perhaps SIAP services. When a service only publishes a single resource, use the type.

3.1.4 CatalogService

The resource type is used to describe a service publishing astronomical data or metadata based on tabular representations. Its relationship to is as between and : Use when either the resource’s capabilities are exclusive to the resource described by the resource-level metadata (“SSAP service for the XY instrument”) or if the service publishes multiple other CatalogResources; in that latter case, again, the resource-level metadata should not refer to any specific data collection contained.

This is the type that should be used for one-resource VO services.

CatalogService’s content model is exactly the one of ; please refer to sect. 3.1.3 CatalogResource for the motivation of this duplication.

3.1.5 DataCollection

The type is deprecated and should no longer be used in new resource records. It was used in version 1.1 to define simple collections of data, much like in the current version. It did not admit capabilities, though, and since the addition of capabilities would essentially have created a CatalogService clone with a different child sequence, it was decided to abandon rather than repair it.

Existing -typed records should be migrated to records of type or as appropriate. If children are present in the xmlel{vr:WebBrowser}`-typed interface.

This type may be removed from the schema when all resource records using it have vanished from the VO Registry.

3.1.6 StandardSTC

The type is deprecated and should no longer be used in new resource records. Since the XML serialisation of the STC 1 data model was never promoted to an IVOA recommendation, there also is no properly standardised way of creating such records. Since no such records ever existed in the Registry, this type will probably be removed from the schema in version 1.4 of this specification.

3.2 Coverage in Space, Time, and Spectrum

The type summarily describes how the data served is distributed on the sky, in energy, and in time.

In addition, there is the element that originally contained a qualitative indication of the location of the resource’s coverage on the electromagnetic spectrum. As more resources cover non-elec:raw-latex:`-`tromagnetic messengers, the element’s meaning has somewhat shifted, and it now admits values from an extendable vocabulary of messengers [4] that, for instance, includes Neutrinos.

Historically, the quantitative footprints were expected to be given in the element of type [5]. As discussed in , this expectation turned out to be erroneous, and the underlying standard, STC-X [], never proceeded to become a recommendation. Hence, this version of VODataService deprecates the use of .

Instead, resource record authors are strongly encouraged to provide coverage information in the , , and children of .

Spatial coverage is conveyed as a MOC. To enable easy embedding into resource records written in VOResource (i.e., XML), VODataService uses the string serialisation defined in section 2.3.2 of Fernique et al. [MOC1.1].

By default, the MOCs are to be interpreted in the ICRS. Future extensions to non-celestial frames (e.g., on planet surfaces) will use the attribute. However, the only celestial reference system allowed is ICRS. If a resource’s native coordinates are given for another frame (e.g., Galactic or FK4 for some equinox), it is the resource record author’s responsibility to convert the spatial coverage into the ICRS.

An important characteristic of MOCs is the order of the smallest scale (the “MOC resolution”). Higher orders yield more faithful representations of the actual coverage, but also lead to a possibly significant increase of the size of the serialized MOC. We suggest a “typical resolution” of the Registry of about a degree (i.e., MOC order 6), but resources are free to choose a higher maximum orders if appropriate and the resource record size remains reasonable.

Resources that need to communicate high-resolution spatial coverage, perhaps for some non-discovery use case, can use the element with its attribute set to ivo://ivoa.net/std/moc to declare a URL giving a footprint in one of the approved MOC serialisations and of arbitrary level and size.

Time and spectral coverage are modeled as unions of simple intervals over real numbers; the serialisation here is a space-separated pair of floating point numbers as governed by the DALI interval xtype.

Times are given in Barycentric Dynamical Time (TDB) at the solar system barycenter. They must be specified as Modified Julian Dates. Since discovery use cases in which high-precision times are required are not forseen, resource record authors are encouraged to pad their actual temporal coverage such that differences in time scales (of the order of 10s of seconds) or reference positions (of the order of minutes between ground-based observatories and the barycenter) do not matter. In other words, the temporal resolution of the Registry at this point should be assumed to be of order 10 minutes.

Deviating from common VO practice (which currently fairly consistently uses wavelengths of electromagnetic waves in vacuum), spectral limits are given in Joules of messenger energy. This is intended to allow seamless integration of non-elec:raw-latex:`-`tromagnetic messengers. The reference position for the spectral axis is the solar system barycenter. Again, discovery use cases on a level where the difference between reference frames of ground-based observatories versus the solar system barycenter matters are not forseen, and resource record authors are advised to pad their intervals on that level.

In order to avoid future ambiguity in the spatial coverage, we already add a attribute to the element. In its absence, the MOC contained is for ICRS coordinates. Any value indicates non-celestial coordinates, where actual, interoperable values are not defined here.

Coverage declaration makes use of three types, , , and , defined as follows:

3.3 Tabular Data

The type should be used to describe the set of tables that are part of a single resource. While there is no expectation that the table set directly corresponds to the responses of tabular services, services should not include metadata for purely internal tables.

The type groups tables that are logically related. For example, a single resource may provide access to several major astronomical catalogues (e.g., SDSS, 2MASS, and FIRST) from one site, enabling high-performance cross-correlations between them. Each catalogue can be described in a separate element, using the elements from the type.

The order in which elements are given within a tableset is significant. Publishers should put schemas they consider more important or interesting lexically before less salient ones. For TAP services, this order should be consistent with the one implied by TAP_SCHEMA’s schema_index.

Each table in a schema is described in detail using the type. As with , the order of the elements is significant, with more salient tables listed further up within a schema element. For TAP services, this order should be consistent with the one implied by TAP_SCHEMA’s table_index.

Each column in a table can be described using the type which is described in section 3.5 Data Parameters. The foreign keys in the table that can be used to join it with another table can be described with the type (section 3.3.2 Foreign Keys). A foreign key description should only refer to tables described within the current table set.

When the table set describes a set of TAP-accessible tables, the value of a ’s child must be in a form immediately usable for use in ADQL or SQL queries. This corresponds to the analogous requirement for TAP_SCHE:raw-latex:-`MA. This means that all qualifications (schema, catalogue) must be present, but also that when delimited identifiers are used as table names on the relational side, the quotes must be part of :raw-latex:xmlel{name}`’s value, and the capitalisation used in the DDL must be preserved.

The also provides an attribute for indicating the role a table plays in the schema.

3.3.1 Unique Names for Tables

The definitions of the elements used in the and types constrain certain names to be unique. In particular, all schema names within a element must be unique, and all table names within a element must be unique. A schema and table may share a common name, such as “default”. These constraints make it possible to uniquely locate the description of a schema or table within a VOResource description.

3.3.2 Foreign Keys

The type is used to describe foreign keys in a table that allow it to be joined efficiently with another table. A foreign key is a set of columns that map to a corresponding set of columns in another table.

In this model, the source of the foreign key is the current table being described (i.e., represented by the element that contains the description, and thus does not need to be named explicitly). The key that is described points to the table given by the child element. Each child element then gives a pair of columns, one from the source table and one from the target table, that can be constrained to be equal in a query that joins the two tables.

3.3.3 Extending Table Metadata

It is envisioned that it may be useful in the future to provide richer metadata for describing tables within a VOResource description than what are defined in this document. This document recommends the use of the following extension mechanisms when richer descriptions are desired:

1. Use extended types by applying the attribute to the , , , and/or elements. The values provided in the attributes must refer to an XML type legally extended from the types associated with these elements according to the rules of XML Schema [] and the VOResource specification.

2. Apply a globally-defined attribute from a schema other than VODataService (i.e. from a namespace other than http://www.ivoa.net/xml/VODataSer\-vice/v1.1) to any of the , , , and/or elements.

3. When the extended metadata is specific to how the table data is accessed via a particular service protocol, then the new metadata can be incorporated into a specific capability extension (as described in the VOResource specification). This extension may make use of the various names within the to indicate where the extension metadata apply.

4. Use the attribute of the element (see section 3.5.3 Table Column Data Types) to indicate a more specific data type then those defined by the type.

3.4 Interface Type Extension: ParamHTTP

The type is a specialized service interface description that extends the VOResource type (as recommended by VOResource 1.1, section 2.2). It describes a service interface that is invoked over HTTP via a GET or a POST in which the inputs are parameters encoded in multipart/form-data or application/x-www-form-urlencoded containers.

The extension metadata defined in the schema definition above are all optional. Nevertheless, even when an instance does not include any of these extended child elements, the use of xsi:type="vs:ParamHTTP" indicates that the interface accessed via the URL given by the element complies with the general parameter-based protocol described in this section.

An important intended use of the type is describing the interface of an IVOA standard service protocol of the “simple” variety, such as the Simple Image Access Protocol [SIA2.0]. In particular, it is recommended that specifications that define how a standard service is registered in a registry require the use of the interface type when it is applicable.

Normally, a VOResource description indicates its support for a standard protocol with a element having a attribute set to specific URI representing the standard. The standard will usually spell out the HTTP query type, the returned media type, and input parameters required for compliance; therefore, it is not necessary that the description provide any of the optional extended metadata, as they are already implied by the . The description need only reflect the optional or locally unique features of the interface. In particular, description may include

• a element for a type that is not required by the standard (as long as the required query type is supported as well),

• elements for any optional parameters or local extended parameters (when allowed by the standard).

Listing required parameters is allowed, even when describing a standard interface, as long as these are consistent with the service specification and the corresponding elements include the attribute std="true" (see section 3.5.1 Input Parameters). The elements for custom parameters that are not part of the standard (but are rather local customizations) should include the attribute std="false".

3.5 Data Parameters

The VODataService schema provides several element types for describing different kinds of data parameters used in datasets and services, including service input parameters and table columns. The parameter types describe a parameter in terms of elementary metadata including name, data type, and meaning.

All the VODataService parameter types derive from the base type which defines all the common parameter metadata except the data type.

Leaving the data type metadatum out of allows the different kinds of parameters derived from to restrict the allowed data types to specific sets. The subsections below describe the different data types associated with input parameters () and table columns (). The XML types associated with their elements derive from a common parent, .

The content of an element of type is the name of the data type for the current parameter. When the element is explicitly a (as opposed to one of its derived types), there are no restrictions on the names that may be included.

A data type description can be augmented via a common set of attributes. The attribute indicates the parameter is an array of values of the named type. Its value describes the shape of the array. When there is no natural serialisation defined through the type system, the attribute may be used to indicate a delimiter that should appear between elements of an array value. This attribute must not be combined with VOTableDataType, which always uses VOTable serialisation rules.

More descriptive information about the type can be provided via and , which provide an alternate data type name. The name given in the type’s element content, then, represents a commonly understood “fallback” type. For instance, in VOTable, timestamps are serialised into strings, which implies a VOTableType of char with arraysize *, as supported by all VOTable readers. VOTable readers interpreting the timestamp xtype, however, can turn this string into a timestamp value native to its clients. Such readers will interpret a VOTable ’s attribute. Such information is reflected in .

Arbitrary information can also be provided via any prefix-qualified, globally defined attribute drawn from an XML Schema other than VODataService (by virtue of the specification present on ).

Note that in the derived parameter description types described below, the element is optional. Its absence from the parameter description does not mean that the parameter can support any data type; rather, it means that the data type simply has not been provided (which may limit what an application can do with the parameter). If a parameter can truly support any data type, the type can be used directly when the context permits.

3.5.1 Input Parameters

Actual parameters are normally described with types derived from . The is intended for describing an input parameter to a service or function. In previous versions of VODataService, input parameters were restricted to be defined in terms of simple data types, which are intended to be sufficient for describing an input parameter to a simple REST-like service or a function in a weakly-typed language. They are defined in :

Since VODataService 1.2, input parameters can use any type system, where non-DALI-compliant services SHOULD use and DALI-compliant services SHOULD use . To ensure schema validation catches mistakes, resource record authors are advised to declare the type system intended using ; for instance, a service accepting a DALI point might declare:

<param std="true">
    <name>pos</name>
    <description>ICRS position of target object</description>
    <dataType arraysize="2"
      xsi:type="vs:VOTableType"
      extendedType="point">double</dataType>
  </param>

The class then is a furnished with additional metadata defining how to use the parameter and whether or not it is defined in the standard governing the capability the interface is in (if any):

Here is an example for a description of an input parameter that might appear inside an interface description. As noted in section 3.4 Interface Type Extension: ParamHTTP, a element uses the type to describe itself:

<param use="required">
  <name> radius </name>
  <description>
    search radius; returned objects are restricted to fall
    within this angular distance of the search position.
  </description>
  <ucd> phys.angSize </ucd>
  <dataType xsi:type="vs:SimpleDataType"> real </dataType>
</param>

3.5.2 Table Columns

The is also derived from , and is designed for describing a column of a table.

A table column’s data type is indicated with the element with a name drawn from a standard set of names. Because ’s XML type, , is abstract, the element MUST include an attribute. As discussed in sect. 3.5.3 Table Column Data Types, this SHOULD be for VODataService 1.2 table columns.

When the tableset describes a set of TAP-accessible tables, the value of a ’s child must be in a form immediately usable for use in ADQL or SQL queries. This corresponds to the analogous requirement for TAP_SCHE:raw-latex:-`MA and is usually only a problem when delimited identifiers are used for column names on the relational side. In that case, the quotes must be part of :raw-latex:xmlel{name}`’s value, and the capitalisation used in the DDL must be preserved.

As examples, here are declarations of a column called “Dec” containing a double-valued declination, of the (deprecated) size column from TAP 1.0 which requires quotes because it otherwise clashes with a SQL reserved name, and a SIAP 1.0-compatible wcs_cdmatrix column that shows how multidimensional arrays are declared; note that in the last case, the content of pertains to elements of the array, not the array as a whole.

<column>
   <name> Dec </name>
   <description> the J2000 declination of the object </description>
   <ucd> pos.eq.dec </ucd>
   <dataType xsi:type="vs:VOTableType"> double </dataType>
</column>

<column>
  <name>"size"</name>
  <description>Length of variable length datatypes</description>
  <dataType xsi:type="vs:VOTableType">int</dataType>
  <flag>nullable</flag>
</column>

<column>
  <name>wcs_cdmatrix</name>
  <description>World coordinates at WCS reference pixel</description>
  <unit>deg</unit>
  <ucd>VOX:WCS_CoordRefValue</ucd>
  <dataType arraysize="2x2" xsi:type="vs:VOTableType">double</dataType>
  <flag>nullable</flag>
</column>

3.5.3 Table Column Data Types

The VODataService schema defines two type systems that derive from : and . Following the move to VOTable-compatible type descriptions in TAP 1.1 ref, this version of VODataService deprecates the use of . New software should only generate xmlel{tableset}`s.

When the actual column type is not well matched to a VOTable data type, authors are encouraged to use the attribute to refer to a more specific type. This will usually be a VOTable as defined by DALI ref. Using different extended type schemes is possible by setting to a non-empty value; data providers using this extension mechanism should explain their schema in an IVOA Note.

Appendices

A Changes from previous versions

A.1 Changes since REC-1.2

• Adding a child to ; this is intended to replace the previous practice of choosing product types by service types.

• Postponing the drop of StandardSTC and DataCollection to version 1.4.

• Clarifying that the order of schema and table elements in a tableset is significant.

A.2 Changes since PR-20210223

• Numerous editorial changes after RFC comments without impact on the normative content.

• Schema: Minor style fixes (e.g., removing gratuitous maxOccurs) without impact on document validity.

A.3 Changes since PR-20190715

• Sect. 3.1 VODataService Resource Types and schema: dropped vs:Waveband and changed waveband to being controlled by a vocabulary that initially grows a generic Photon and a Neutrino concept over what the previous Waveband had.

• Sect. 3.3 Tabular Data and schema: table/@nrows is now constrained to be non-negative.

• Sect. 3.5.1 Input Parameters and schema: Now allowing any vs:DataType element to define vs:InputParams. In order to still ensure schema validation of type names, now advising to have an explicit xsi:type in param’s dataTypes.

A.4 Changes since WD-20181026

• Sect. 2.2.3 Discovering Data Within Other Services: Added a summary of the discovering data collections EN.

• Sect. 3.2 Coverage in Space, Time, and Spectrum and schema: Spatial coverage now has a frame attribute.

• Sect. 3.1.3 CatalogResource: Added a SHOULD requirement on CatalogResources to have a tableset.

• Sect. 3.4 Interface Type Extension: ParamHTTP and schema: Restricted interface/@testQuery to zero or one occurrences (this is because there is no clear semantics to having multiple of those).

• Sect. 3.2 Coverage in Space, Time, and Spectrum: Sanctioning the use of footprint/@ivo-id to indicate the footprint standard used (which, of course, totally goes against the semantics of ServiceReference underlying footprint).

A.5 Changes since REC-1.1

• Sect. 3.2 Coverage in Space, Time, and Spectrum and schema: Deprecated STCResourceProfile and replaced it with , , and elements.

• Sect. 3.1 VODataService Resource Types and schema: Introduced new DataResource and CatalogResource resource types and wove them into the inheritance hierarchy to CatalogService; these are to be used for “dependent” resources.

• Sect. 3.2 Coverage in Space, Time, and Spectrum: Deprecated DataCollection and StandardSTC (which are no longer needed).

• Sect. 3.3 Tabular Data and schema: Added an nrows element to .

• Sect. 3.3 Tabular Data: Required inclusion of quotes for delimited identifiers in a SQL context.

• Sect. 3.5 Data Parameters and schema: DataType/@arraysize no longer defaults to 1, and the interpretation of arraysize=1 as a scalar is withdrawn. Use empty arraysize for scalars now.

• Sect. 3.5 Data Parameters and schema: DataType’s delim attribute no longer defaults to blank. That would be very unfortunate with VOTable, where other conventions are in place (e.g., for string arrays). Now discouraging the use of delim outside of InputParams.

• Sect. 3.5.3 Table Column Data Types: Deprecated TAPType.

• Sect. 3.5.3 Table Column Data Types: extendedType is now defined to correspond to VOTable xtypes in the absence of extendedSchema.

• Sect. 3.3 Tabular Data: No longer requiring unique table names within a tableset; uniquness is now required within a schema (actually, many services have been in violation of the old unique-within-tableset rule for a long time without operational difficulties); but then that’s largely a moot point because for the main uses of tableset, fully qualified names are now required.

• Ported source to .

A.6 Changes since PR-20100916

• updated status for elevation to Recommendation.

• cleaned-up mis-labeled and mis-ordered change history.

A.7 Changes since PR-20100914

• added change history for PR-20100412.

• added Note about STC mark-up in 3.2 Coverage in Space, Time, and Spectrum

• reworded sentence describing content of in section 3.5 Data Parameters.

A.8 Changes since PR-20100412

• fix numerous typos discovered in TCG review

• added section 1.1 to describe role of standard in the VO architecture, including diagram.

• corrected frequency range for the UV waveband

• corrected links to reference documents

A.9 Changes since PR-20090903

• added to

• in text, added explanation of

• grammatical clean-up

A.10 Changes since WD-20090508 (v1.10)

• corrected errors in example in Introduction

• added and elements to the type for consistency with TAP.

• changed type names to and .

[1]

http://www.ivoa.net/xml

[2]

http://www.g-vo.org/rdf/product-type

[3]

Of course, in non-service discovery (e.g., authorities or standards), resource types are important.

[4]

http://www.ivoa.net/rdf/messenger

[5]

Defined in http://www.ivoa.net/xml/STC/stc-v1.30.xsd