\documentclass[11pt,a4paper]{ivoa}
% we widen up the page a bit so schema fragments with 80 chars/line
% don't cause overfull hboxes.
\usepackage[scale=0.75]{geometry}
\input tthdefs
\usepackage{listings}
\lstloadlanguages{XML}
\lstset{flexiblecolumns=true,tagstyle=\ttfamily, showstringspaces=False}
\title{Describing Simple Data Access Services}
\ivoagroup{Registry}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante]{Raymond
Plante}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/MarkusDemleitner]{Markus
Demleitner}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/JesusSalgado]{Jesus Salgado}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/PaulHarrison]{Paul Harrison}
\author[http://www.ivoa.net/twiki/bin/view/IVOA/DougTody]{Doug Tody}
\editor{Markus Demleitner}
\previousversion[https://ivoa.net/documents/SimpleDALRegExt/20200424/]{
WD-20200424}
\previousversion[http://ivoa.net/documents/SimpleDALRegExt/20200212/]{
WD-20200212}
\previousversion[http://ivoa.net/documents/SimpleDALRegExt/20170530/]{
REC-1.1}
\previousversion[http://ivoa.net/documents/SimpleDALRegExt/20160525/]{
WD-20160525}
\previousversion[http://www.ivoa.net/Documents/SimpleDALRegExt/20131005/]{
REC-1.0}
\begin{document}
\SVN$Rev$
\SVN$Date$
\SVN$URL$
\begin{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 service that
supports any of the four typed data access protocols -- Simple Cone
Search (SCS), Simple Image Access (SIA), Simple Spectral Access (SSA),
Simple Line Access (SLA) -- 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 rules for describing such
services within the context of IVOA Registries and data discovery as
well as the VO Support Interfaces (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.
\end{abstract}
\section*{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), from the Eurpean Commission's Sixth Framework Program
via the Optical Infrared Coordination Network (OPTICON), and from
BMBF grant 05A14VHA (GAVO).
\section*{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 \citep{std: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 \citep{std:XSD}
This document defines the VOResource schema using XML Schema. The full
Schema documents are kept on the IVOA schema
repository\footnote{\url{http://ivoa.net/xml/}}. The files given
there are authoritative and override XML schema fragments contained
in specification in case of conflicts.
Note that the schema files in the IVOA repository can change
over time according to the
rules laid down in \citet{2018ivoa.spec.0529H}.
Reference to specific elements and types defined in the VOResource
schema include the namespaces prefix, \xmlel{vr:}, as in
\xmlel{vr:Resource}.
Reference to specific elements and
types defined in the VODataService extension schema include the
namespaces prefix, \xmlel{vs:}, as in \xmlel{vs:ParamHTTP}.
Use of the \xmlel{vs:} prefix in compliant instance
documents is strongly recommended, particularly in the applications
that involve IVOA Registries \citep{2009ivoa.spec.1104B}.
\section{Introduction}
Four data access service protocols play a key role in discovering data
in the VO:
\begin{itemize}
\item Simple Cone Search \citep{2008ivoa.specQ0222P} -- searches a catalog for sources or
observations that are within a given distance of a sky position.
\item Simple Image Access \citep{2015ivoa.spec.1223D} -- searches an
archive for spatially resolved data (like images and cubes)
that overlap a given region of sky.
While the extension
presented here was designed for SIAP version 1, it can be
used for SIAP version 2 \citep{2015ivoa.spec.1223D} services,
too. A future version of SIAP version 2 may provide a registry
extension tailored to it, in which case that extension should be
preferred.
\item Simple Spectral Access \citep{2012ivoa.spec.0210T} -- searches an archive for spectra
of positions within a given region of sky.
\item Simple Line Access \citep{2010ivoa.specQ1209O} -- searches a catalog specializing in
descriptions of spectral line transitions.
\end{itemize}
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 multiple services
which support that protocol, and
to then interpret the results uniformly. The collected
results, in effect, represent all
the relevant 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 as
described by the Registry Interfaces standard
\citep{2018ivoa.spec.0723D} -- i.e., a searchable repository of descriptions of resources in
VO. These descriptions are comprised of common standard metadata as
specified in the Resource Metadata document
\citep{2007ivoa.spec.0302H} 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 \citep{2008ivoa.spec.0222P}. 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 to 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:
\begin{enumerate}
\item 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.
\item The application may wish to plan its use of the service according
its limitations, such as the maximum region of sky that can be
searched in one query.
\end{enumerate}
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, for example, 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, SSA, and SLA.
This document describes for each of the standard data access
protocols -- SCS, SIA, SSA, and SLA -- precisely how to describe a service
that supports one of the protocols in terms of the VOResource XML
encoding standard. This specification is intended to be
applicable wherever VOResource records are used, but in particular, it
is intended as the standard for encoding resource descriptions within
an IVOA-compliant registry and for encoding capability
metadata available through the VO Support Interfaces VOSI
\citep{2017ivoa.spec.0524G}.
\subsection{The Role in IVOA Architecture}
\begin{figure}
\centering
\includegraphics[width=0.9\textwidth]{role_diagram.pdf}
\caption{SimpleDALRegExt in the IVOA Architecture}
\label{fig:archdiag}
\end{figure}
The IVOA Architecture \citep{2010ivoa.rept.1123A} provides a high-level view of how IVOA
standards work together to connect users and applications with
providers of data and services, as depicted in the diagram in
Fig.~\ref{fig:archdiag}.
In this architecture, data access protocols provide the means for users
(via the User Layer) to access data from archives. Of particular
importance are the standard protocols, SCS, SIA, SSA, and SLA, which
allow a generic user tool to find data in any archive that supports
those protocols. Registries provide to tools in the User Layer a means
to discover which archives support the standard protocols. A registry
is a repository of descriptions of resources, such as standard
services, that can be searched based on the metadata in those
descriptions.
The Registry enables applications in the User Layer to discover archives
in the Resource Layer and the services they provide for accessing data,
particularly those that support the standard data access protocols like
SIAP, SCS, SSAP, and SLAP (illustrated on the right). The registry
metadata model standards (in blue text and boxes on the left) give
structure to the information that enables that discovery. In
particular, the SimpleDALRegExt standard defines the metadata used to
describe standard data access services of the types listed on the right.
Resource descriptions have a well-defined structure: the core concepts
are defined in the Resource Metadata standard \citep{2007ivoa.spec.0302H}, and the format
is defined by the VOResource XML standard \citep{2008ivoa.spec.0222P}. Additional
metadata specialized to describe a specific kind of service are defined
via extensions to the VOResource core XML Schema. SimpleDALRegExt is
one such extension specifically for describing SCS, SIA, SSA, and SLA
services in the registry.
\subsection{Dependencies on Other Standards}
This specification relies directly on other IVOA standards in the
following ways:
\begin{bigdescription}
\item[VOResource, v1.1 \citep{2018ivoa.spec.0625P}]
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.
\item[Typed DAL Protocols]
The standards Simple Cone Search, v1.03 \citep{2008ivoa.specQ0222P},
Simple Image Access, v1.0 \citep{2009ivoa.spec.1111H},
Simple Image Access, v2.0 \citep{2015ivoa.spec.1223D},
Simple Spectral Access, v1.1 \citep{2012ivoa.spec.0210T}, and
Simple Line Access, v1.0 \citep{2010ivoa.specQ1209O}
describe the metadata concepts that should be included in a
description of a service that supports the specification.
We expect future versions of these standards to provide their
own metadata schemes. Unless they do, however, the relevant
metadata scheme from this document should be used.
\item[VODataService, v1.1 \citep{2010ivoa.spec.1202P}]
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,
\xmlel{vs:CatalogDataService}.
\end{bigdescription}
This specification refers to other IVOA standards:
\begin{bigdescription}
\item[Registry Interfaces, v1.1 \citep{2018ivoa.spec.0723D}]
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.
\item[VO Support Interfaces, v1.1 \citep{2017ivoa.spec.0524G}]
A service that supports one of the target protocols as well as
the capability metadata retrieval method defined by VOSI
is compliant with this specification if
the capability metadata are encoded according the
recommendations in this document.
\item[RegTAP, v1.1 \citep{2019ivoa.spec.1011D}]
This specification makes use of the extensability of RegTAP schema
through its \verb|res_details| table. In particular, it overwrites
the specifications made in RegTAP 1.1's Appendix A for the extension
schemas defined here.
\end{bigdescription}
\section{The Common Data Model for Simple DAL Services}
\label{sect:dm}
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 \xmlel{vr:Service} (defined in the VOResource
schema) or one of its legal sub-types. As specified in the
VOResource specification, the resource type is set by setting
the \xmlel{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,
their Registry records will typically be of the resource type
\xmlel{vs:CatalogService} (defined
in the VODataService extension schema). In this case, record
authors are encouraged to include a full description of the columns in
the table returned in query response (assuming full verbosity). The
\xmlel{vs:CatalogService} resource type also allows the record to provide sky
coverage information which authors are also encouraged to provide; an
exception to this would be for pure SLA services as the spectral line
catalogs they serve are not strictly sky observations.
The VOResource record must include a \xmlel{capability} element that
describes the services support for the DAL protocol. The contents of the
element is described in section~\ref{sect:describing}. In all cases, the
value of the \xmlel{capability} element's \xmlel{standardID}
unambiguously identifies the service's support for the particular DAL
protocol. The resource may include other \xmlel{capability} elements to
describe support for other protocols.
Note that, by the IVOA Identifiers standard \citep{2016ivoa.spec.0523D},
the scheme, authority, and path parts of ivoids must be compared
case-insensitively. That means that clients comparing standardIDs
obtained from, for instance, a VOSI capability endpoint, must normalise
them. The recommended normalisation is simply lowercasing them.
\begin{admonition}{Note}
In VO practice, many clients still discover the standard endpoints by looking
for \xmlel{capability} elements with the \xmlel{standardID} of the
protocol they are interested in and then locating a
\xmlel{vs:ParamHTTP}-typed \xmlel{interface} in it without regard for it
being marked up with \verb|role="std"|. While this practice should
cease in the years following 2019, and new clients have no reason to do
so any more, Resource record authors
should, for the time being, not include non-standard \xmlel{vs:ParamHTTP}
interfaces in capabilities with the \xmlel{standardID}s defined here.
\end{admonition}
The \xmlel{capability} element describing support for the DAL protocol
must include a child \xmlel{interface} element that describes support
for the required DAL interface; the \xmlel{xsi:type} attribute on that element
must be set to \xmlel{vs:ParamHTTP}, and the role attribute must be set
to \verb|"std"|. A \xmlel{accessURL} element within that
\xmlel{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 \xmlel{use} attribute to the
\xmlel{accessURL} element (as its value can be assumed); however, when
it is provided, it must be set to \verb|"base"|. Similarly, it is not
necessary to provide the \xmlel{interface} element with
\xmlel{queryType} or \xmlel{resultType} elements; however, when
provided, their values should be \verb|"GET"| and
\verb|"application/x-votable+xml"|, respectively. The
\xmlel{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.
Here is a sample interface description for a simple DAL service.
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f&
CFRAME
request to shift to a given coordinate frame.
string
FREQ
Frequency of observation.
Hz
real
\end{lstlisting}
\section{Describing Standard Capabilities}
\label{sect:describing}
This section describes the specific VOResource metadata extension
schemas used to describe support for the target DAL protocols. The
purpose of these schemas are to provide the \xmlel{vr:Capability} sub-type that
identifies the specific protocol. These are defined employing the
recommendations for \xmlel{vr:Capability} extensions given in the VOResource
standard. In particular, each extension schema has the
following features:
\begin{itemize}
\item The namespace associated with the extension is a URI that is
intended to resolve an HTTP URL to XML Schema document that defines
the extension schema. This means that VOResource document authors
may use this URI as the location URL within the value of
\xmlel{xsi:schemaLocation} attribute.
Note that the IVOA Registry Interface standard actually
requires that the VOResource records it shares with other
registries provide location URLs via
\xmlel{xsi:schemaLocation}
for the VOResource schema and all legal extension schemas
that are used in the records. This rule would apply to the
extension schemas defined in this standard.
\item A particular namespace prefix is recommended for use when referring
to the specialized \xmlel{vr:Capability} sub-type defined in the schema.
In general XML applications, instance documents may use any prefix;
however, in a VO context, document authors are strongly advised
to use the canonical prefixes given (and used) in this document
to avoid confusion when raw XML is exposed to the users. This
means that documents should not use two different versions of a
given schema (as defined by a common canonical prefix) within the
same namespace mapping; documents for which this is impossible
are probably semantically invalid.
\item Following VOResource practice, the schema sets
\xmlel{elementFormDefault} to \verb|"unqualified"|. This means that
element names defined in the schema do not take a namespace
prefix (as there are no global elements defined).
The only place namespaced names occur in SimpleDALRegExt instance
elements is the
Capability sub-type name given as the value of an
\xmlel{xsi:type}
attribute on the \xmlel{capability} element (see the examples in the
subsections below).
\item The specialized \xmlel{vr:Capability} sub-type includes a
\xmlel{testQuery}
element for encoding parameters that together can be used to test
the service. The format for encoding the individual parameters is
customized for each of the four simple services covered in this
specification.
\end{itemize}
\subsection{Simple Cone Search}
This section describes the ConeSearch VOResource metadata extension
schema which is used to describe services that comply with the Simple
Cone Search protocol \citep{2008ivoa.specQ0222P}.
\subsubsection{The Standard Identifier}
The \xmlel{standardID} value for Simple Cone Search version 1.03 (and
before) is
$$\hbox{\nolinkurl{ivo://ivoa.net/std/ConeSearch} .}$$ Standard
identifiers for later versions will be given in the respective
standards.
\subsubsection{The Schema Namespace}
The namespace associated with the ConeSearch extension schema is
$$\hbox{\nolinkurl{http://www.ivoa.net/xml/ConeSearch/v1.0} ,}$$
the canonical prefix is \xmlel{cs:}.
\subsubsection{ConeSearch}
The \xmlel{cs:ConeSearch} type is a \xmlel{vr:Capability} sub-type that should be used
to describe a service's support for the Simple Cone Search protocol;
it is defined as follows:
% GENERATED: !schemadoc ConeSearch-v1.1.xsd ConeSearch
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{cs:ConeSearch} Type Schema Documentation}
\noindent{\small
The capabilities of a Cone Search implementation.
\par}
\vspace{1ex}\noindent\textbf{\xmlel{cs:ConeSearch} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{cs:ConeSearch} Extension Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{maxSR}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:float}
\item[Meaning]
The largest search radius, in degrees, that will be
accepted by the service without returning an error
condition. Not providing this element or
specifying a value of 180 indicates that there
is no restriction.
\item[Occurrence] optional
\item[Comment]
Not providing a value is the prefered way to indicate
that there is no restriction.
\end{description}
\item[Element \xmlel{maxRecords}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
The largest number of records that the service will
return. Not providing this value means that
there is no effective limit.
\item[Occurrence] optional
\item[Comment]
This does not refer to the total number of records in
the catalog but rather maximum number of records the
service is capable of returning. A limit that is
greater than the number of records available in the
archive is equivalent to their being no effective
limit. (See RM, Hanisch 2007.)
\end{description}
\item[Element \xmlel{verbosity}]
\begin{description}
\item[Type] boolean (true/false): xs:boolean
\item[Meaning]
True if the service supports the VERB keyword;
false, otherwise.
\item[Occurrence] required
\end{description}
\item[Element \xmlel{testQuery}]
\begin{description}
\item[Type] composite: \xmlel{cs:Query}
\item[Meaning]
A query that will result in at least one
matched record that can be used to test the
service.
\item[Occurrence] optional
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
The custom metadata that the \xmlel{cs:ConeSearch} type provides is given
above. For the elements whose semantics map directly to
service profile metadata called for in the SCS standard,
section 3, there is an entry labeled ``SCS Name''; this indicates the
metadata name given in the SCS specification that the element in this
schema corresponds to. The profile metadata listed in the SCS
specification that is not covered by the elements below are covered by
other metadata that are part of the core VOResource schema.
\subsubsection{testQuery and the Query Type}
The \xmlel{testQuery} element is intended to help other VO components (e.g.
registries, validation services, services that monitor the VO's
operational health, but typically not end users) test that the service
is up and operating correctly. It provides a set of legal input
parameters that should return a legal response that includes at least
one matched record. Since this query is intended for testing purposes,
the size of the result set should be small.
The \xmlel{cs:Query} type captures the different components of the query into
separate elements, as defined below:
% GENERATED: !schemadoc ConeSearch-v1.1.xsd Query
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{cs:Query} Type Schema Documentation}
\noindent{\small
A query to be sent to the service
\par}
\vspace{1ex}\noindent\textbf{\xmlel{cs:Query} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{cs:Query} Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{ra}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
the right ascension of the search cone's center in
decimal degrees.
\item[Occurrence] required
\end{description}
\item[Element \xmlel{dec}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
the declination of the search cone's center in
decimal degrees.
\item[Occurrence] required
\end{description}
\item[Element \xmlel{sr}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
the radius of the search cone in decimal degrees.
\item[Occurrence] required
\end{description}
\item[Element \xmlel{verb}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
the verbosity level to use where 1 means the bare
minimum set of columns and 3 means the full set of
available columns.
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{catalog}]
\begin{description}
\item[Type] string: \xmlel{xs:string}
\item[Meaning]
the catalog to query.
\item[Occurrence] optional
\item[Comment]
When the service can access more than one catalog,
this input parameter, if available, is used to
indicate which catalog to access.
\end{description}
\item[Element \xmlel{extras}]
\begin{description}
\item[Type] string: \xmlel{xs:string}
\item[Meaning]
any extra (non-standard) parameters that must be
provided (apart from what is part of base URL given
by the accessURL element).
\item[Occurrence] optional
\item[Comment]
this value should be in the form of name=value
pairs delimited with ampersands (\&).
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{RegTAP Details Keys}
The following RegTAP \verb|res_details| keys are derived from the SCS
capability type by mapping xpaths as defined by RegTAP; keys RegTAP
services must include in their tables if they are given in the registry
record are marked by an exclamation mark:
\begin{description}
\item[/capability/maxRecords (!)]The largest number of rows the cone
search will return
\item[/capability/maxSR (!)]The largest search radius of a cone search service
\item[/capability/testQuery/catalog]The catalog used in a test query.
\item[/capability/testQuery/dec]Declination in a test query.
\item[/capability/testQuery/extras]Any extra (non-standard) parameters
that must be provided (apart from what is part of base URL given by the
accessURL element)
\item[/capability/testQuery/ra]Right ascension in a test query
\item[/capability/testQuery/sr]Search radius of a cone search service's test query
\item[/capability/testQuery/verb]Verbosity of a service's test query
\item[/capability/verbosity (!)]\texttt{true} if the service supports the VERB keyword; \texttt{false}, otherwise
\end{description}
\subsection{Simple Image Access}
This section describes the SIA VOResource metadata extension schema
which is used to describe services that comply with versions of the
Simple Image Access protocol for which the specifications do not give
extensions themselves. This applies at least to versions 1.0
\citep{2009ivoa.spec.1111H} and 2.0 \citep{2015ivoa.spec.1223D}..
\subsubsection{The Standard Identifier}
The \xmlel{standardID} value for the Simple Image Access protocol
version 1.0 is
$$\hbox{\nolinkurl{ivo://ivoa.net/std/SIA} .}$$ Standard
identifiers for later versions are given in the respective
standards; for instance, SIA version 2.0 \citep{2015ivoa.spec.1223D},
specifies
$$\hbox{\nolinkurl{ivo://ivoa.net/std/SIA#query-2.0}}$$ for its query
capability.
\subsubsection{The Schema Namespace}
The namespace associated with the SIA extension schema is
$$\hbox{\nolinkurl{http://www.ivoa.net/xml/SIA/v1.1} ,}$$ the canonical
namespace prefix is \xmlel{sia:}
\subsubsection{SimpleImageAccess}
The \xmlel{sia:SimpleImageAccess} type is a \xmlel{vr:Capability} sub-type that should
be used to describe a service's support for the Simple Image Access
protocol; it is defined as follows:
% GENERATED: !schemadoc SIA-v1.2.xsd SimpleImageAccess
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{sia:SimpleImageAccess} Type Schema Documentation}
\noindent{\small
The capabilities of an SIA implementation.
\par}
\vspace{1ex}\noindent\textbf{\xmlel{sia:SimpleImageAccess} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{sia:SimpleImageAccess} Extension Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{imageServiceType}]
\begin{description}
\item[Type] string with controlled vocabulary
\item[Meaning]
The class of image service: Cutout, Mosaic, Atlas, Pointed
\item[Occurrence] required
\item[Terms]\hfil
\begin{longtermsdescription}
\item[Cutout]
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.
\item[Mosaic]
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.
\item[Atlas]
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.
\item[Pointed]
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.
\end{longtermsdescription}
\end{description}
\item[Element \xmlel{maxQueryRegionSize}]
\begin{description}
\item[Type] composite: \xmlel{sia:SkySize}
\item[Meaning]
The maximum image query region size, expressed in
decimal degrees. Not providing this element or
specifying a value of 360 degrees indicates that
there is no limit and the entire data collection
(entire sky) can be queried.
\item[Occurrence] optional
\item[Comment]
Not providing a value is the prefered way to indicate
that there is no limit.
\end{description}
\item[Element \xmlel{maxImageExtent}]
\begin{description}
\item[Type] composite: \xmlel{sia:SkySize}
\item[Meaning]
An upper bound on a region of the sky that can
be covered by returned images. That is, no image
returned by this service will cover more than
this limit. Not providing this element or
specifying a value of 360 degrees indicates that
there is no fundamental limit to the region covered
by a returned image.
\item[Occurrence] optional
\item[Comment]
When the imageServiceType is “Cutout” or “Mosaic”,
this represents the largest area that can be requested.
In this case, the “no limit” value means that all-sky
images can be requested. When the type is “Atlas” or
“Pointed”, it should be a region that most closely
encloses largest images in the archive, and the ”no
limit” value means that the archive contains all-sky
(or nearly so) images.
\item[Comment]
Not providing a value is the prefered way to indicate
that there is no limit.
\end{description}
\item[Element \xmlel{maxImageSize}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
A measure of the largest image the service
can produce given as the maximum number of
pixels along the first or second axes.
Not providing a value indicates that there is
no effective limit to the size of the images
that can be returned.
\item[Occurrence] optional
\item[Comment]
This is primarily relevant when the imageServiceType
is “Cutout” or “Mosaic”, indicating the largest
image that can be created. When the imageServiceType
is “Atlas” or “Pointed”, this should be specified only
when there are static images in the archive that can
be searched for but not returned because they are
too big.
\item[Comment]
When a service is more fundementally limited
by the total number of pixels in the image, this
value should be set to the square-root of that
number. This number will then represent a
lower limit on the maximum length of a side.
\end{description}
\item[Element \xmlel{maxFileSize}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
The maximum image file size in bytes. Not providing
a value indicates that there is no effective limit
the size of files that can be returned.
\item[Occurrence] optional
\item[Comment]
This is primarily relevant when the imageServiceType
is “Cutout” or “Mosaic”, indicating the largest
files that can be created. When the imageServiceType
is “Atlas” or “Pointed”, this should be specified only
when there are static images in the archive that can
be searched for but not returned because they are
too big.
\end{description}
\item[Element \xmlel{maxRecords}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
The largest number of records that the Image Query web
method will return. Not providing this value means that
there is no effective limit.
\item[Occurrence] optional
\item[Comment]
This does not refer to the total number of images in
the archive but rather maximum number of records the
service is capable of returning. A limit that is
greater than the number of images available in the
archive is equivalent to their being no effective
limit. (See RM, Hanisch 2007.)
\end{description}
\item[Element \xmlel{testQuery}]
\begin{description}
\item[Type] composite: \xmlel{sia:Query}
\item[Meaning]
a set of query parameters that is expected
to produce at least one matched record which
can be used to test the service.
\item[Occurrence] optional
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{SkySize}
The \xmlel{sia:SkySize} type is used to capture simple rectangular extents on
the sky along longitudinal and latitudinal directions. It is defined as
follows:
% GENERATED: !schemadoc SIA-v1.2.xsd SkySize
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{sia:SkySize} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{sia:SkySize} Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{long}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
The maximum size in the longitude (R.A.) direction
given in degrees
\item[Occurrence] required
\end{description}
\item[Element \xmlel{lat}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
The maximum size in the latitude (Dec.) direction
given in degrees
\item[Occurrence] required
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{testQuery and the Query Type}
As with the other DAL \xmlel{vr:capability} types, the \xmlel{testQuery}
element is intended to help other VO components (e.g. registries,
validation services, services that monitor the VO's operational
health--but typically not end users) test that the service is up and
operating correctly. It provides a region of interest (plus optionally
additional parameters) to be used to get a non-empty result from the
service. For SIAv2, this region of interest would usually be translated
into a RANGE query.
Since this query is intended for testing purposes, the size of the
result set should be small.
The \xmlel{sia:Query} type captures the different components of the
query into separate elements, as defined below:
% GENERATED: !schemadoc SIA-v1.2.xsd Query
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{sia:Query} Type Schema Documentation}
\noindent{\small
A query to be sent to the service
\par}
\vspace{1ex}\noindent\textbf{\xmlel{sia:Query} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{sia:Query} Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{pos}]
\begin{description}
\item[Type] composite: \xmlel{sia:SkyPos}
\item[Meaning]
the center position of the rectangular region that
should be used as part of the query to the SIA service.
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{size}]
\begin{description}
\item[Type] composite: \xmlel{sia:SkySize}
\item[Meaning]
the rectangular size of the region that should be
used as part of the query to the SIA service.
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{verb}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
the verbosity level to use where 0 means the bare
minimum set of columns and 3 means the full set of
available columns.
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{extras}]
\begin{description}
\item[Type] string: \xmlel{xs:string}
\item[Meaning]
any extra (particularly non-standard) parameters that must
be provided (apart from what is part of base URL given by
the accessURL element).
\item[Occurrence] optional
\item[Comment]
this value should be in the form of name=value
pairs delimited with ampersands (\&).
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{SkyPos}
The \xmlel{sia:SkyPos} type is used to encode the \xmlel{testQuery}'s
\xmlel{pos} element, the center position of the test region of interest.
% GENERATED: !schemadoc SIA-v1.2.xsd SkyPos
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{sia:SkyPos} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{sia:SkyPos} Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{long}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
The sky position in the longitude (R.A.) direction
\item[Occurrence] required
\end{description}
\item[Element \xmlel{lat}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
The sky position in the latitude (Dec.) direction
\item[Occurrence] required
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{RegTAP Details Keys}
The following RegTAP \verb|res_details| keys are derived from the
SIAP capability type by mapping xpaths as defined by RegTAP; keys RegTAP
services must include in their tables if they are given in the registry
record are marked by an exclamation mark:
\begin{description}
\item[/capability/imageServiceType (!)]The class of image service: Cutout, Mosaic, Atlas, Pointed
\item[/capability/maxFileSize (!)]The maximum image file size in bytes
\item[/capability/maxImageExtent/lat]The maximum size in the latitude (Dec.) direction
\item[/capability/maxImageExtent/long]The maximum size in the longitude (R.A.) direction
\item[/capability/maxImageSize]A measure of the largest image the service can produce given as the maximum number of pixels along the first or second axes.
\item[/capability/maxQueryRegionSize/lat]The maximum size in the latitude (Dec.) direction
\item[/capability/maxQueryRegionSize/long]The maximum size in the longitude (R.A.) direction
\item[/capability/maxRecords (!)]The largest number of rows the image search will return
\item[/capability/testQuery/extras]Any extra (non-standard) parameters that must be provided (apart from what is part of base URL given by the accessURL element)
\item[/capability/testQuery/pos/lat]The Declination of the center of the search position in decimal degrees
\item[/capability/testQuery/pos/long]The Right Ascension of the center of the search position in decimal degrees
\item[/capability/testQuery/size/lat]Region size for a SIA test query in declination
\item[/capability/testQuery/size/long]Region size for a SIA test query in RA
\item[/capability/testQuery/verb]Verbosity of a service's test query
\end{description}
\subsection{Simple Spectral Access}
This section describes the SSA VOResource metadata extension schema
which is used to describe services that comply with the Simple Spectral
Access protocol, which primarily defines the
\xmlel{ssap:SimpleSpectralAccess}
\xmlel{vr:Capability} type to be used by services
compliant with published SSA Recommendation
\citep{2012ivoa.spec.0210T}.
\subsubsection{The Standard Identifier}
The \xmlel{standardID} value for Simple Spectral access version 1.1 (and
before) is
$$\hbox{\nolinkurl{ivo://ivoa.net/std/SSA} .}$$ Standard
identifiers for later versions will be given in the respective
standards.
\subsubsection{The Schema Namespace}
The namespace associated with the SSA extension schema is
\nolinkurl{http://www.ivoa.net/xml/SSA/v1.1}. The namespace prefix,
\xmlel{ssap:} should be used in applications where common use of
prefixes improves interoperability (e.g. in the IVOA registries).
Furthermore, we use the \xmlel{ssap:} prefix in this document to refer
to types defined as part of the SSA extension schema.
\begin{admonition}{Note}
Though it departs a bit from convention, the ssap prefix was
chosen to avoid a collision with its use in SSA for
identifying UTypes from the Spectral Data Model.
\end{admonition}
\subsubsection{SimpleSpectralAccess}
The \xmlel{ssap:SimpleSpectralAccess} type is the \xmlel{vr:Capability}
sub-type that should be used to describe a service's support for the
Simple Spectral Access protocol; it is defined as follows:
% GENERATED: !schemadoc SSA-v1.3.xsd SimpleSpectralAccess
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{ssap:SimpleSpectralAccess} Type Schema Documentation}
\noindent{\small
The capabilities of an SSA service implementation.
\par}
\vspace{1ex}\noindent\textbf{\xmlel{ssap:SimpleSpectralAccess} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{ssap:SimpleSpectralAccess} Extension Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{complianceLevel}]
\begin{description}
\item[Type] string with controlled vocabulary
\item[Meaning]
The category indicating the level to which
this instance complies with the SSA standard.
\item[Occurrence] required
\item[Terms]\hfil
\begin{longtermsdescription}
\item[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.
\item[minimal]
The service supports all of the capabilities and features
of the SSA protocol identified as {"}must{"} in the
specification.
\item[full]
The service supports all of the capabilities and features
of the SSA protocol identified as {"}must{"} or {"}should{"} in the
specification.
\end{longtermsdescription}
\item[Comment]
Allowed values are {"}query{"}, {"}minimal{"}, and {"}full{"}.
See definitions of allowed values for details.
\end{description}
\item[Element \xmlel{dataSource}]
\begin{description}
\item[Type] string with controlled vocabulary
\item[Meaning]
The category specifying where the data originally
came from.
\item[Occurrence] required; multiple occurrences allowed.
\item[Terms]\hfil
\begin{longtermsdescription}
\item[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.
\item[pointed]
A pointed observation of a particular astronomical object
or field.
\item[custom]
Data which has been custom processed, e.g., as part of
a specific research project.
\item[theory]
Theory data, or any data generated from a theoretical
model, for example a synthetic spectrum.
\item[artificial]
Artificial or simulated data.
\end{longtermsdescription}
\item[Comment]
Allowed values are {"}survey{"}, {"}pointed{"}, {"}custom{"},
{"}theory{"}, {"}artificial{"}
\end{description}
\item[Element \xmlel{creationType}]
\begin{description}
\item[Type] string with controlled vocabulary
\item[Meaning]
The category that describes the process used to
produce the dataset.
\item[Occurrence] required; multiple occurrences allowed.
\item[Terms]\hfil
\begin{longtermsdescription}
\item[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).
\item[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.
\item[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.
\item[mosaic]
Data from multiple non- or partially-overlapping datasets
are combined to produce a new dataset.
\item[projection]
Data is geometrically warped or dimensionally reduced by
projecting through a multidimensional dataset.
\item[spectralExtraction]
Extraction of a spectrum from another dataset, e.g.,
extraction of a spectrum from a spectral data cube
through a simulated aperture.
\item[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).
\end{longtermsdescription}
\item[Comment]
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.
\item[Comment]
Allowed values are {"}archival{"}, {"}cutout{"}, {"}filtered{"},
{"}mosaic{"}, {"}projection{"}, {"}spectralExtraction{"},
{"}catalogExtraction{"}
\end{description}
\item[Element \xmlel{supportedFrame}]
\begin{description}
\item[Type] string: \xmlel{xs:token}
\item[Meaning]
Identifiers of spatial reference frames that can be used
in the POS parameter. The identifiers must be taken
from the vocabulary http://www.ivoa.net/rdf/refframe.
\item[Occurrence] required; multiple occurrences allowed.
\item[Comment]
At least one recognized value must be listed
when the service supports POS.
With SSA v1.1, ICRS must be supported in that
case; thus,
this list must include at least this value.
\end{description}
\item[Element \xmlel{maxSearchRadius}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
The largest search radius, in degrees, that will be
accepted by the service without returning an error
condition. Not providing this element or
specifying a value of 180 indicates that there
is no restriction.
\item[Occurrence] optional
\item[Comment]
Not providing a value is the prefered way to indicate
that there is no restriction.
\end{description}
\item[Element \xmlel{maxRecords}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
The hard limit on the largest number of records that
the query operation will return in a single response.
Not providing this value means that there is no
effective limit.
\item[Occurrence] optional
\item[Comment]
This does not refer to the total number of spectra in
the archive but rather maximum number of records the
service is capable of returning. A limit that is
greater than the number of spectra available in the
archive is equivalent to their being no effective
limit. (See RM, Hanisch 2007.)
\end{description}
\item[Element \xmlel{defaultMaxRecords}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
The largest number of records that the service will
return when the MAXREC parameter not specified
in the query input. Not providing a value means
that the hard limit implied by maxRecords will be
the default limit.
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{maxAperture}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
The largest aperture that can be supported upon
request via the APERTURE input parameter by a
service that supports the spectral extraction
creation method. A value of 180 or not providing
a value means there is no theoretical limit.
\item[Occurrence] optional
\item[Comment]
Not providing a value is the preferred way to
indicate that there is no limit.
\end{description}
\item[Element \xmlel{maxFileSize}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
The maximum spectrum file size in bytes that will
be returned. Not providing
a value indicates that there is no effective limit
the size of files that can be returned.
\item[Occurrence] optional
\item[Comment]
This is primarily relevant when spectra are created
on the fly (see creationType). If the service
provides access to static spectra, this should only
be specified if there are spectra in the archive that
can be searched for but not returned because they are
too big.
\end{description}
\item[Element \xmlel{testQuery}]
\begin{description}
\item[Type] composite: \xmlel{ssap:Query}
\item[Meaning]
a set of query parameters that is expected to
produce at least one matched record which can be
used to test the service.
\item[Occurrence] optional
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
The custom metadata that the \xmlel{ssap:SimpleSpectralAccess} type provides is
given above. Note that some of these elements derive from
the SSA standard; others, from the RM standard \citep{2007ivoa.spec.0302H}.
The ``Semantic Meaning'' entry provides the reference to the original
definition.
\subsubsection{testQuery and the Query Type}
As with the other DAL \xmlel{vr:capability} types, the \xmlel{testQuery} element is
intended to help other VO components (e.g. registries, validation
services, services that monitor the VO's operational health -- but
typically not end users) test that the service is up and operating
correctly. It provides a set of legal input parameters that should
return a legal response that includes at least matched record. Since
this query is intended for testing purposes, the size of the result set
should be small.
The \xmlel{ssap:Query} type captures the different components of the
query into separate elements, as defined below:
% GENERATED: !schemadoc SSA-v1.3.xsd Query
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{ssap:Query} Type Schema Documentation}
\noindent{\small
A query to be sent to the service
\par}
\vspace{1ex}\noindent\textbf{\xmlel{ssap:Query} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{ssap:Query} Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{pos}]
\begin{description}
\item[Type] composite: \xmlel{ssap:PosParam}
\item[Meaning]
the center position the search cone given in
decimal degrees.
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{size}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
the size of the search radius.
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{queryDataCmd}]
\begin{description}
\item[Type] string: \xmlel{xs:string}
\item[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{"}.
\item[Occurrence] optional
\item[Comment]
This value must be in the form of name=value
pairs delimited with ampersands (\&). A query
may then be formed by appending to the base URL the
request argument, {"}REQUEST=queryData\&{"}, followed
by the contents of this element.
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{PosParam}
The \xmlel{ssap:PosParam} type is used to encode the \xmlel{testQuery}'s
\xmlel{pos} element, the center position of the test region of interest;
it is defined as follows:
% GENERATED: !schemadoc SSA-v1.3.xsd PosParam
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{ssap:PosParam} Type Schema Documentation}
\noindent{\small
a position in the sky to search.
\par}
\vspace{1ex}\noindent\textbf{\xmlel{ssap:PosParam} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{ssap:PosParam} Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{long}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
The longitude (e.g. Right Ascension) of the center of the
search position in decimal degrees.
\item[Occurrence] required
\end{description}
\item[Element \xmlel{lat}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
The latitude (e.g. Declination) of the center of the
search position in decimal degrees.
\item[Occurrence] required
\end{description}
\item[Element \xmlel{refframe}]
\begin{description}
\item[Type] string: \xmlel{xs:token}
\item[Meaning]
the coordinate system reference frame name indicating
the frame to assume for the given position. If not
provided, ICRS is assumed.
\item[Occurrence] optional
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{RegTAP Details Keys}
The following RegTAP \verb|res_details| keys are derived from the
SSAP capability type by mapping xpaths as defined by RegTAP; keys RegTAP
services must include in their tables if they are given in the registry
record are marked by an exclamation mark:
\begin{description}
\item[/capability/complianceLevel]The category indicating the level to which this instance complies with the SSA standard
\item[/capability/creationType (!)]The category that describes the process used to produce the dataset; one of archival, cutout, filtered, mosaic, projection, specialExtraction, catalogExtraction
\item[/capability/dataSource (!)]The category specifying where the data originally came from; one of survey, pointed, custom, theory, artificial
\item[/capability/defaultMaxRecords (!)]The largest number of records that the service will return when the MAXREC parameter is not specified in the query input
\item[/capability/maxAperture]The largest aperture that can be supported upon request via the APERTURE input parameter by a service that supports the special extraction creation method
\item[/capability/maxRecords (!)]The largest number of items (records, rows, etc.) that the service will return
\item[/capability/maxSearchRadius (!)]The largest search radius, in degrees, that will be accepted by the service without returning an error condition. Not providing this element or specifying a value of 180 indicates that there is no restriction
\item[/capability/supportedFrame (!)]The STC name for a world coordinate system frame supported by this service
\item[/capability/testQuery/pos/lat]The Declination of the center of the search position in decimal degrees
\item[/capability/testQuery/pos/long]The Right Ascension of the center of the search position in decimal degrees
\item[/capability/testQuery/pos/refframe]A coordinate system reference frame name for a test query. If not provided, ICRS is assumed
\item[/capability/testQuery/queryDataCmd]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
\item[/capability/testQuery/size]The size of the search radius in an SSA search query
\end{description}
\subsection{Simple Line Access}
This section describes the SLA VOResource metadata extension schema
which is used to describe services that comply with the Simple Line
Access protocol \citep{2010ivoa.specQ1209O}.
\subsubsection{The Standard Identifier}
The \xmlel{standardID} value for Simple Line Access version 1.0
is
$$\hbox{\nolinkurl{ivo://ivoa.net/std/SLAP} .}$$ Standard
identifiers for later versions will be given in the respective
standards.
\subsubsection{The Schema Namespace}
The namespace associated with the SLA extension schema is
\nolinkurl{http://www.ivoa.net/xml/SLAP/v1.0}. The namespace prefix,
\xmlel{slap:}, should be used in applications where common use of
prefixes improves interoperability (e.g. in the IVOA registries).
Furthermore, we use the \xmlel{slap:} prefix in this document to refer
to types defined as part of the SLA extension schema.
\subsubsection{SimpleLineAccess}
The \xmlel{slap:SimpleLineAccess} type is a \xmlel{vr:Capability}
sub-type that should be used to describe a service's support for the
Simple Line Access protocol; it is defined as follows:
% GENERATED: !schemadoc SLAP-v1.1.xsd SimpleLineAccess
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{slap:SimpleLineAccess} Type Schema Documentation}
\noindent{\small
The capabilities of an SLAP service implementation.
\par}
\vspace{1ex}\noindent\textbf{\xmlel{slap:SimpleLineAccess} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{slap:SimpleLineAccess} Extension Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{complianceLevel}]
\begin{description}
\item[Type] string with controlled vocabulary
\item[Meaning]
The category indicating the level to which this
service instance complies with the SLAP standard.
\item[Occurrence] required
\item[Terms]\hfil
\begin{longtermsdescription}
\item[minimal]
The service supports all of the capabilities and features
of the SLAP protocol identified as {"}must{"} in the
specification.
\item[full]
The service supports, at a minimum, all of the capabilities
and features of the SLAP protocol identified as {"}must{"} or
{"}should{"} in the specification.
\end{longtermsdescription}
\item[Comment]
Allowed values are {"}minimal{"} and {"}full{"}.
See definitions of allowed values for details.
\end{description}
\item[Element \xmlel{dataSource}]
\begin{description}
\item[Type] string with controlled vocabulary
\item[Meaning]
The category specifying where the data accessed by
the service originally came from.
\item[Occurrence] required
\item[Terms]\hfil
\begin{longtermsdescription}
\item[observational/astrophysical]
Lines observed and identified in real spectra of
astrophysical observations by different
instrument/projects
\item[observational/laboratory]
Lines observed and identified in real spectra of
laboratory measurements
\item[theoretical]
Servers containing theoretical spectral lines
\end{longtermsdescription}
\item[Comment]
Allowed values are {"}observational/astrophysical{"},
{"}observational/laboratory{"}, {"}theoretical{"}
\end{description}
\item[Element \xmlel{maxRecords}]
\begin{description}
\item[Type] \xmlel{xs:positiveInteger}
\item[Meaning]
The hard limit on the largest number of records that
the query operation will return in a single response.
Not providing this value means that there is no
effective limit.
\item[Occurrence] optional
\item[Comment]
This does not refer to the total number of spectra in
the archive but rather maximum number of records the
service is capable of returning. A limit that is
greater than the number of spectra available in the
archive is equivalent to their being no effective
limit. (See RM, Hanisch 2007.)
\end{description}
\item[Element \xmlel{testQuery}]
\begin{description}
\item[Type] composite: \xmlel{slap:Query}
\item[Meaning]
A set of queryData parameters that is expected to
produce at least one matched record which can be
used to test the service.
\item[Occurrence] optional
\item[Comment]
The value should include all parameters required
for the test query but should exclude the baseURL
and the REQUEST parameter.
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{testQuery and the Query Type}
As with the other DAL \xmlel{vr:capability} types, the \xmlel{testQuery} element is
intended to help other VO components (e.g. registries, validation
services, services that monitor the VO's operational health -- but
typically not end users) test that the service is up and operating
correctly. It provides a set of legal input parameters that should
return a legal response that includes at least matched record. Since
this query is intended for testing purposes, the size of the result set
should be small.
The \xmlel{slap:Query} type captures the different components of the
query into separate elements, as defined below:
% GENERATED: !schemadoc SLAP-v1.1.xsd Query
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{slap:Query} Type Schema Documentation}
\noindent{\small
A query to be sent to the service, e.g., a test query.
\par}
\vspace{1ex}\noindent\textbf{\xmlel{slap:Query} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{slap:Query} Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{wavelength}]
\begin{description}
\item[Type] composite: \xmlel{slap:WavelengthRange}
\item[Meaning]
Spectral range in meters to be used to constrain the query
of spectral lines.
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{queryDataCmd}]
\begin{description}
\item[Type] string: \xmlel{xs:string}
\item[Meaning]
Fully specified queryData test query formatted as an URL
argument list in the syntax specified by the SLAP standard.
The list must exclude the REQUEST argument which is
assumed to be set to {"}queryData{"}. VERSION may be
included if the test query applies to a specific version
of the service protocol.
\item[Occurrence] optional
\item[Comment]
If queryDataCmd is used to form a query, the default
value of WAVELENGTH specified above is not
used; if the test query requires WAVELENGTH it
should be included directly in queryDataCmd.
\item[Comment]
This value must be a string in the form of name=value
pairs delimited with ampersands (\&). A query may
then be formed by appending to the baseURL the request
argument, {"}REQUEST=queryData\&{"}, followed by the
contents of this element.
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{WavelengthRange}
The \xmlel{slap:WavelengthRange} type is used to encode the \xmlel{testQuery}'s
\xmlel{wavelength} element, the range of wavelengths to search.
% GENERATED: !schemadoc SLAP-v1.1.xsd WavelengthRange
\begin{generated}
\begingroup
\renewcommand*\descriptionlabel[1]{%
\hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{slap:WavelengthRange} Type Schema Documentation}
\noindent{\small
Spectral range in meters to be used to constrain the query
of spectral lines
\par}
\vspace{1ex}\noindent\textbf{\xmlel{slap:WavelengthRange} Type Schema Definition}
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
\end{lstlisting}
\vspace{0.5ex}\noindent\textbf{\xmlel{slap:WavelengthRange} Metadata Elements}
\begingroup\small\begin{bigdescription}\item[Element \xmlel{minWavelength}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
Minimum wavelength in meters to be used to constrain the query
of spectral lines
\item[Occurrence] optional
\end{description}
\item[Element \xmlel{maxWavelength}]
\begin{description}
\item[Type] floating-point number: \xmlel{xs:double}
\item[Meaning]
Maximum wavelength in meters to be used to constrain the query
of spectral lines
\item[Occurrence] optional
\end{description}
\end{bigdescription}\endgroup
\endgroup
\end{generated}
% /GENERATED
\subsubsection{RegTAP Details Keys}
The following RegTAP \verb|res_details| keys are derived from the
SLAP capability type by mapping xpaths as defined by RegTAP; keys RegTAP
services must include in their tables if they are given in the registry
record are marked by an exclamation mark:
\begin{description}
\item[/capability/complianceLevel (!)] The level to which this service instance complies with SLAP standard
\item[/capability/dataSource (!)] The means that were used to generate the data published (see schema for the values allowed here)
\item[/capability/maxRecords (!)] The largest number of lines the service will return
\item[/capability/testQuery/queryDataCmd] A URL argument list for a test query returning at least one line
\item[/capability/testQuery/wavelength/maxWavelength] Upper end of a spectral range that returns at least one line
\item[/capability/testQuery/wavelength/minWavelength] Lower end of a spectral range that returns at least one line
\end{description}
\section{Auxiliary Capabilities for Simple DAL Protocols}
The endorsed note on discovering data collections DDC
\citep{2019ivoa.rept.0520D} defines a method for separating metadata on
the service that publishes one or more data collections from the
metadata of these data collections themselves. This is particularly
useful when, for instance, a single SSAP service publishes spectra from
multiple experiments, surveys, or simulations. In this situations,
publishers SHOULD register each data collection contained in a separate
record as defined by DDC, and have one record for the service itself as
specified here.
By DDC, the records for the data collections have to contain capability
elements with special, bespoke \xmlel{standardID} values. For the
capabilities described here, the corresponding auxiliary standardIDs
are:
\begin{description}
\item[SCS version 1] \verb|ivo://ivoa.net/std/ConeSearch#aux|
\item[SIAP version 1] \verb|ivo://ivoa.net/std/SIA#aux|
\item[SSAP version 1] \verb|ivo://ivoa.net/std/SSA#aux|
\item[SLAP version 1] \verb|ivo://ivoa.net/std/SLAP#aux|
\end{description}
While, contrary to the authority and path parts, the fragment
part of ivoids is in principle case-sensitive, for ease of
implementation we guarantee that no standard keys will be admitted to
the resource records affected here that, when lowercased, would clash
with the keys in the above identifiers. Clients may thus normalise
SimpleDALRegExt standardIDs by lowercasing them as a whole without a
prior parsing step.
\appendix
\section{Supporting Multiple Versions of DAL Protocols}
This section is non-normative.
It is possible for a VOResource-encoded resource description to
indicate support for multiple versions of standard service. This is
described in general terms in Section~2.2.2 (``The service data model'') of the
VOResource specification \citep{2008ivoa.spec.0222P}. In that section, the
specification says that a \xmlel{capability} element can contain multiple
\xmlel{interface} elements, each describing a different version.
In VO practice, in particular after the publication of StandardsRegExt
\citep{2012ivoa.spec.0508H}, it turned out that declaring support
of particular versions of IVOA
standards (typically) happens with different capabilities, each with a
different \xmlel{standardID}, rather than providing multiple interface
elements with differing \xmlel{version} attributes as originially
envisioned.
Here is an example a service that supports both SIA versions 1.0 and
2.0, as well as a web browser interface on the 1.0 endpoint:
\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
Example Image Service
[...]
http://example.com/asvc/sia.xml?
GET
application/x-votable+xml
POS
ICRS Position, RA,DEC decimal degrees
[... enumerate the parameters supported ...]
http://example.com/asvc/form.html
Pointed
1000000
230.444
52.929
0.1
0.1
http://example.com/asvc/sia2.xml?
GET
application/x-votable+xml
POS
Specification of a region of...
[... enumerate the parameters supported for SIAv2...]
Pointed
10000
230.444
52.929
0.1
0.1
\end{lstlisting}
\section{Change History}
\subsection{Changes from PR-2020-12-16}
Backing out of productType in SSAP: the vocabulary it needs is harder to
write than was to be expected, and takeup during RFC was very limited.
\subsection{Changes from WD-2020-04-24}
Editorial changes only.
\subsection{Changes from WD-2020-02-12}
\begin{itemize}
\item Added res\_details keys from RegTAP's appendix A and stating that
we are now authoritative for these.
\item Added support for declaring productType in SSAP.
\end{itemize}
\subsection{Changes from REC-1.1}
\begin{itemize}
\item Added auxiliary ids for the standard ids covered.
\item Added language stressing the need for case-insensitive comparsions.
\item Dropped the SpaceFrame type, pointing to the relevant vocabulary
instead. While this is, in principle, an incompatible change as the
vocabulary is a good deal smaller than what SpaceFrame listed, no actual
SSA record in the VO ever used one of the dropped identifiers. Also,
clarifying that theoretical services don't have to give frames when
they don't support POS. [in schema @version=1.3-wd1]
\item Dropped ProtoSpectralAccess type. Again, this is an incompatible
change justified by the fact that no registered service uses this any
more.
\end{itemize}
\subsection{Changes from PR-2016-11-24}
Only editorial changes.
\subsection{Changes from PR-2016-07-06}
\begin{itemize}
\item References to auxiliary SIAv2 capabilities removed again.
\item Clarification that future standards are expected to override these
regulations.
\item Clarifications in the explanation of multi-version declarations,
and how to interpret TestQuery for SIAv2.
\end{itemize}
\subsection{Changes from REC-1.0}
\begin{itemize}
\item \xmlel{standardID} values are no longer fixed for the various
capability types.
\item Now giving the \xmlel{standardID} values of the existing standards
in the text (since they are no longer in the schema).
\item XML schemas are no longer included in the document; the files in
the IVOA repository are declared authoritative.
\item We now claim, essentially, to describe the S-protocol metadata
schemas until the respective standards define one themselves.
\item Updated example in the appendix to the style of Identifiers 2.0
\item Mentioning auxiliary capabilities and giving a standard id for
them.
\item Removing most material on ProtoSpectralAccess.
\end{itemize}
\subsection{Changes since PR-v1.0 20130911}
\begin{itemize}
\item none other than date and status.
\end{itemize}
\subsection{Changes from PR-v1.0 20121116}
\begin{itemize}
\item for SSA's creationType, changed specialExtraction to
spectralExtraction.
\item corrected Creation Type reference to section in SSA doc.
\item made long and lat elements in ssap:PosParam required.
\item incremented SSA schema version to 1.1 in namespace.
\item refresh App. A from official schemas
\item fixed typos (``IRCS'' and value type for maxFileSize)
\item noted that the and values within the sia:SkySize type
are given in degrees.
\item Fixed documentation of SIA's sia:Query type in the schema.
\end{itemize}
\subsection{Changes from PR-v1.0 20120517}
\begin{itemize}
\item The namespace URIs given in Sections 3.1.1, 3.2.1, 3.3.1, and 3.4.1
were updated to match that specified in the XSDs (i.e. to include a
``v'' preceding the version field).
\item Several capability metadata with types xs:int and xs:float were
changed to xs:positive\-Integer xs:double to allow for larger/more
precise numbers.
\item Capability metadata that indicated maximum allowed values (e.g.
, , etc.) were made optional to avoid
large, meaningless numbers from being provided. Now not specifying
a value is the preferred way to indicate that no upper limit
applies.
\item Semantic definition of sia:maxImageExtent clarified to
differentiate it from sia:max\-QueryRegionSize
\item The type for was changed to xs:positiveInteger,
a single number that represents the length of a side in pixels. The
sia:ImageSize type (no longer needed) was dropped.
\item The version field in the SIA namespace was incremented to 1.1 due
to the non-backward-compatible change to
\item various typos and grammatical errors corrected.
\end{itemize}
\subsection{Changes from WD-v1.0 20110921}
\begin{itemize}
\item Now recommend ssap as prefix; changed all occurances of ssa in text
and schema.
\item added to ssap:SimpleSpectralAccess
\item removed import of VODataService schema from SIA, SSA, and
Conesearch schemas.
\item change base type of controlled vocab types from xs:string to
xs:token for consistancy with VOResource.
\end{itemize}
\bibliography{ivoatex/ivoabib,ivoatex/docrepo}
\end{document}