\documentclass[11pt,a4paper]{ivoa} \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/JesusDelago]{Jesus Delago} \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{Ray Plante} \editor{Markus Demleitner} \previousversion[http://ivoa.net/documents/SimpleDALRegExt/20160525/]{ WD-20160525} \previousversion[http://www.ivoa.net/Documents/SimpleDALRegExt/20131005/]{ REC-1.0} \previousversion[http://www.ivoa.net/Documents/SimpleDALRegExt/20130911/]{PR-20130911} \previousversion[http://www.ivoa.net/Documents/SimpleDALRegExt/20121116/]{PR-2012116} \previousversion[http://www.ivoa.net/Documents/SimpleDALRegExt/20120517/]{PR-20120517} \previousversion[http://www.ivoa.net/Documents/SimpleDALRegExt/20110921/]{WD-20110921} \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{note:schemaversioning}. 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. \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 selected, say, for their relevence to a scientific topic which support that protocol. The results collected from those services, in effect then, represent all the relevent 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{2009ivoa.spec.1104B} -- 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{2011ivoa.spec.0531G}. \subsection{The Role in IVOA Architecture} \begin{figure} \centering \includegraphics[width=0.9\textwidth]{archdiag.png} \caption{SimpleDALRegExt in the IVOA Architecture} \label{fig:archdiag} \end{figure} The IVOA Architecture \citep{note:VOARCH} 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.03 \citep{2008ivoa.spec.0222P}] 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.04 \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.0 \citep{2009ivoa.spec.1104B}] 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.0 \citep{2011ivoa.spec.0531G}] 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. \end{bigdescription} Unlike with the previously mentioned specifications, this specification may apply to later versions of the RI and VOSI standards. \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. \begin{admonition}{Note} In VO practice, many clients 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"|. Resource record authors therefore should 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 \texttt{"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 \texttt{"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 \texttt{"GET"} and \texttt{"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 canoncical 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 on 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 service 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 \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[Allowed Values]\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 \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.2.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[Allowed Values]\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[Allowed Values]\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[Allowed Values]\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 with controlled vocabulary \item[Meaning] The STC name for a world coordinate system frame supported by this service. \item[Occurrence] required; multiple occurrences allowed. \item[Allowed Values]\hfil \begin{longtermsdescription} \item[FK4] the Fundemental Katalog, system 4, frame; Besselian \item[FK5] the Fundemental Katalog, system 5, frame; Julien \item[ECLIPTIC] Ecliptic coordinates \item[ICRS] International Celestial Reference System \item[GALACTIC\_I] old Galactic coordinates \item[GALACTIC\_II] old Galactic coordinates \item[SUPER\_GALACTIC] Super-galactic coordinates with the north pole at GALACTIC\_II (47.37, +6.32) and the origin at GALACTIC\_II (137.37, 0). \item[AZ\_EL] The local azimuth and elevation frame where azimuth increases from north through east. \item[BODY] A generic solar system body-centered coordinate frame \item[GEO\_C] 3D Geographic (geocentric) coordinates where the magnitude is expressed as a geocentric distance \item[GEO\_D] 3D Geographic (geocentric) coordinates where the magnitude is expressed as an elevation above sea-level. \item[MAG] Geomagnetic coordinates. \item[GSE] Geocentric Solar Ecliptic coordinates \item[GSM] Geocentric Solar Magnetic coordinates \item[HGC] Heliographic coordinates (Carrington) \item[HGS] Heliographic coordinates (Stonyhurst) \item[HEEQ] Heliographic Earth Equatorial coordinates \item[HRTN] Heliographic Radial-Tangential-Normal coordinates \item[HPC] Helioprojective Cartesian coordinates \item[HPR] Helioprojective Polar coordinates \item[HCC] Heliocentric Cartesian coordinates \item[HGI] Heliographic Inertial coordinates \item[MERCURY\_C] Planteocentric coordinates on Mercury \item[VENUS\_C] Planteocentric coordinates on Venus \item[LUNA\_C] Selenocentric coordinates (for the Moon) \item[MARS\_C] Planteocentric coordinates on Mars \item[JUPITER\_C\_III] Planteocentric coordinates on Jupiter, system III \item[SATURN\_C\_III] Planteocentric coordinates on Saturn, system III \item[URANUS\_C\_III] Planteocentric coordinates on Uranus, system III \item[NEPTUNE\_C\_III] Planteocentric coordinates on Neptune, system III \item[PLUTO\_C] Planteocentric coordinates on Mercury \item[MERCURY\_G] Planteographic coordinates on Mercury \item[VENUS\_G] Planteographic coordinates on Venus \item[LUNA\_G] Selenographic coordinates (for the Moon) \item[MARS\_G] Planteographic coordinates on Mars \item[JUPITER\_G\_III] Planteographic coordinates on Jupiter, system III \item[SATURN\_G\_III] Planteographic coordinates on Saturn, system III \item[URANUS\_G\_III] Planteographic coordinates on Uranus, system III \item[NEPTUNE\_G\_III] Planteographic coordinates on Neptune, system III \item[PLUTO\_G] Planteographic coordinates on Mercury \item[UNKNOWN] a frame that is either unknown or non-standard \end{longtermsdescription} \item[Comment] At least one recognized value must be listed. With SSA v1.1, ICRS must be supported; 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.2.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.2.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{ProtoSpectralAccess} \label{sect:protossa} The \xmlel{ssap:ProtoSpectralAccess} type still defined in the schema was intended for seamless migration of services predating the SSAP specification. It should no longer be used. \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[Allowed Values]\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[Allowed Values]\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 \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-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:positiveInterger 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 clarified to differentiate it from \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}