IVOA

Describing Simple Data Access Services
Version 1.0

IVOA Working Draft 22 October 2009

This version:
http://www.ivoa.net/Documents/RegSimpleDAL/20091022/
Latest version:
http://www.ivoa.net/Documents/latest/RegSimpleDAL.html
Previous versions:
none
Authors:
Raymond Plante, Editor

Abstract

An application that queries or consumes descriptions of VO resources must be able to recognize a resource's support for standard IVOA protocols. This specification describes how to describe a services that supports three fundemental data access protocols--Simple Cone Search (SCS), Simple Image Access (SIA), and Simple Spectral Access (SSA)--using the VOResource XML encoding standard. A key part of this specification is the set of VOResource XML extension schemas that define new metadata that are specific to those protocols. This document describes in particular rules for describing such services within the context of IVOA Registries and data discovery as well as the VO Stadard Interface (VOSI) and service self-description. In particular, this document spells out the essential mark-up needed to identify support for a standard protocol and the base URL required to access the interface that supports that protocol.

Status of this document

This is an IVOA Working Draft for review by IVOA members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than "works in progress".

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

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, RFC 2119 [RFC 2119].

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.

Syntax Notation Using XML Schema

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:ParamHTTP (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


1. Introduction

Three data access service protocols play a key role in discovering data in the VO:

They are called "simple" because a typical query can be formed using only a few search parameters encoded into a URL (i.e. an HTTP GET request). Their power for data discovery comes from the ability of an application to form a single query according to the rules of one of these protocols and send it to all known services which support that protocol. The results collected from all those services, in effect then, represent all matching data of that type known to the VO. Thus, the key for an application wishing to do a comprehensive search of the VO is to discover all of the services that support the particular standard protocol.

Service discovery in the VO is done via a searchable registry [RI]--i.e., a searchable repository of descriptions of resources in VO. These descriptions are comprised of common standard metadata [RM] that capture information about what a resource contains or does and who provides it. A standard registry encodes these descriptions using the VOResource XML Schema [VOR]. Service resources in particular include capability metadata that describe the functionality it supports along with interface metadata that describe how to access that functionality. It is within the capability metadata that it is possible to indicate support for a particular standard protocol.

Capability metadata play an important role beyond just identifying support for a standard interface. More generally, they describe how the service behaves, and if applications are to make use of this information in an automated way, the behavior must be described using standardized metadata. In general, the metadata necessary for describing that behavior will be specific the particular kind of service. In the case of a standard protocol, in which it is common that some variation in behavior is allowed while still being in compliance, it can be important to an application to know how a service complies with the standard for two reasons:

  1. The application may wish to search for and select services that support a particular protocol feature. For example, an application may wish to find image services that can create cut-outs on-the-fly.
  2. The application may wish to plan its use of the service according its limitations, such as the maximum region of sky that can be search in one query.

It is important to note that the relevent behavioral differences between separate services that support a common protocol--and thus the metadata used to describe those behaviors--will be specific to that protocol. That is, the ability to create image cut-outs is irrelevent to the Simple Cone Search protocol. Consequently, it is necessary to define protocol-specific metadata to adequately describe a service's support for that protocol. This document defines such capability metadata for SCS, SIA, and SSA.

This document describes, for each of the standard data access protocols SCS, SIA, and SSA, precisely how to describe a service that supports one of the protocol using the VOResource XML encoding standard [VOR]. This specification is intended to be applicable whereever VOResource records are used, but in particular, it is intended as the standard for encoding resource descriptions within an IVOA-compliant registry [RI] and for encoding capability metadata available through the VO Standard Interface [VOSI].

1.1. Dependencies on Other Standards

This specification relies directly on other IVOA standards in the following ways:
VOResource, v1.03 [VOR]:
Descriptions of services that support the standard protocols are encoded using the VOResource XML Schema. The protocol-specific schemas defined in this document are extensions of the VOResource core schema.

Simple Cone Search, v1.03 [SCS],
Simple Image Access, v1.0 [SIA],
Simple Spectral Access, v1.04 [SSA]:
Each protocol specification describes the metadata concepts that should be included in a description of a service that supports the specification.

VODataService, v1.1 [VDS]:
The interface to the standard protocol functionality is described with a specialized Interface type, vs:ParamHTTP, which is defined in the VODataService XML Schema, an extension to VOResource. This document also recommends describing the service using VODataService resource type, vs:CatalogDataService.

Except where noted in subsequent sections, this specification does not allow imply support for any other versions (including later versions) than the ones noted above.

This specification refers to other IVOA standards:

Registry Interfaces, v1.0 [RI]:
A registry that is compliant with both this specification and the Registry Interfaces standard will encode service resource descriptions according to the recommendations in this document.

IVOA Standard Interface, v1.0 [VOSI]:
A service that supports one of the target protocols as well as the capability metadata retrieval method defined by VOSI [VOSI, section 2.1] is compliant with this specifcation if the capability metadata are encoded according the recommendations in this document.

Unlike with the previously mentioned specifications, this specification may apply to later versions of the RI and VOSI standards.

2. The Common Description Requirements

This section describes common requirements for describing the target DAL services as VOResource records.

To be recognized as a service, the DAL service resource must be described as a resource type of vr:Service (defined in the VOResource schema [VOR]) or one of its legal sub-types. As specified in the VOResource specification [VOR], the resource type is set by setting the xsi:type attribute on the element representing the root of the VOResource record to the namespace-qualified resource type name. As the DAL services respond to queries with tables of available data products, the resource should set the resource type to vs:CatalogService (defined in the VODataService extension schema [VDS]. In this case, record authors are encouraged to include coverage information (via the <coverage> element) and a full description of the columns in the table returned in query response (assuming full verbosity).

Note:
In the future, a more appropriate resource type may be defined for describing DAL services; thus, the loose requirement on the resource type allows for this. At the time of this writing, the vs:CatalogService is recommended as the most appropriate type and represents current practice with IVOA registries.

The VOResource record must include a <capability> element that describes the services support for the DAL protocol. The contents of the element is described in the next section. In all cases, the value of the <capability> element's standardID unambiguosly identifies the service's support for the particular DAL protocol. The resource may include other <capability> elements to describe support for other protocols.

The <capability> element describing support for the DAL protocol must include a child <interface> element that describes support for the required DAL interface; the xsi:type attribute on that element must be set to vs:ParamHTTP, and the role attribute must be set to "std". A <accessURL> element within that <interface> must be set to the base URL, as defined in the DAL protocol specification, that provides access to the standard DAL protocol. It is not necessary to provide the use attribute to the <accessURL> element (as its value can be assumed); however, when it is provided, it must be set to "base". Similarly, it is not necessary to provide the <interface> element with <queryType> or <resultType> elements; however, when provided, their values should be "GET" and "application/x-votable+xml", respectively. The vs:ParamHTTP allows one to describe input parameters supported by the service; description authors are encouraged to list the optional parameters and any custom parameters supported by the instance of the service.

A sample interface description for a simple DAL service.
 <interface xsi:type="vs:ParamHTTP" role="std">
    <accessURL use="base">
       http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f&
    </accessURL>

    <!-- here is a standard, optional parameter -->
    <param use="optional" std="true">
      <name>CFRAME</name>
      <description>request to shift to a given coordinate frame.</description>
      <dataType>string</dataType>
    </param>

    <!-- here is a site-specific parameter that this service supports -->
    <param use="optional" std="false">
      <name>FREQ</name>
      <description>Frequency of observation.</description>
      <unit>Hz</unit>
      <dataType>real</dataType>
    </param>
 </interface>

3. Describing Standard Capabilities

For each protocol

3.1. Simple Cone Search

ConeSearch

cs:ConeSearch Type Schema Definition:
(Note that the purpose of type CSCapRestriction is to fix the value of standardID.)
<xs:complexType name="CSCapRestriction" abstract="true" >
  <xs:complexContent >
    <xs:restriction base="vr:Capability" >
      <xs:sequence >
        <xs:element name="validationLevel" type="vr:Validation"
                    minOccurs="0" maxOccurs="unbounded" />
        <xs:element name="description" type="xs:token" minOccurs="0" />
        <xs:element name="interface" type="vr:Interface"
                    minOccurs="0" maxOccurs="unbounded" />
      </sequence>
      <xs:attribute name="standardID" type="vr:IdentifierURI" use="required"
                    fixed="ivo://ivoa.net/std/ConeSearch" />
    </restriction>
  </complexContent>
</complexType>

<xs:complexType name="ConeSearch" >
  <xs:complexContent >
    <xs:extension base="cs:CSCapRestriction" >
      <xs:sequence >
        <xs:element name="maxSR" type="xs:float" />
        <xs:element name="maxRecords" type="xs:int" />
        <xs:element name="verbosity" type="xs:boolean" />
        <xs:element name="testQuery" type="cs:Query" />
      </sequence>
    </extension>
  </complexContent>
</complexType>

cs:ConeSearch Extension Metadata Elements
ElementDefinition
maxSR
Value type: floating-point number: xs:float
Semantic Meaning: The largest search radius, in degrees, that will be accepted by the service without returning an error condition.
Occurrences: required
Comments:

Use 180.0 if there is no restriction.

maxRecords
Value type: integer: xs:int
Semantic Meaning: The largest number of records that the service will return.
Occurrences: required
verbosity
Value type: boolean (true/false): xs:boolean
Semantic Meaning: True if the service supports the VERB keyword; false, otherwise.
Occurrences: required
testQuery
Value type: composite: cs:Query
Semantic Meaning: A query that will result in at least on matched record that can be used to test the service.
Occurrences: required

Query

cs:Query Type Schema Definition
<xs:complexType name="Query" >
  <xs:sequence >
    <xs:element name="ra" type="xs:double" />
    <xs:element name="dec" type="xs:double" />
    <xs:element name="sr" type="xs:double" />
    <xs:element name="verb" type="xs:positiveInteger" minOccurs="0" />
    <xs:element name="catalog" type="xs:string" minOccurs="0" />
    <xs:element name="extras" type="xs:string" minOccurs="0" />
  </sequence>
</complexType>

cs:Query Metadata Elements
ElementDefinition
ra
Value type: floating-point number: xs:double
Semantic Meaning: the right ascension of the search cone's center in decimal degrees.
Occurrences: required
dec
Value type: floating-point number: xs:double
Semantic Meaning: the declination of the search cone's center in decimal degrees.
Occurrences: required
sr
Value type: floating-point number: xs:double
Semantic Meaning: the radius of the search cone in decimal degrees.
Occurrences: required
verb
Value type: positive integer: xs:positiveInteger
Semantic Meaning: the verbosity level to use where 1 or less means the bare minimum set of columns and 3 or more means the full set of available columns.
Occurrences: optional
catalog
Value type: string: xs:string
Semantic Meaning: the catalog to query.
Occurrences: optional
Comments:

When the service can access more than one catalog, this input parameter, if available, is used to indicate which service to access.

extras
Value type: string: xs:string
Semantic Meaning: any extra (non-standard) parameters that must be provided (apart from what is part of base URL given by the accessURL element).
Occurrences: optional
Comments:

this value should be in the form of name=value pairs delimited with apersands (&).

3.2. Simple Image Access

SimpleImageAccess

sia:SimpleImageAccess Type Schema Definition
(Note that the purpose of type SIACapRestriction is to fix the value of standardID.)
<xs:complexType name="SIACapRestriction" abstract="true" >
  <xs:complexContent >
    <xs:restriction base="vr:Capability" >
      <xs:sequence >
        <xs:element name="validationLevel" type="vr:Validation"
                    minOccurs="0" maxOccurs="unbounded" />
        <xs:element name="description" type="xs:token" minOccurs="0" />
        <xs:element name="interface" type="vr:Interface"
                    minOccurs="0" maxOccurs="unbounded" />
      </sequence>
      <xs:attribute name="standardID" type="vr:IdentifierURI" use="required"
                    fixed="ivo://ivoa.net/std/SIA" />
    </restriction>
  </complexContent>
</complexType>

<xs:complexType name="SimpleImageAccess" >
  <xs:complexContent >
    <xs:extension base="sia:SIACapRestriction" >
      <xs:sequence >
        <xs:element name="imageServiceType" type="sia:ImageServiceType" />
        <xs:element name="maxQueryRegionSize" type="sia:SkySize" />
        <xs:element name="maxImageExtent" type="sia:SkySize" />
        <xs:element name="maxImageSize" type="sia:ImageSize" />
        <xs:element name="maxFileSize" type="xs:int" />
        <xs:element name="maxRecords" type="xs:int" />
        <xs:element name="testQuery" type="sia:Query" minOccurs="0" maxOccurs="1" />
      </sequence>
    </extension>
  </complexContent>
</complexType>

sia:SimpleImageAccess Extension Metadata Elements
ElementDefinition
imageServiceType
SIA Name: Type.ImageService
Value type: string with controlled vocabulary
Semantic Meaning: The category of image service as defined by [SIA], section 3.
Occurrences: required
Allowed Values:
Cutout   an Image Cutout Service, as defined in [SIA], section 3 (see Note below).
Mosaic   an Image Mosaicing Service, as defined in [SIA], section 3 (see Note below).
Atlas   an Atlas Image Archive, as defined in [SIA], section 3 (see Note below).
Pointed   a Pointed Image Archive, as defined in [SIA], section 3 (see Note below).
maxQueryRegionSize
SIA Name: MaxQueryRegionSize
Value type: composite: sia:SkySize
Semantic Meaning: The maximum image query region size, expressed in decimal degrees. A value of 360 degrees indicates that there is no limit and the entire data collection (entire sky) can be queried.
Occurrences: required
maxImageExtent
SIA Name: MaxImageExtent
Value type: composite: sia:SkySize
Semantic Meaning: The maximum image query region size, expressed in decimal degrees. A value of 360 degrees indicates that there is no limit and the entire data collection (entire sky) can be requested.
Occurrences: required
maxImageSize
SIA Name: MaxImageSize
Value type: composite: sia:ImageSize
Semantic Meaning: The largest image (in terms of pixels) that can be requested.
Occurrences: required
maxFileSize
SIA Name: MaxFileSize
Value type: integer: xs:int
Semantic Meaning: The maximum image file size in bytes.
Occurrences: required
maxRecords
SIA Name: MaxRecords
Value type: integer: xs:int
Semantic Meaning: The largest number of records that the Image Query web method will return.
Occurrences: required
testQuery
Value type: composite: sia:Query
Semantic Meaning: a set of query parameters that is expected to produce at least one matched record which can be used to test the service.
Occurrences: optional

Note:
The SIA specification defines the image service types as follows:
Image Cutout Service
This is a service which extracts or "cuts out" rectangular regions of some larger image, returning an image of the requested size to the client. Such images are usually drawn from a database or a collection of survey images that cover some large portion of the sky. To be considered a cutout service, the returned image should closely approximate (or at least not exceed) the size of the requested region; however, a cutout service will not normally resample (rescale or reproject) the pixel data. A cutout service may mosaic image segments to cover a large region but is still considered a cutout service if it does not resample the data. Image cutout services are fast and avoid image degredation due to resampling.
Image Mosaicing Service
This service is similar to the image cutout service but adds the capability to compute an image of the size, scale, and projection specified by the client. Mosaic services include services which resample and reproject existing image data, as well as services which generate pixels from some more fundamental dataset, e.g., a high energy event list or a radio astronomy measurement set. Image mosaics can be expensive to generate for large regions but they make it easier for the client to overlay image data from different sources. Image mosaicing services which resample already pixelated data will degrade the data slightly, unlike the simpler cutout service which returns the data unchanged.
Atlas Image Archive
This category of service provides access to pre-computed images that make up a survey of some large portion of the sky. The service, however, is not capable of dynamically cutting out requested regions, and the size of atlas images is predetermined by the survey. Atlas images may range in size from small cutouts of extended objects to large calibrated survey data frames.
Pointed Image Archive
This category of service provides access to collections of images of many small, "pointed" regions of the sky. "Pointed" images normally focus on specific sources in the sky as opposed to being part of a sky survey. This type of service usually applies to instrumental archives from observatories with guest observer programs (e.g., the HST archive) and other general purpose image archives (e.g., the ADIL). If a service provides access to both survey and pointed images, then it should be considered a Pointed Image Archive for the purposes of this specification; if a differentiation between the types of data is desired the pointed and survey data collections should be registered as separate image services.

SkySize

sia:SkySize Type Schema Definition
<xs:complexType name="SkySize" >
  <xs:sequence >
    <xs:element name="long" type="xs:float" />
    <xs:element name="lat" type="xs:float" />
  </sequence>
</complexType>

sia:SkySize Metadata Elements
ElementDefinition
long
Value type: floating-point number: xs:float
Semantic Meaning: The maximum size in the longitude (R.A.) direction
Occurrences: required
lat
Value type: floating-point number: xs:float
Semantic Meaning: The maximum size in the latitdude (Dec.) direction
Occurrences: required

SkyPos

sia:SkyPos Type Schema Definition
<xs:complexType name="SkyPos" >
  <xs:sequence >
    <xs:element name="long" type="xs:double" />
    <xs:element name="lat" type="xs:double" />
  </sequence>
</complexType>

sia:SkyPos Metadata Elements
ElementDefinition
long
Value type: floating-point number: xs:double
Semantic Meaning: The sky position in the longitude (R.A.) direction
Occurrences: required
lat
Value type: floating-point number: xs:double
Semantic Meaning: The sky position in the latitdude (Dec.) direction
Occurrences: required

ImageSize

sia:ImageSize Type Schema Definition
<xs:complexType name="ImageSize" >
  <xs:sequence >
    <xs:element name="long" type="xs:int" />
    <xs:element name="lat" type="xs:int" />
  </sequence>
</complexType>

sia:ImageSize Metadata Elements
ElementDefinition
long
Value type: integer: xs:int
Semantic Meaning: The image size in the longitude (R.A.) direction in pixels
Occurrences: required
lat
Value type: integer: xs:int
Semantic Meaning: The image size in the latitdude (Dec.) direction in pixels
Occurrences: required

ImageServiceType

sia:ImageServiceType Type Schema Definition
<xs:simpleType name="ImageServiceType" >
  <xs:restriction base="xs:string" >
    <xs:enumeration value="Cutout" />
    <xs:enumeration value="Mosaic" />
    <xs:enumeration value="Atlas" />
    <xs:enumeration value="Pointed" />
  </restriction>
</simpleType>

Query

sia:Query Type Schema Definition
<xs:complexType name="Query" >
  <xs:sequence >
    <xs:element name="pos" type="sia:SkyPos" minOccurs="0" />
    <xs:element name="size" type="sia:SkySize" minOccurs="0" />
    <xs:element name="verb" type="xs:positiveInteger" minOccurs="0" />
    <xs:element name="extras" type="xs:string" minOccurs="0" />
  </sequence>
</complexType>

sia:Query Metadata Elements
ElementDefinition
pos
Value type: composite: sia:SkyPos
Semantic Meaning: the right ascension of the search cone's center in decimal degrees.
Occurrences: optional
size
Value type: composite: sia:SkySize
Semantic Meaning: the declination of the search cone's center in decimal degrees.
Occurrences: optional
verb
Value type: positive integer: xs:positiveInteger
Semantic Meaning: the verbosity level to use where 1 or less means the bare minimum set of columns and 3 or more means the full set of available columns.
Occurrences: optional
extras
Value type: string: xs:string
Semantic Meaning: any extra (particularly non-standard) parameters that must be provided (apart from what is part of base URL given by the accessURL element).
Occurrences: optional
Comments:

this value should be in the form of name=value pairs delimited with apersands (&).

3.2. Simple Spectral Access

SimpleSpectralAccess

ssa:SimpleSpectralAccess Type Schema Definition
<xs:complexType name="SSACapRestriction" abstract="true" >
  <xs:complexContent >
    <xs:restriction base="vr:Capability" >
      <xs:sequence >
        <xs:element name="validationLevel" type="vr:Validation" minOccurs="0"
            maxOccurs="unbounded" />
        <xs:element name="description" type="xs:token" minOccurs="0" />
        <xs:element name="interface" type="vr:Interface" minOccurs="0"
            maxOccurs="unbounded" />
      </sequence>
      <xs:attribute name="standardID" type="vr:IdentifierURI" use="required"
              fixed="ivo://ivoa.net/std/SSA" />
    </restriction>
  </complexContent>
</complexType>

<xs:complexType name="SimpleSpectralAccess" >
  <xs:complexContent >
    <xs:extension base="ssa:SSACapRestriction" >
      <xs:sequence >
        <xs:element name="complianceLevel" type="ssa:ComplianceLevel" />
        <xs:element name="dataSource" type="ssa:DataSource" minOccurs="1"
            maxOccurs="unbounded" />
        <xs:element name="creationType" type="ssa:CreationType" minOccurs="1"
            maxOccurs="unbounded" />
        <xs:element name="maxSearchRadius" type="xs:double" />
        <xs:element name="maxRecords" type="xs:int" />
        <xs:element name="defaultMaxRecords" type="xs:int" />
        <xs:element name="maxAperture" type="xs:double" minOccurs="0" />
        <xs:element name="maxFileSize" type="xs:int" maxOccurs="1" minOccurs="0" />
        <xs:element name="testQuery" type="ssa:Query" minOccurs="0" maxOccurs="1" />
      </sequence>
    </extension>
  </complexContent>
</complexType>

ssa:SimpleSpectralAccess Extension Metadata Elements
ElementDefinition
complianceLevel
Value type: string with controlled vocabulary
Semantic Meaning: The category indicating the level to which this instance complies with the SSA standard, as defined in [SSA], section 1.4.1.
Occurrences: required
Allowed Values:
query The service supports all of the capabilities and features of the SSA protocol identified as "must" in the specification, except that it does not support returning data in at least one SSA-compliant format.
minimal The service supports all of the capabilities and features of the SSA protocol identified as "must" in the specification.
full The service supports all of the capabilities and features of the SSA protocol identified as "must" or "should" in the specification.
dataSource
Value type: string with controlled vocabulary
Semantic Meaning: The category specifying where the data originally came from.
Occurrences: required; multiple occurrences allowed.
Allowed Values:
survey A survey dataset, which typically covers some region of observational parameter space in a uniform fashion, with as complete as possible coverage in the region of parameter space observed.
pointed A pointed observation of a particular astronomical object or field.
custom Data which has been custom processed, e.g., as part of a specific research project.
theory Theory data, or any data generated from a theoretical model, for example a synthetic spectrum.
artificial Artificial or simulated data.
creationType
Value type: string with controlled vocabulary
Semantic Meaning: The category that describes the process used to produce the dataset.
Occurrences: required; multiple occurrences allowed.
Allowed Values:
archival The entire archival or project dataset is returned. Transformations such as metadata or data model mediation or format conversions may take place, but the content of the dataset is not substantially modified (e.g., all the data is returned and the sample values are not modified).
cutout The dataset is subsetted in some region of parameter space to produce a subset dataset. Sample values are not modified, e.g., cutouts could be recombined to reconstitute the original dataset.
filtered The data is filtered in some fashion to exclude portions of the dataset, e.g., passing only data in selected regions along a measurement axis, or processing the data in a way which recomputes the sample values, e.g., due to interpolation or flux transformation.
mosaic Data from multiple non- or partially-overlapping datasets are combined to produce a new dataset.
projection Data is geometrically warped or dimensionally reduced by projecting through a multidimensional dataset.
specialExtraction Extraction of a spectrum from another dataset, e.g., extraction of a spectrum from a spectral data cube through a simulated aperture.
catalogExtraction Extraction of a catalog of some form from another dataset, e.g., extraction of a source catalog from an image, or extraction of a line list catalog from a spectrum (not valid for a SSA service).
Comments:

Typically this describes only the processing performed by the data service, but it could describe some additional earlier processing as well, e.g., if data is partially precomputed.

Allowed values are "archival", "cutout", "filtered", "mosaic", "projection", "spectralExtraction", "catalogExtraction"

maxSearchRadius
Value type: floating-point number: xs:double
Semantic Meaning: The largest search radius, in degrees, that will be accepted by the service without returning an error condition.
Occurrences: required
Comments:

Use 180.0 if there is no restriction.

maxRecords
Value type:
Semantic Meaning: The hard limit on the largest number of records that the query operation will return in a single response
Occurrences: required
defaultMaxRecords
Value type:
Semantic Meaning: The largest number of records that the service will return when the MAXREC parameter not specified in the query input.
Occurrences: required
maxAperture
Value type: floating-point number: xs:double
Semantic Meaning: The largest aperture that can be supported upon request via the APERTURE input parameter by a service that supports the special extraction creation method.
Occurrences: optional
Comments:

A value of 180 (the default) means there is no theoretical limit.

maxFileSize
Value type:
Semantic Meaning: The maximum image file size in bytes.
Occurrences: optional
testQuery
Value type: composite: ssa:Query
Semantic Meaning: a set of query parameters that is expected to produce at least one matched record which can be used to test the service.
Occurrences: optional

ComplianceLevel

ssa:ComplianceLevel Type Schema Definition
<xs:simpleType name="ComplianceLevel" >
  <xs:restriction base="xs:string" >
    <xs:enumeration value="query" />
    <xs:enumeration value="minimal" />
    <xs:enumeration value="full" />
  </restriction>
</simpleType>

DataSource

ssa:DataSource Type Schema Definition
<xs:simpleType name="DataSource" >
  <xs:restriction base="xs:string" >
    <xs:enumeration value="survey" />
    <xs:enumeration value="pointed" />
    <xs:enumeration value="custom" />
    <xs:enumeration value="theory" />
    <xs:enumeration value="artificial" />
  </restriction>
</simpleType>

CreationType

ssa:CreationType Type Schema Definition
<xs:simpleType name="CreationType" >
  <xs:restriction base="xs:string" >
    <xs:enumeration value="archival" />
    <xs:enumeration value="cutout" />
    <xs:enumeration value="filtered" />
    <xs:enumeration value="mosaic" />
    <xs:enumeration value="projection" />
    <xs:enumeration value="specialExtraction" />
    <xs:enumeration value="catalogExtraction" />
  </restriction>
</simpleType>

PosParam

ssa:PosParam Type Schema Definition
<xs:complexType name="PosParam" >
  <xs:sequence >
    <xs:element name="long" type="xs:double" minOccurs="0" />
    <xs:element name="lat" type="xs:double" minOccurs="0" />
    <xs:element name="refframe" type="xs:token" minOccurs="0" />
  </sequence>
</complexType>

ssa:PosParam Metadata Elements
ElementDefinition
long
Value type: floating-point number: xs:double
Semantic Meaning: The longitude (e.g. Right Ascension) of the center of the search position in decimal degrees.
Occurrences: optional
lat
Value type: floating-point number: xs:double
Semantic Meaning: The latitude (e.g. Declination) of the center of the search position in decimal degrees.
Occurrences: optional
refframe
Value type: string: xs:token
Semantic Meaning: the coordinate system reference frame name indicating the frame to assume for the given position. If not provided, ICRS is assumed.
Occurrences: optional

ProtoSpectralAccess

ssa:ProtoSpectralAccess Type Schema Definition
<xs:complexType name="ProtoSpectralAccess" >
  <xs:complexContent >
    <xs:extension base="ssa:SSACapRestriction" >
      <xs:sequence >
        <xs:element name="dataSource" type="ssa:DataSource" minOccurs="1"
            maxOccurs="unbounded" />
        <xs:element name="creationType" type="ssa:CreationType" minOccurs="1"
            maxOccurs="unbounded" />
        <xs:element name="maxSearchRadius" type="xs:double" />
        <xs:element name="maxRecords" type="xs:int" />
        <xs:element name="defaultMaxRecords" type="xs:int" />
        <xs:element name="maxAperture" type="xs:double" minOccurs="0" />
        <xs:element name="maxFileSize" type="xs:int" maxOccurs="1" minOccurs="0" />
        <xs:element name="testQuery" type="ssa:Query" minOccurs="0" maxOccurs="1" />
      </sequence>
    </extension>
  </complexContent>
</complexType>

ssa:ProtoSpectralAccess Extension Metadata Elements
ElementDefinition
dataSource
Value type: string with controlled vocabulary
Semantic Meaning: The category specifying where the data originally came from.
Occurrences: required; multiple occurrences allowed.
Allowed Values:
survey A survey dataset, which typically covers some region of observational parameter space in a uniform fashion, with as complete as possible coverage in the region of parameter space observed.
pointed A pointed observation of a particular astronomical object or field.
custom Data which has been custom processed, e.g., as part of a specific research project.
theory Theory data, or any data generated from a theoretical model, for example a synthetic spectrum.
artificial Artificial or simulated data.
Comments:

Allowed values are "survey", "pointed", "custom", "theory", "artificial"

creationType
Value type: string with controlled vocabulary
Semantic Meaning: The category that describes the process used to produce the dataset.
Occurrences: required; multiple occurrences allowed.
Allowed Values:
archival The entire archival or project dataset is returned. Transformations such as metadata or data model mediation or format conversions may take place, but the content of the dataset is not substantially modified (e.g., all the data is returned and the sample values are not modified).
cutout The dataset is subsetted in some region of parameter space to produce a subset dataset. Sample values are not modified, e.g., cutouts could be recombined to reconstitute the original dataset.
filtered The data is filtered in some fashion to exclude portions of the dataset, e.g., passing only data in selected regions along a measurement axis, or processing the data in a way which recomputes the sample values, e.g., due to interpolation or flux transformation.
mosaic Data from multiple non- or partially-overlapping datasets are combined to produce a new dataset.
projection Data is geometrically warped or dimensionally reduced by projecting through a multidimensional dataset.
specialExtraction Extraction of a spectrum from another dataset, e.g., extraction of a spectrum from a spectral data cube through a simulated aperture.
catalogExtraction Extraction of a catalog of some form from another dataset, e.g., extraction of a source catalog from an image, or extraction of a line list catalog from a spectrum (not valid for a SSA service).
Comments:

Typically this describes only the processing performed by the data service, but it could describe some additional earlier processing as well, e.g., if data is partially precomputed.

Allowed values are "archival", "cutout", "filtered", "mosaic", "projection", "spectralExtraction", "catalogExtraction"

maxSearchRadius
Value type: floating-point number: xs:double
Semantic Meaning: The largest search radius, in degrees, that will be accepted by the service without returning an error condition.
Occurrences: required
Comments:

Use 180.0 if there is no restriction.

maxRecords
Value type:
Semantic Meaning: The hard limit on the largest number of records that the query operation will return in a single response
Occurrences: required
defaultMaxRecords
Value type:
Semantic Meaning: The largest number of records that the service will return when the MAXREC parameter not specified in the query input.
Occurrences: required
maxAperture
Value type: floating-point number: xs:double
Semantic Meaning: The largest aperture that can be supported upon request via the APERTURE input parameter by a service that supports the special extraction creation method.
Occurrences: optional
Comments:

A value of 180 (the default) means there is no theoretical limit.

maxFileSize
Value type:
Semantic Meaning: The maximum image file size in bytes.
Occurrences: optional
testQuery
Value type: composite: ssa:Query
Semantic Meaning: a set of query parameters that is expected to produce at least one matched record which can be used to test the service.
Occurrences: optional

Query

ssa:Query Type Schema Definition
<xs:complexType name="Query" >
  <xs:sequence >
    <xs:element name="pos" type="ssa:PosParam" minOccurs="0" />
    <xs:element name="size" type="xs:double" minOccurs="0" />
    <xs:element name="queryDataCmd" type="xs:string" minOccurs="0" />
  </sequence>
</complexType>

ssa:Query Metadata Elements
ElementDefinition
pos
Value type: composite: ssa:PosParam
Semantic Meaning: the center position the search cone given in decimal degrees.
Occurrences: optional
size
Value type: floating-point number: xs:double
Semantic Meaning: the size of the search radius.
Occurrences: optional
queryDataCmd
Value type: string: xs:string
Semantic Meaning: Fully specified test query formatted as an URL argument list in the syntax specified by the SSA standard. The list must exclude the REQUEST argument which is assumed to be set to "queryData".
Occurrences: optional
Comments:

This value must be in the form of name=value pairs delimited with apersands (&). A query may then be formed by appending to the base URL the request argument, "REQUEST=queryData&", followed by the contents of this element.

Appendix A: The XML Schemas

A.1 The ConeSearch XML Schema


A.1 The SIA XML Schema


A.1 The SSA XML Schema


Appendix B: Supporting Multiple Versions of DAL Protocols

non-normative

Appendix C: Change History

None yet applicable.

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
[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/
[SCS]
Williams, R., Hanisch, R., Szalay, A., and Plante, R. 2008, Simple Cone Search Version 1.03, IVOA Recommendation, 22 February 2008, http://www.ivoa.net/Documents/REC/DAL/ConeSearch-20080222.html.
[SIA]
Tody, D. and Plante, R. 2004, Simple Image Access Specification Version 1.0, IVOA Working Draft, http://www.ivoa.net/Documents/WD/SIA/sia-20040524.html.
[SSA]
Tody, D., Dolensky, M., McDowell, J., Bonnarel, F., Budavari, T., Busko, I., Micol, A., Osuna, P, Salgado, J., Skoda, P., Thompson, R., and Valdes, F. 2008, Simple Spectral Access Protocol Version 1.04, IVOA Recommendation, 01 Febrary 2008, http://www.ivoa.net/Documents/cover/SSA-20080201.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
[RM]
Hanisch, Robert (ed.) 2004. Resource Metadata for the Virtual Observatory, Version 1.12, IVOA Recommendation, http://www.ivoa.net/Documents/REC/ResMetadata/RM-20040426.htm
[VOR]
Plante, R., Benson, K., Graham, M., Greene, G., Harrison, P., Lemson, G., Linde, T., Rixon, G., Stébé, A. 2008, VOResource: an XML Encoding Schema for Resource Metadata, v1.03, IVOA Recommendation, http://www.ivoa.net/Documents/REC/ReR/VOResource-20080222.html
[VDS]
Plante, R., Stébé, A. Benson, K., Dowler, P. Graham, M., Greene, G., Harrison, P., Lemson, G., Linde, T., Rixon, G., Stébé, A. 2009, VODataService: a VOResource Schema Extension for Describing Collections and Services, v1.1, IVOA Proposed Recommendation, http://www.ivoa.net/Documents/VODataService/20090903/