TAPRegExt: a VOResource Schema Extension for Describing TAP Services
Version 1.0

1.1. TAPRegExt within the VO Architecture

Figure 1: IVOA Architecture diagram with TAPRegExt and the related standards marked up.

This specification directly relates to other IVOA standards in the following ways:

VOResource, v1.03 [VOR]

Descriptions of services that support TAP are encoded using the VOResource XML Schema. TAPRegExt is an extension of the VOResource core schema.

TAP, v1.0 [TAP]

The TAP standard describes some of the concepts the declaration of which is the scope of TAPRegExt; the standard indirectly refers to this document in the specification of its capabilities endpoint.

UWS, v1.0 [UWS]

The UWS standard describes additional parameters the choices of are communicated using TAPRegExt.

StandardsRegExt [SRE]

TAPRegExt uses the StandardKeyEnumeration mechanism introduced in StandardsRegExt to define controlled vocabularies.

This standard also relates to other IVOA standards:

IVOA Standard Interface, v1.0 [VOSI]

VOSI describes the standard interfaces to discover metadata about services; this document describes the response TAP services should provide on the capabilities endpoint described by VOSI.

IVOA defined data models

The IVOA defines data models database tables can conform to in order to facilitate cross-service queries. The first example of those is [ObsTAP]. The support for queries against such data models is noted within TAPRegExt instance documents.

2.1. The Schema Namespace and Location

The namespace associated with TAPRegExt VOResource extensions will be http://www.ivoa.net/xml/TAPRegExt/v1.0. Just like the namespace URI for the VOResource schema, the TAPRegExt namespace URI can be interpreted as a URL. Resolving it will return the XML Schema document (given in Appendix A) that defines the TAPRegExt 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 author is free to choose any schema location, this specification recommends using the TAPRegExt namespace URI as its location URL (as illustrated in the example above), as in,

xsi:schemaLocation="http://www.ivoa.net/xml/TAPRegExt/v1.0
                    http://www.ivoa.net/xml/TAPRegExt/v1.0"

2.2. Declaring Instantiated Data Models

In TAPRegExt, a data model is identified by its IVORN. The first example for such a data model is ObsCore (see [OT]).

<xs:complexType name="DataModelType" >
  <xs:simpleContent >
    <xs:extension base="xs:token" >
      <xs:attribute name="ivo-id" type="vr:IdentifierURI" use="required" />
    </extension>
  </simpleContent>
</complexType>

2.3. Languages Supported

The recommended way to associate larger amounts of documentation with a language entry in a capability element is via registration of the language using the mechanisms defined in [SRE] and associating the registry record with the language element through the latter's ivo-id attribute. The only language mandatory for TAP services, ADQL 2.0, has a registry record at ivo://ivoa.net/ADQL/2.0

<xs:complexType name="Language" >
  <xs:sequence >
    <xs:element name="name" type="xs:NCName" />
    <xs:element name="version" type="tr:Version" minOccurs="1"
                maxOccurs="unbounded" />
    <xs:element name="description" type="xs:token" minOccurs="0" />
    <xs:element name="languageFeatures"
                type="tr:LanguageFeatureList"
                minOccurs="0"
                maxOccurs="unbounded" />
  </sequence>
</complexType>

<xs:complexType name="Version" >
  <xs:simpleContent >
    <xs:extension base="xs:token" >
      <xs:attribute name="ivo-id" type="vr:IdentifierURI" />
    </extension>
  </simpleContent>
</complexType>

Query languages may support optional features. For ADQL, the most prominent of those are user-defined functions, i.e. functions not defined in the language standard but added by the operators of the service, and geometry functions. Such optional features may be communicated to the service client by use of one or more tr:languageFeatures elements.

Each such list is labelled with a type attribute indicating the type of language option being described. This string should be an IVORN whose semantics in this context, along with the semantics of the content of its descendant feature/form elements, can be documented in association with the language in question.

TAPRegExt itself defines the following feature types:

ivo://ivoa.net/TAPRegExt#features-udf

Each feature declares a user-defined ADQL (or similar) function supported. The content of the form element must be the signature of the function, written to match the signature nonterminal in the following grammar:

signature ::= <funcname> <arglist> "->" <type_name>
funcname ::= <regular_identifier>
arglist ::= "(" <arg> { "," <arg> } ")"
arg ::= <regular_identifier> <type_name>

The type_name nonterminal is not defined by the ADQL grammar. For the purposes of TAPRegExt, it is sufficient to assume it expands to "some sort of SQL type specifier" (which may include spaces and parentheses).

ivo://ivoa.net/TAPRegExt#features-adqlgeo

Each feature declares support for one of the geometry functions defined by ADQL (support for these functions is in general optional for ADQL implementations, though TAP imposes some constraints on what combinations of support are permitted).

The signature of these functions, where supported, is fixed by ADQL; the content of the form element is just the name of the function.

Example:

<feature>
  <form>CONTAINS</form>
</feature>

We could go on to define what's allowed in a region and the coordinate systems supported. However, I'd hope both features won't become very prominent, and thus I'd rather not talk about them too much. If you disagree, it's not hard to sway me, but at least for REGION I'd need input as to what "form" could be for it. -- MD

<xs:complexType name="LanguageFeatureList" >
  <xs:sequence >
    <xs:element name="feature" type="tr:LanguageFeature" minOccurs="0"
                maxOccurs="unbounded" />
  </sequence>
  <xs:attribute name="type" type="xs:anyURI" use="required" />
</complexType>

<xs:complexType name="LanguageFeature" >
  <xs:sequence >
    <xs:element name="form" type="xs:token" />
    <xs:element name="description" type="xs:string" minOccurs="0" />
  </sequence>
</complexType>

2.4. Output Formats

A TAP service may offer a variety of output formats. What output formats are available is defined using outputFormat elements. They declare a MIME type (see [RFC2045]) as well as aliases (the shorthand forms the server also accepts in the FORMAT parameter). If desired, the format can be further described using an IVORN; at the time of writing, the TAPRegExt provides keys for tabledata encoded and binary encoded VOTables.

<xs:complexType name="OutputFormat" >
  <xs:sequence >
    <xs:element name="mime" type="xs:token" />
    <xs:element name="alias" type="xs:token" minOccurs="0"
                maxOccurs="unbounded" />
  </sequence>
  <xs:attribute name="ivo-id" type="xs:anyURI" />
</complexType>

2.5. Upload Methods

Keys for the standard upload methods are provided within the resource record ivo://ivoa.net/TAPRegExt (while the registry record is not in place, it can be examined in the volute repository). The keys are built by using the keys as fragment identifiers within the TAPRegExt IVORN.

It is permitted to register upload methods under authorities other than ivoa.net. The registry records can then provide more in-depth information. For the upload methods defined in the TAP specification, however, you must use the IVORNs of the keys in the TAPRegExt resource record to enable clients to identify supported methods using string comparisons.

At the time of writing, the set of protocol identifiers includes:

• upload-inline -- HTTP upload as per section 2.5.2 of [TAP].
• upload-http -- retrieval from an http URL.
• upload-https -- retrieval from an https URL.
• upload-ftp -- retrieval from an ftp URL.

Thus, a service offering upload by retrieving from ftp and http URLs would say:

  <uploadMethod ivo-id="ivo://ivoa.net/TAPRegExt#upload-http"/>
  <uploadMethod ivo-id="ivo://ivoa.net/TAPRegExt#upload-ftp"/>

<xs:complexType name="UploadMethod" >
  <xs:complexContent >
    <xs:restriction base="xs:anyType" >
      <xs:attribute name="ivo-id" type="xs:anyURI" />
    </restriction>
  </complexContent>
</complexType>

2.6. Resource Limits

<xs:complexType name="TimeLimits" >
  <xs:sequence >
    <xs:element name="default" type="xs:integer" minOccurs="0" maxOccurs="1" />
    <xs:element name="hard" type="xs:integer" minOccurs="0" maxOccurs="1" />
  </sequence>
</complexType>

Limits on Data

Limits on data work like time limits, including having a default and a hard value, except that both those values have a unit attribute that can either be bytes or rows.

This document defines two resource limits on data:

• outputLimit -- if unit is rows here, the default gives the value of TAP's MAXREC parameter the service will use when none is specified.
• uploadLimit -- the maximum size of uploads. This is not a TAP adjustable parameter. The default value advises clients about the server's wishes as to the limit above which some sort of acknowledgement should be requested from the user. The hard limit gives the maximum size of an upload to the server.

Data limits are defined using the tr:DataLimits and tr:DataLimit types:

<xs:complexType name="DataLimits" >
  <xs:sequence >
    <xs:element name="default" type="tr:DataLimit" minOccurs="0" maxOccurs="1" />
    <xs:element name="hard" type="tr:DataLimit" minOccurs="0" maxOccurs="1" />
  </sequence>
</complexType>

<xs:complexType name="DataLimit" >
  <xs:simpleContent >
    <xs:extension base="xs:integer" >
      <xs:attribute name="unit" use="required" >
        <xs:simpleType >
          <xs:restriction base="xs:token" >
            <xs:enumeration value="bytes" />
            <xs:enumeration value="rows" />
          </restriction>
        </simpleType>
      </attribute>
    </extension>
  </simpleContent>
</complexType>

2.7. The Capability Record

  <capability 
    xmlns:tr="http://www.ivoa.net/xml/TAP/v1.0" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    standardID="ivo://ivoa.net/std/TAP" 
    xsi:type="tr:TableAccess">
    ...

<xs:complexType name="TableAccess" >
  <xs:complexContent >
    <xs:extension base="tr:TAPCapRestriction" >
      <xs:sequence >
        <xs:element name="dataModel" type="tr:DataModelType" minOccurs="0"
                    maxOccurs="unbounded" />
        <xs:element name="language" type="tr:Language" minOccurs="1"
                    maxOccurs="unbounded" />
        <xs:element name="outputFormat" type="tr:OutputFormat" minOccurs="1"
                    maxOccurs="unbounded" />
        <xs:element name="uploadMethod" type="tr:UploadMethod" minOccurs="0"
                    maxOccurs="unbounded" />
        <xs:element name="retentionPeriod" type="tr:TimeLimits" minOccurs="0"
                    maxOccurs="1" />
        <xs:element name="executionDuration" type="tr:TimeLimits" minOccurs="0"
                    maxOccurs="1" />
        <xs:element name="outputLimit" type="tr:DataLimits" minOccurs="0"
                    maxOccurs="1" />
        <xs:element name="uploadLimit" type="tr:DataLimits" minOccurs="0"
                    maxOccurs="1" />
      </sequence>
    </extension>
  </complexContent>
</complexType>