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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

Name Value
svn:executable *

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