/[volute]/trunk/projects/dal/SCS/SCS.tex
ViewVC logotype

Contents of /trunk/projects/dal/SCS/SCS.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4182 - (show annotations)
Fri Jul 14 09:44:02 2017 UTC (4 years ago) by molinaro
File MIME type: application/x-tex
File size: 37664 byte(s)
scs: rewritten error response

1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
3
4 \usepackage{todonotes}
5
6 \usepackage{listings}
7 \lstloadlanguages{XML,sh}
8 \lstset{flexiblecolumns=true,tagstyle=\ttfamily,
9 showstringspaces=False}
10
11 \usepackage{multirow}
12
13 \title{Simple Cone Search}
14
15 \ivoagroup{Data Access Layer}
16
17 \author[http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante]{Raymond Plante}
18 \author[http://www.ivoa.net/twiki/bin/view/IVOA/MarcoMolinaro]{Marco Molinaro}
19 \author[http://www.ivoa.net/twiki/bin/view/IVOA/MarkusDemleitner]{Markus Demleitner}
20 \author[http://www.ivoa.net/twiki/bin/view/IVOA/BobHanisch]{Robert Hanisch}
21 \author[http://www.ivoa.net/twiki/bin/view/IVOA/AlexSzalay]{Alex Szalay}
22 \author[http://www.ivoa.net/twiki/bin/view/IVOA/RoyWilliams]{Roy Williams}
23
24 \editor{Ray Plante, Marco Molinaro}
25
26 \previousversion[http://www.ivoa.net/Documents/REC/DAL/ConeSearch-20080222.html]{REC 1.03}
27 \previousversion[http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20070914.html]{PR 2007-09-14}
28 \previousversion[http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20070628.html]{PR 2007-06-28}
29 \previousversion[http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20060908.html]{PR 2006-09-08}
30
31
32 \begin{document}
33 \begin{abstract}
34 This specification defines a simple query protocol, named Simple Cone Search (SCS or simply cone search hereafter), for retrieving records from a catalog of astronomical sources. The query describes a sky position and an angular distance, defining a cone on the sky. The response returns a list of astronomical sources from the catalog whose positions lie within the cone, formatted as a VOTable. This version aims essentially at aligning this specification with the Data Access Layer (DAL) landscape at the time of writing.
35 \end{abstract}
36
37
38 \section*{Acknowledgments}
39 This document was originally published as a document of the US National Virtual Observatory (NVO) \todo{check if the document or a link is still available} and then transcripted into an IVOA standards document format to became an IVOA recommendation. The changes made in this transcription and in the process of producing the first recommandation are reported in Appendix \ref{app:changes}.
40
41 The Simple Cone Search (SCS) version 1.03 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.
42
43 The SCS-1.1 revision has been developed under the ASTERICS project, supported by the European Commission Framework Programme Horizon 2020 Research and Innovation action, grant agreement n. 653477.
44
45 Work of the original authors of the Cone Search specification as well as the numerous data providers who have implemented and continue to support this protocol is kindly ackonwledged.
46
47 \section*{Conformance-related definitions}
48
49 The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
50 ``OPTIONAL'' (in upper or lower case) used in this document are to be
51 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
52
53 The \emph{Virtual Observatory (VO)} is a
54 general term for a collection of federated resources that can be used
55 to conduct astronomical research, education, and outreach.
56 The \href{http://www.ivoa.net}{International
57 Virtual Observatory Alliance (IVOA)} is a global
58 collaboration of separately funded projects to develop standards and
59 infrastructure that enable VO applications.
60
61
62 \section{Introduction}
63
64 This specification describes how a provider of an astronomical source catalog can publish that catalog to the Virtual Observatory in such a way that a simple cone search can be done. The data remains in the control of the data provider, served through a web server to the world, but the query profile and response profile are carefully controlled, as described below. It is intended that setting up this web service be simple enough that data providers will not have to spend too much time on it (their funding to support such services is typically small). At the same time, the service implementation and the data it provides can serve as a basis for more sophisticated tools.
65
66 This specification does not specify how cone search services are implemented, or how the data are stored or manipulated. The concern of this specification is how the data are exposed to the world through well-defined requests and responses.
67
68 This specification assumes that the data provider has already selected a catalog of astronomical sources. This catalog can be presented as a single table; it is expected that the table contains several columns.
69
70 \subsection{Role within the VO Architecture}
71
72 \begin{figure}
73 \centering
74
75 % Get the architecture diagram from the TCG chair
76 % http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG
77 % If they give you a PDF, for now dumb it down to a png by
78 % convert -antialias -density 72x72 archdiag.pdf archdiag.png
79 % Oh -- Notes don't need this; you'd have to remove archdiag.png
80 % from FIGURES in the Makefile, too.
81
82 \includegraphics[width=0.9\textwidth]{archdiag.png}
83 \caption{Architecture diagram for SCS - TODO}
84 \label{fig:archdiag}
85 \end{figure}
86
87 Fig.~\ref{fig:archdiag} shows the role this document plays within the
88 IVOA architecture \citep{note:VOARCH}.
89
90 \section{Resource}
91 \label{sec:resif}
92
93 A SCS service for accessing catalogue resources is implemented as a synchronous resource (as compliant as possible to the DALI specification, \citet{std:DALI}) that must meet the following requirements:
94 \begin{itemize}
95 \item the resource \textbf{must} respond to requests submitted using an HTTP GET query string, and may respond to HTTP POST query actions, as described in Sec.~\ref{sec:basepar};
96 \item the response, by default, \textbf{must} be a valid VOTable document, providing a table containing the sources of the catalogue whose positions are within the cone described in the query request (see Sec.~\ref{sec:response}); or
97 \item must return a stubbed VOTable in case of error, as described in Sec.~\ref{sec:error}.
98 \end{itemize}
99
100 \subsection{Query}
101 \label{sec:basepar}
102 The SCS service endpoint is represented by a \texttt{base\_url} formed by a \texttt{<base\_path>} and an optional \texttt{<base\_query>} of the form
103 $$\hbox{\nolinkurl{http://<server>/<base\_path>?<base\_query>} ,}$$
104 where \texttt{<base\_path>} is a URI-compliant component indicating the local location path and the \texttt{<base\_query>} may optionally be formed by locally supported query parameters; these latter are not recognized parts of the SCS protocol and thus are treated opaquely by clients of the service as part of the \texttt{base\_url}.\\
105 Note that when it contains extra GET arguments, the \texttt{base\_url} ends in an ampersand, \&; if there are no extra arguments, then it ends in a question mark, ?.\\
106 \begin{bigdescription}
107 \item[Examples] \nolinkurl{http://mycone.org/cgi-bin/VOsearch?}\\
108 \nolinkurl{http://adil.ncsa.uiuc.edu/vocone?resolv\&issurvey=T\&}
109 \end{bigdescription}
110 Every query to a given cone search service uses the same base URL.
111
112 Constraints to filter the catalogue are expressed as a list of ampersand-delimited GET arguments of the form: \texttt{<name>=<value>} where \texttt{<name>} is a parameter name specified by this specification and \texttt{<value>} is its value. The constraints represent the query parameters which can vary for each successive query. The order of the name-parameter pairs is not significant.
113
114 The \texttt{base\_url} and constraint list are concatenated to form the query.
115
116 In the case the SCS service accepts HTTP POST action for query, the \texttt{value=param} constraints must be passed on to the service as data in the request body, with \texttt{application/x-www-form-urlencoded} encoding type. Whether the \texttt{<base\_query>} parameters are accepted as POST parameters or not, is up to the service provider.\todo{There's currently no way to alert clients on SCS service POST capability. This poses a question on best practices here. Maybe allowing 1.03 baseURL but moving already towards a 1.1 PathParam only baseURL?} Mixed GET/POST queries are possible.
117
118 The set of query constraints a cone search needs to understand \textbf{must} include the \textbf{RA}, \textbf{DEC}, \textbf{SR} parameters, \textbf{should} include the \textbf{MAXREC} and \textbf{RESPONSEFORMAT} ones and \textbf{may} include the \textbf{VERB} one, all of which are to be interpreted with the following stated meaning and the DALI recommendations about parameters.
119
120 \subsubsection{RA}
121 \textbf{RA} represents a right-ascension in the ICRS coordinate system for the position of the center of the cone to search, given in decimal degrees. It is a single valued parameter and \textbf{must} be present in the query.
122
123 \subsubsection{DEC}
124 \textbf{DEC} represents a declination in the ICRS coordinate system for the position of the center of the cone to search, given in decimal degrees. It is a single value parameter and \textbf{must} be present in the query.
125
126 \subsubsection{SR}
127 \textbf{SR} represents the radius of the cone to search, given in decimal degrees. It is a single valued parameter and \textbf{must} be present in the query. If set to zero (SR=0) it should have the same effect as setting MAXREC=0, i.e. a service metadata request as prescribed by DALI\footnote{SR=0 is kept in this version of this specification for back compatibility. It is suggested to prefer the usage of MAXREC to enable metadata discovery}.
128
129 \subsubsection{MAXREC}
130 As defined by DALI a cone search \textbf{should} accept the \textbf{MAXREC} parameter to let the client limit the number of records returned or require a service metadata response (see above). Its usage is encouraged and preferred to the SR=0 solution for metadata discovery.
131
132 \subsubsection{RESPONSEFORMAT}
133 \label{subsubsec:responseformat}
134 An SCS service \textbf{must} provide responses in VOTable \citep{std:VOTABLE} format, compliant with respect to what will be detailed in Sec.~\ref{sec:response}, but \textbf{should} also support the DALI \textbf{RESPONSEFORMAT} parameter. Allowed media types for VOTable response \textbf{should} be the \texttt{application/x-votable+xml} or \texttt{text/xml} as specified by DALI but \texttt{text/xml;content=x-votable} may be considered legal for backward compatibility reasons.
135
136 \subsubsection{VERB}
137 The query \textbf{may} contain the optional single valued parameter, \textbf{VERB}, whose value is an integer (either 1, 2, or 3) indicating verbosity which determines how many columns are to be returned in the resulting table. If the service supports the parameter, then when the value is 1, the response should include the bare minimum of columns that the provider considers useful in describing the returned objects (while still remaining compliant with this standard; see section \ref{sec:response} below). When the value is 3, the service should return all of the columns that are available for describing the objects. A value of 2 is intended for requesting a medium number of columns between the minimum and maximum (inclusive) that are considered by the provider to most typically useful to the user. When the VERB parameter is not provided, the server should respond as if VERB=2. If the VERB parameter is not supported by the service, the service should ignore the parameter and should always return the same columns for every request.
138
139 There may be other parameters in the query, but this document does not specify their meaning or usage. If a query includes an optional parameter, either one specified by this document or not, that is not supported by the service implementation, the service must ignore that parameter.
140
141 A query following this syntax represents a request for information on sources located within the specified cone on the sky.
142
143 \subsection{Query examples}
144 \begin{bigdescription}
145 \item[Minimal SCS query] \nolinkurl{http://my.cone/search?RA=10.68\&DEC=41.26\&SR=0.01}
146 \item[Service Metadata query] \nolinkurl{http://my.cone/search?cat=A1\&RA=0\&DEC=0\&SR=0\&MAXREC=0}
147 \item[Limit number of records in response] \nolinkurl{http://my.cone/search?RA=10.68\&DEC=41.26\&SR=1\&MAXREC=100}
148 \item[Ask for the minimal set of response fields] \nolinkurl{http://my.cone/search?RA=10.68\&DEC=41.26\&SR=0.01\&VERB=1}
149 \end{bigdescription}
150
151 TODO\todo{add POST example?}
152
153 \section{Successful Response}
154 \label{sec:response}
155 A successful query \textbf{must} result in an HTTP response with status code 200 (OK) and a content that, by default, \textbf{must} be in VOTable format (version 1.0 or later), that represents a table of astronomical sources whose positions are within the cone (see Appendix \ref{app:responsesample} for an example)\todo{Example needs to be rebuild.}.
156
157 There may also be other sources outside the cone, the service implementor may decide on the exact search criterion used internally to the service to select the sources.
158
159 The response format may be other than VOTable when requested using the RESPONSEFORMAT query parameter described in Sec.~\ref{subsubsec:responseformat}. Mime-type of the response will vary accordingly to the output format, again as prescribed by DALI and reported in Sec.~\ref{subsubsec:responseformat}.
160
161 \subsection{VOTable compliant response}
162
163 In the of the default VOTable response, this \textbf{MUST} comply with the following requirements.
164
165 There \textbf{must} be a single \xmlel{RESOURCE} with \xmlel{type}=\texttt{"results"}\todo{Do current cone services use this attribute?} in the VOTable, and containing a single \xmlel{TABLE}\todo{should we relax on the number of tables?}.
166
167 The \xmlel{TABLE} \textbf{must} have \xmlel{FIELD}s where the following UCD values have been set. There \textbf{must} only be one \xmlel{FIELD} with each of these UCDs:
168 \begin{itemize}
169 \item \textbf{Exactly one} \xmlel{FIELD} \textbf{must} have \xmlel{ucd}=\texttt{"ID\_MAIN"}, with an array character type (fixed or variable length), representing an ID string for that record of the table. This identifier \textbf{may not} be repeated in the table, and it could be used to retrieve that same record again from that same table.
170 \item \textbf{Exactly one} \xmlel{FIELD}, representing the right ascension of the source in the ICRS coordinate system, \textbf{must} have \xmlel{ucd}=\texttt{"POS\_EQ\_RA\_MAIN"}, and have \xmlel{datatype} set to \texttt{"float"} or \texttt{"double"}.
171 \item \textbf{Exactly one} \xmlel{FIELD}, representing the declination of the source in the ICRS coordinate system, \textbf{must} have \xmlel{ucd}=\texttt{"POS\_EQ\_DEC\_MAIN"}, and have \xmlel{datatype} set to \texttt{"float"} or \texttt{"double"}.
172 \end{itemize}
173
174 The VOTable may include an expression of the uncertainty of the positions given in the above mentioned fields to be interpreted either as a positional error of the source positions, or an angular size if the sources are resolved. If this uncertainty is not provided, it should be taken to be zero; otherwise, it may be set for all table entries with a \xmlel{PARAM} in the \xmlel{RESOURCE} which has a UCD that is set to OBS\_ANG-SIZE and has a value which is the angle in decimal degrees. Alternatively, a different value for each row in the table can be given via a \xmlel{FIELD} in the table having a UCD set to OBS\_ANG-SIZE.
175 There may be other \xmlel{FIELD}s in the table. Their specification \textbf{should} include description, data-type, and UCD.\todo{A solution to move to UCD1+ would be nice, but it should probably be postponed to a major revision.}
176
177 \section{Error Response}
178 \label{sec:error}
179
180 If the service detects an exceptional condition, it \textbf{should} return an error document with an appropriate status code, as specified by DALI, with, possibly, a Content-Type header to tell the client the format of the document.
181
182 In the case the error is expressed in VOTable format, recommendation expressed in Section 4.4 of DALI (currently version 1.1) \textbf{should} be followed, inluding the overflow behaviour in the case the MAXREC parameter is in use.
183
184 Errors \textbf{must} be reported in case any one of the three required paramaters (RA, DEC, SR) is missing,
185 or if their values cannot be parsed to floating-point numbers, or if the numbers are out of range (DEC=91.0, for example).
186
187 The service \textbf{may} also return an error if the search radius (give by the SR parameter) is larger than the one set by the \xmlel{maxSR} element child of the \xmlel{capability} one of the service described as a VO resource (see Sec.~\ref{sec:regext}).
188
189 The service \textbf{may}, as an alternative, report exceptions using the profile expressed by the previous SCS recommendation \citep[v1.03]{std:SCS}. This alternative for error reporting is to be considered \textbf{deprecated}, being the purpose of this specification to fill in the gap of the SCS protocol with the general DAL landscape. The way the alternative works is detailed in Sec.~\ref{subsec:err103} here below.
190
191 \subsection{(\textbf{deprecated}) Alternative Error Response}
192 \label{subsec:err103}
193 In the case of error, the service \textbf{must} respond with a VOTable that contains a single \xmlel{PARAM} element or a single \xmlel{INFO} element with \xmlel{name}=\texttt{"Error"}, where the corresponding \xmlel{value} attribute should contain some explanation of the nature of the error. If an \xmlel{INFO} element is used, it must appear as a direct child of one of the following elements:
194 \begin{itemize}
195 \item the root \xmlel{VOTABLE} element (which is preferred by this document), or
196 \item the \xmlel{RESOURCE} element
197 \end{itemize}
198
199 If a \xmlel{PARAM} element is used, it must appear as a direct child of the \xmlel{RESOURCE} element.\todo{Removed reference to the DEFINITION element solution, definitely out of VOTable since long.} Please note that, apart from being deprecated here, the use of the \xmlel{PARAM} element to convey error response was already discouraged in the previous version of this specification.
200
201 \begin{bigdescription}
202 \item[Example Error Responses] Error INFO as child of VOTABLE (preferred)\\
203 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
204 <?xml version="1.0"?>
205 <!DOCTYPE VOTABLE SYSTEM "http://us-vo.org/xml/VOTable.dtd">
206 <VOTABLE version="1.0">
207 <DESCRIPTION>MAST Simple Cone Search Service</DESCRIPTION>
208 <INFO ID="Error" name="Error" value="Error in input RA value: as3f"/>
209 </VOTABLE>
210 \end{lstlisting}
211 Error PARAM as child of RESOURCE (allowed)
212 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
213 <?xml version="1.0"?>
214 <!DOCTYPE VOTABLE SYSTEM "http://us-vo.org/xml/VOTable.dtd">
215 <VOTABLE version="1.0">
216 <DESCRIPTION>
217 HEASARC Browse data service
218 Please send inquiries to mailto:request@athena.gsfc.nasa.gov
219 </DESCRIPTION>
220 <RESOURCE ID="error_resource">
221 <PARAM ID="Error" name="Error" datatype="char" arraysize="*"
222 value="Invalid data type: text/html"/>
223 </RESOURCE>
224 </VOTABLE>
225 \end{lstlisting}
226 \end{bigdescription}
227
228 Queries targeting no records \textbf{should not} generate an error response, but an empty metadata response.\todo{Does it make sense to keep this sentence, shortened from the previous version? MMo guess: no}
229
230 \section{Resource Registry Extension}
231 \label{sec:regext}
232
233 \begin{admonition}{Note}
234 The content of \textbf{Section \ref{sec:regext}} is taken from REC-SimpleDALRegExt-1.1, sections 1, 2 and 3, specifically section 3.1 that is dedicated to the Simple Cone Search case.
235 \end{admonition}
236
237 To adequately describe that a service supports the Simple Cone Search protocol, it is necessary to define SCS specific capability metadata. This is needed both to allow discovery of cone search services within VO registered resources (through the Registry Interfaces standard, \citet{std:RI1}, deploying VOResource documents, \citet{std:VOR}) and to generally describe service behaviour to help applications consume it properly, given compliance to the protocol.
238
239 This section specifies these metadata for cone search resources and is intended to be applicable wherever VOResource records are used, in particular for standard encoding of resource descriptions within IVOA registries and for encoding capability metadata available through VOSI \citep{std:VOSI11} interfaces.
240
241 Apart from the above standards referenced here above, this registry extension depends on the VODataService \citep{std:VODS11} standard.
242
243 \subsection{Resource record and Capability requirements}
244 To be recognized as a SCS, the service resource must be described as a resource of type \xmlel{vr:Service} (defined in the VOResource schema) or one of its legal sub-types. 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. SCS \textbf{should} be of the resource type \xmlel{vs:CatalogService} (defined in the VODataService extension schema)\footnote{\xmlel{vr:} and \xmlel{vs:} are the canonical prefixes for the namespaces associated with VOResource and VODataService XML schemata}.
245
246 Since the \xmlel{vs:CatalogService} resource type allows it, record authors are encouraged to include a full description of the columns in the table returned in query response (assuming full verbosity), as well as to provide sky coverage information.
247
248 \subsubsection{Capability}
249 The VOResource record \textbf{must} include a \xmlel{capability} element that \textbf{must} have a \xmlel{standardID} attribute set to
250 $$\hbox{\nolinkurl{ivo://ivoa.net/std/conesearch#query-1.1}}$$
251 to unambiguously identify the resource as a Simple Cone Search compliant to SCS-1.1 version. The \xmlel{capability} \textbf{should} also have \xmlel{xsi:type="cs:ConeSearch"} to specialize the \xmlel{vr:Capability} to be of the specific sub-type supporting the cone search protocols. The \xmlel{cs:} here refers to the canonical prefix for the namespace associated with the SCS extension schema, that is
252 $$\hbox{\nolinkurl{http://www.ivoa.net/xml/ConeSearch/v1.0} ,}$$
253 the same as for SCS-1.03, as explained in the XML Schema Versioning \citep{note:schemaversioning} document; distinction among the two schemata version being delivered by the \xmlel{version} attribute in the schema root element.
254
255 The \xmlel{cs:ConeSearch} type is described in Sec.~\ref{subsec:cstype}
256
257 \subsubsection{Interface}
258 The \xmlel{capability} element describing \textbf{must} include a child \xmlel{interface} element.
259 The \xmlel{interface} element \xmlel{xsi:type} attribute \textbf{must} be set to \texttt{vs:ParamHTTP}, and its \xmlel{role} attribute \textbf{must} be set to \texttt{"std"}. A \xmlel{accessURL} element within that
260 \xmlel{interface} \textbf{must} be set to the \xmlel{<base\_url>} of the service (see \ref{sec:basepar}).
261
262 It is not necessary to provide the \xmlel{use} attribute to the
263 \xmlel{accessURL} element (as its value can be assumed); however, when
264 it is provided, it must be set to \texttt{"base"}. Similarly, it is not
265 necessary to provide the \xmlel{interface} element with
266 \xmlel{queryType} or \xmlel{resultType} elements; however, when
267 provided, their values should be \texttt{"GET"} and
268 \texttt{"application/x-votable+xml"}, respectively. The
269 \xmlel{vs:ParamHTTP} allows one to describe input parameters supported
270 by the service; description authors are encouraged to list the optional
271 parameters and any custom parameters supported by the instance of the
272 service.
273
274 \subsubsection{\textit{cs:}ConeSearch}
275 \label{subsec:cstype}
276 The \xmlel{cs:ConeSearch} type is a \xmlel{vr:Capability} sub-type that should be used
277 to describe a service's support for the Simple Cone Search protocol;
278 it is defined as follows:
279
280 % GENERATED: !schemadoc ConeSearch-v1.1.xsd ConeSearch
281 \begin{generated}
282 \begingroup
283 \renewcommand*\descriptionlabel[1]{%
284 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{cs:ConeSearch} Type Schema Documentation}
285
286 \noindent{\small
287 The capabilities of a Cone Search implementation.
288 \par}
289
290 \vspace{1ex}\noindent\textbf{\xmlel{cs:ConeSearch} Type Schema Definition}
291
292 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
293 <xs:complexType name="ConeSearch" >
294 <xs:complexContent >
295 <xs:extension base="vr:Capability" >
296 <xs:sequence >
297 <xs:element name="maxSR" type="xs:float" minOccurs="0"
298 maxOccurs="1" />
299 <xs:element name="maxRecords" type="xs:positiveInteger"
300 minOccurs="0" maxOccurs="1" />
301 <xs:element name="verbosity" type="xs:boolean" />
302 <xs:element name="testQuery" type="cs:Query" minOccurs="0"
303 maxOccurs="1" />
304 </xs:sequence>
305 </xs:extension>
306 </xs:complexContent>
307 </xs:complexType>
308 \end{lstlisting}
309
310 \vspace{0.5ex}\noindent\textbf{\xmlel{cs:ConeSearch} Extension Metadata Elements}
311
312 \begingroup\small\begin{bigdescription}\item[Element \xmlel{maxSR}]
313 \begin{description}
314 \item[Type] floating-point number: \xmlel{xs:float}
315 \item[Meaning]
316 The largest search radius, in degrees, that will be
317 accepted by the service without returning an error
318 condition. Not providing this element or
319 specifying a value of 180 indicates that there
320 is no restriction.
321
322 \item[Occurrence] optional
323 \item[Comment]
324 Not providing a value is the prefered way to indicate
325 that there is no restriction.
326
327
328 \end{description}
329 \item[Element \xmlel{maxRecords}]
330 \begin{description}
331 \item[Type] \xmlel{xs:positiveInteger}
332 \item[Meaning]
333 The largest number of records that the service will
334 return. Not providing this value means that
335 there is no effective limit.
336
337 \item[Occurrence] optional
338 \item[Comment]
339 This does not refer to the total number of records in
340 the catalog but rather maximum number of records the
341 service is capable of returning. A limit that is
342 greater than the number of records available in the
343 archive is equivalent to their being no effective
344 limit. (See RM, Hanisch 2007.)
345
346
347 \end{description}
348 \item[Element \xmlel{verbosity}]
349 \begin{description}
350 \item[Type] boolean (true/false): xs:boolean
351 \item[Meaning]
352 True if the service supports the VERB keyword;
353 false, otherwise.
354
355 \item[Occurrence] required
356
357 \end{description}
358 \item[Element \xmlel{testQuery}]
359 \begin{description}
360 \item[Type] composite: \xmlel{cs:Query}
361 \item[Meaning]
362 A query that will result in at least one
363 matched record that can be used to test the
364 service.
365
366 \item[Occurrence] optional
367
368 \end{description}
369
370
371 \end{bigdescription}\endgroup
372
373 \endgroup
374 \end{generated}
375
376 % /GENERATED
377
378 The custom metadata that the \xmlel{cs:ConeSearch} type provides is given
379 above. Other genaral metadata useful to describe the SCS
380 specification are directly part of the core VOResource schema.
381
382 \subsubsection{testQuery and the Query Type}
383
384 The \xmlel{testQuery} element is intended to help other VO components (e.g.
385 registries, validation services, services that monitor the VO's
386 operational health, but typically not end users) test that the service
387 is up and operating correctly. It provides a set of legal input
388 parameters that should return a legal response that includes at least
389 one matched record. Since this query is intended for testing purposes,
390 the size of the result set should be small.
391
392 The \xmlel{cs:Query} type captures the different components of the query into
393 separate elements, as defined below:
394
395 % GENERATED: !schemadoc ConeSearch-v1.1.xsd Query
396 \begin{generated}
397 \begingroup
398 \renewcommand*\descriptionlabel[1]{%
399 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{cs:Query} Type Schema Documentation}
400
401 \noindent{\small
402 A query to be sent to the service
403 \par}
404
405 \vspace{1ex}\noindent\textbf{\xmlel{cs:Query} Type Schema Definition}
406
407 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
408 <xs:complexType name="Query" >
409 <xs:sequence >
410 <xs:element name="ra" type="xs:double" />
411 <xs:element name="dec" type="xs:double" />
412 <xs:element name="sr" type="xs:double" />
413 <xs:element name="verb" type="xs:positiveInteger" minOccurs="0" />
414 <xs:element name="catalog" type="xs:string" minOccurs="0" />
415 <xs:element name="extras" type="xs:string" minOccurs="0" />
416 </xs:sequence>
417 </xs:complexType>
418 \end{lstlisting}
419
420 \vspace{0.5ex}\noindent\textbf{\xmlel{cs:Query} Metadata Elements}
421
422 \begingroup\small\begin{bigdescription}\item[Element \xmlel{ra}]
423 \begin{description}
424 \item[Type] floating-point number: \xmlel{xs:double}
425 \item[Meaning]
426 the right ascension of the search cone's center in
427 decimal degrees.
428
429 \item[Occurrence] required
430
431 \end{description}
432 \item[Element \xmlel{dec}]
433 \begin{description}
434 \item[Type] floating-point number: \xmlel{xs:double}
435 \item[Meaning]
436 the declination of the search cone's center in
437 decimal degrees.
438
439 \item[Occurrence] required
440
441 \end{description}
442 \item[Element \xmlel{sr}]
443 \begin{description}
444 \item[Type] floating-point number: \xmlel{xs:double}
445 \item[Meaning]
446 the radius of the search cone in decimal degrees.
447
448 \item[Occurrence] required
449
450 \end{description}
451 \item[Element \xmlel{verb}]
452 \begin{description}
453 \item[Type] \xmlel{xs:positiveInteger}
454 \item[Meaning]
455 the verbosity level to use where 1 means the bare
456 minimum set of columns and 3 means the full set of
457 available columns.
458
459 \item[Occurrence] optional
460
461 \end{description}
462 \item[Element \xmlel{catalog}]
463 \begin{description}
464 \item[Type] string: \xmlel{xs:string}
465 \item[Meaning]
466 the catalog to query.
467
468 \item[Occurrence] optional
469 \item[Comment]
470 When the service can access more than one catalog,
471 this input parameter, if available, is used to
472 indicate which service to access.
473
474
475 \end{description}
476 \item[Element \xmlel{extras}]
477 \begin{description}
478 \item[Type] string: \xmlel{xs:string}
479 \item[Meaning]
480 any extra (non-standard) parameters that must be
481 provided (apart from what is part of base URL given
482 by the accessURL element).
483
484 \item[Occurrence] optional
485 \item[Comment]
486 this value should be in the form of name=value
487 pairs delimited with ampersands (\&).
488
489
490 \end{description}
491
492
493 \end{bigdescription}\endgroup
494
495 \endgroup
496 \end{generated}
497
498 \todo{attach xsd?}
499
500 \appendix
501 \section{Sample VOTable Response}
502 \label{app:responsesample}
503 This is a sample of a legal response to a Cone Search query.\todo{Needs to be changed}
504 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
505 <?xml version="1.0"?>
506 <!DOCTYPE VOTABLE SYSTEM "http://us-vo.org/xml/VOTable.dtd">
507 <VOTABLE version="1.0">
508 <DEFINITIONS>
509 <COOSYS system="eq_FK5" equinox="2000" />
510 </DEFINITIONS>
511 <RESOURCE ID="T9001">
512 <DESCRIPTION>
513 HEASARC Browse data service
514 Please send inquiries to mailto:request@athena.gsfc.nasa.gov
515 </DESCRIPTION>
516 <PARAM ID="default_search_radius" ucd="OBS_ANG-SIZE" datatype="double"
517 value="0.0516666666666667" />
518 <TABLE ID="heasarc_first_9001">
519 <DESCRIPTION> Faint Images of the Radio Sky at Twenty cm Source Catalog (FIRST) </DESCRIPTION>
520 <FIELD name="unique_id" datatype="char" arraysize="*" ucd="ID_MAIN">
521 <DESCRIPTION> Integer key </DESCRIPTION>
522 </FIELD>
523 <FIELD name="name" datatype="char" arraysize="*" >
524 <DESCRIPTION> FIRST Source Designation </DESCRIPTION>
525 </FIELD>
526 <FIELD name="ra" datatype="double" unit="degree" ucd="POS_EQ_RA_MAIN">
527 <DESCRIPTION> Right Ascension </DESCRIPTION>
528 </FIELD>
529 <FIELD name="dec" datatype="double" unit="degree" ucd="POS_EQ_DEC_MAIN">
530 <DESCRIPTION> Declination </DESCRIPTION>
531 </FIELD>
532 <FIELD name="flux_20_cm" datatype="double" unit="mJy" >
533 <DESCRIPTION> Peak 1.4GHz Flux Density (mJy) </DESCRIPTION>
534 </FIELD>
535 <FIELD name="flux_20_cm_error" datatype="double" unit="mJy" >
536 <DESCRIPTION> Estimated rms in at Source (mJy) </DESCRIPTION>
537 </FIELD>
538 <FIELD name="int_flux_20_cm" datatype="double" unit="mJy" >
539 <DESCRIPTION> Integrated 1.4GHz Flux Density (mJy) </DESCRIPTION>
540 </FIELD>
541 <DATA>
542 <TABLEDATA>
543 <TR>
544 <TD>384559</TD><TD>FIRST J120002.6+595708</TD>
545 <TD>180.0110042</TD><TD>59.9523889</TD>
546 <TD> 1.11</TD><TD> 0.139</TD><TD> 1.14</TD>
547 </TR>
548 <TR>
549 <TD>385094</TD><TD>FIRST J120025.3+600103</TD>
550 <TD>180.1057250</TD><TD>60.0175556</TD>
551 <TD> 2.89</TD><TD> 0.142</TD><TD> 2.56</TD>
552 </TR>
553 <TR>
554 <TD>384928</TD><TD>FIRST J120018.1+600236</TD>
555 <TD>180.0755500</TD><TD>60.0434750</TD>
556 <TD> 19.38</TD><TD> 0.145</TD><TD> 19.23</TD>
557 </TR>
558 <TR>
559 <TD>384490</TD><TD>FIRST J115959.4+600403</TD>
560 <TD>179.9978875</TD><TD>60.0677083</TD>
561 <TD> 1.01</TD><TD> 0.147</TD><TD> 1.20</TD>
562 </TR>
563 </TABLEDATA>
564 </DATA>
565 </TABLE>
566 </RESOURCE>
567 </VOTABLE>
568 \end{lstlisting}
569
570 \section{Changes from Previous Versions}
571 \label{app:changes}
572
573 \subsection{Changes from REC-1.03}
574 \begin{itemize}
575 \item changed resource metadata importing directly from SimpleDALRegExt
576 \item relaxed RA and Dec FIELDs in response to allow float or double datatype
577 \item no more exactly one RESOURCE in response, now stating exactly one of type="results"
578 \item removed fixed version (1.0 or 1.1) for VOTable default response
579 \item Added DALI MAXREC and RESPONSEFORMAT
580 \item Added POST as optional HTTP query method
581 \item Addition of authors/editors.
582 \item Plain porting of the HTML document into ivoatex template, including change history, then modified it and reshaped.
583 \end{itemize}
584
585 \subsection{Changes from PR-1.02}
586 \begin{itemize}
587 \item converted to Recommendation
588 \end{itemize}
589
590 \subsection{Changes from PR-1.01}
591 \begin{itemize}
592 \item eliminated the choice of encoding an ERROR response in a PARAM that is a direct child of VOTABLE as this is not legal in the VOTable schema.
593 \item Allowed the use of the INFO element for error messages.
594 \item In examples, made sure PARAM elements have datatype attributes
595 \item Corrected wording to be definitive that positions are given in the ICRS coordinate system.
596 \item Other typos.
597 \end{itemize}
598
599 \subsection{Changes from PR-1.00}
600 \begin{itemize}
601 \item Various typos.
602 \item Clarified description of VERB parameter:
603 \begin{itemize}
604 \item Clarified what is meant by optional for client and server.
605 \item Clarified the meaning of the values.
606 \end{itemize}
607 \item Explicitly mention the 3 legal locations for ERROR messages.
608 \item Refer to string types as character arrays, as per the VOTable std.
609 \item Prefers text/xml;content=x-votable over text/xml;votable.
610 \item Added examples of error message, legal response in appendix.
611 \end{itemize}
612
613 \subsection{Changes from the original NVO Specification Document}
614 \begin{itemize}
615 \item References to the original HTML document have been replaced with references to this IVOA specification.
616 \item Replaced references to "curator" with "data provider" or similar wording.
617 \item Replaced references to the NVO with references either to the IVOA or this specification, as appropriate.
618 \item Ambiguous language like "perhaps" has been replaced with more definitive wording where appropriate. Use of the word "will" is replaced with "must" and "can" with "may", in accordance with the definitions set in the preface.
619 \item Grammatical and spelling corrections have been made.
620 \item The content is organized into sections typical of an IVOA spec.
621 \item Description of the URL syntax is sharper, borrowing language from the SIA specification [SIA]. This includes:
622 \begin{itemize}
623 \item More explicitly specifying the form of the URL.
624 \item Sharpening the definition of the input parameters.
625 \item Indicating that parameter order is not significant.
626 \item Stating explicitly that unsupported optional arguments should be ignored.
627 \item Adding examples.
628 \item Re-ordering information for improved flow.
629 \end{itemize}
630 \item The version of VOTable supported is explicitly stated.
631 \item Whereas the NVO version describes the parameter with ucd="OBS\_ANG-SIZE" as "an expression of the opening angle of the cones", this version describes it specifically as "an expression of the uncertainty of the positions".
632 \item A note has been added to recognize the ambiguity in the location of the ERROR parameter.
633 \item The general description of the resource profile has been altered to allow rendering of the metadata to change according to the standards and conventions of the IVOA.
634 \item An editor's note has been added that makes reference to the RM document [RM].
635 \item A requirement that \textbf{MaxSR} be given in decimal degrees has been added.
636 \item For the \textbf{BaseURL} resource profile metadatum, the example has been replaced with a reference to the BaseURL syntax description.
637 \item An appendix has been added to describe the current practice for registering Cone Search services.
638 \end{itemize}
639
640 \bibliography{ivoatex/ivoabib,ivoatex/docrepo,scs}
641
642
643 \end{document}

Properties

Name Value
svn:executable *

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26