diff --git a/ConeSearch.tex b/ConeSearch.tex index dd9ff9c..e9cbb0e 100755 --- a/ConeSearch.tex +++ b/ConeSearch.tex @@ -107,11 +107,14 @@ \section{Service Interface Requirements} \label{sec:2} A service implementation that is compliant with this standard must meet -the following requirements: +the requirements described in the following 3 subsections +(\ref{subsec:baseurl}, \ref{subsec:response}, and \ref{subsec:error}). -\begin{enumerate} - \item the service must respond to a HTTP GET request - represented by a URL having two parts:\\ +\subsection{Query resource} +\label{subsec:baseurl} + +The service must respond to a HTTP GET request +represented by a URL having two parts:\\ \begin{itemize} \item A base URL of the form\\ @@ -167,11 +170,18 @@ \section{Service Interface Requirements} \item[Example] \url{http://mycone.org/cgi-bin/search?RA=180.567&DEC=-30.45&SR=0.0125} \end{bigdescription} - \item As defined by DALI a service SHOULD also understand the following parameter: + \item As defined by DALI a service SHOULD also understand the following parameters: \begin{description} \item[\textbf{MAXREC}] to let the client limit the number of records returned - or require a service metadata response. Its usage is encouraged and preferred - to the SR=0 solution for metadata discovery. + or require a service metadata response. That means that a + request including any of MAXREC or SR set with a value of 0 + should require a metadata response. + \item[\textbf{RESPONSEFORMAT}] to allow alternative optional response + formats other than the mandatory VOTable one. Indeed, a Simple + Cone Search service MUST provide responses in VOTable format \citep{2025ivoa.spec.0116O}, + compliant with respect to what will + be detailed in the next subsection (Sec.~\ref{subsec:response}), but should also + support the DALI RESPONSEFORMAT parameter. \end{description} \item The query MAY contain the optional parameter, \textbf{VERB}, whose value is an integer--either 1, 2, or 3--indicating @@ -198,146 +208,115 @@ \section{Service Interface Requirements} A query following this syntax represents a request for information on sources located within the specified cone on the sky. - \item The service must respond with an XML document in the VOTable - format, that represents a table of astronomical sources whose positions - are within the cone (see Appendix \ref{appendix:a} for an example). - 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. The base MIME-type of the HTTP - response should be \texttt{text/xml}. The more specific form - \texttt{text/xml;content=x-votable} may optionally be used. The - MIME-type, \texttt{text/xml;votable} shall also be considered legal (for - backward compatibility reasons); however, this value is strongly - discouraged as it is not compliant with the MIME-type standard - \citep{std:MIME}. Simple Cone Search services MUST return VOTable - version 1 documents. - - \begin{bigdescription} - \item[Editor's Note] The original NVO specification allowed a - MIME-type of text/xml;votable, thus for backward - compatibility this is still allowed but discouraged. - \end{bigdescription} - - The VOTable MUST comply with these conditions: +\subsection{Succesful response} +\label{subsec:response} + +A successfull response from a Cone Search service \textbf{must} be a +table containing the astronomical sources whose positions are within the +cone described by the query parameter values described in +Sec.~\ref{subsec:baseurl}. The service implementor may decide on the exact +search criterion used to select the sources, including also other +sources outside the cone. +The response table \textbf{must} contain, alongside all possible columns +available in the served source catalog: +\begin{itemize} + \item one string column representing an ID for that record of the table. + This identifier may not be repeated in the table, and it could be used to + retrieve that same record again from that same table; + \item one numerical column representing the main value for the + right-ascension of the source in the ICRS coordinate system; + \item one numerical column representing the main value for the + declination of the source in the ICRS coordinate system. +\end{itemize} +Right-ascension and declination of the output columns \textbf{MUST} be in decimal degrees. + +By default, the service \textbf{must} respond with an XML document in the +VOTable\citep{2025ivoa.spec.0116O} format. However, if RESPONSEFORMAT is +set (see Sec.~\ref{subsec:baseurl}) the response table \textbf{should} +match the requested format; if this format is unsupported the request +\textbf{should} fail. + +When the response is in the default VOTable format (see Appendix \ref{appendix:a} +for an example), the MIME-type of the HTTP response \textbf{should} be +set to \texttt{application/x-votable+xml}. The form +\texttt{text/xml} can optionally be used, while the +form \texttt{text/xml;votable} shall be considered legal +only for backward compatibility reasons +\footnote{ + The original NVO specification allowed a MIME-type of text/xml;votable, + this is why for backward compatibility this is still allowed but discouraged. +} +and is strongly discouraged as it is not compliant with the MIME-type +standard \citep{std:MIME}. + +Simple Cone Search services \textbf{MUST} return VOTable +version 1 documents. + +The response in VOTable format \textbf{MUST} follow the prescriptions on +VOTable usage in result contained (currently) in Sec. 4.4 of the DALI 1.1 +specification. Moreover it \textbf{MUST} comply with these conditions: - \begin{itemize} - \item There must be a single RESOURCE with \texttt{type=''results''} in the VOTable, - and that RESOURCE must contain a single TABLE. Additional RESOURCE(s) are - allowed to enable, e.g., DataLink service descriptors. - \item The TABLE must have FIELDS where - the following UCD values have been set. There must only be one FIELD - with each of these UCDs: - - \begin{itemize} - \item Exactly one FIELD must have ucd="meta.id;meta.main", - with an array character type (fixed or variable - length), representing an ID string for that record of the table. This - identifier may not be repeated in the table, and it could be used to - retrieve that same record again from that same table. - \item Exactly one FIELD must have ucd="pos.eq.ra;meta.main", - representing the right-ascension of the source in the ICRS coordinate system. - \item Exactly one FIELD must have ucd="pos.eq.dec;meta.main", - representing the declination of the source in the ICRS coordinate system. - \item The above right-ascension and declination FIELD(s) must have the datatype - attribute set to float or double, following the VOTable standard \citep{2019ivoa.spec.1021O}. - \end{itemize} - - \item 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 PARAM in the RESOURCE which has a UCD that is - set to phys.angSize;obs 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 FIELD in the table having a UCD set to phys.angSize;obs. - \item There may be other FIELDs in the table. Their specification should - include a description, data-type, and UCD. - \end{itemize} - - \item The service must respond with a stubbed version of the VOTable in the case - of error. This must happen if the three required parameters (RA, DEC, - SR) are not all present, or if their values cannot be parsed to - floating-point numbers, or if the numbers are out of range (DEC=91.0, - for example). The service may also make an error return if the search - radius (give by the SR parameter) is larger than the MaxSR parameter of - the Resource Profile (see Section \ref{sec:3}). In the case of error, - the service MUST respond with a VOTable that contains a PARAM element or - an INFO element with \texttt{name="Error"}, where thecorresponding value - attribute should contain some explanation of the nature of the error. No - other PARAM or INFO element in the response can be present having - \texttt{name=''Error''} set, but additional INFO and PARAM elements with - the name parameter set to a different value are allowed. If an INFO - element is used, it must appear as a direct child of one of the - following elements: - - \begin{itemize} - \item the root VOTABLE element (which is preferred by this document), or - \item the RESOURCE element - \end{itemize} - - If a PARAM element is used, it must appear as a direct - child of one of following elements: - - \begin{itemize} - \item the RESOURCE element, or - \item a DEFINITION element below the root VOTABLE element - (which is discouraged by this document). - \end{itemize} +\begin{itemize} + \item There must be a single RESOURCE with \texttt{type=''results''} in the VOTable, + and that RESOURCE must contain a single TABLE. Additional RESOURCE(s) are + allowed to enable, e.g., DataLink service descriptors. + \item The TABLE must have FIELDS where + the following UCD values have been set. There must only be one FIELD + with each of these UCDs: - \begin{bigdescription} - \item[Editor's Note] - It was recognized that this - requirement, as it was described in the original NVO specification, is - ambiguous about both the element to use for the ERROR message and its - location in the document. The VOTable standard allows PARAM and INFO - elements to appear in various places within the document. Since several - of the different methods have been used in practice by Cone Search - service implementations, no attempt is made in this version to correct - this ambiguity. All of the above-mentioned locations should be - considered legal, and Cone Search service clients should be prepared to - look in all of them for an ERROR message. The use of PARAM as a child of - DEFINITIONS is discouraged as the DEFINITIONS element was deprecated in - VOTable v1.1. - \end{bigdescription} - \begin{bigdescription} - \item[Example Error Responses] - Error INFO as child of VOTABLE (preferred)\\ - - \begin{lstlisting}[language=XML,basicstyle=\footnotesize] - - - - - \end{lstlisting} - - Error PARAM as child of RESOURCE (allowed) - - \begin{lstlisting}[language=XML,basicstyle=\footnotesize] - - - - - HEASARC Browse data service - Please send inquiries to mailto:request@athena.gsfc.nasa.gov - - - - - - \end{lstlisting} - - \end{bigdescription} - - Other conditions may - NOT be considered erroneous, for example if a query cone is in the - Southern hemisphere and the catalog coverage is in the Northern - hemisphere. This type of query is different from an error return; it - should return a VOTable as described above, with metadata, but no data - records. -\end{enumerate} + \begin{itemize} + \item Exactly one FIELD must have ucd="meta.id;meta.main", + with an array character type (fixed or variable + length), representing an ID string for that record of the table. This + identifier may not be repeated in the table, and it could be used to + retrieve that same record again from that same table. + \item Exactly one FIELD must have ucd="pos.eq.ra;meta.main", + representing the right-ascension of the source in the ICRS coordinate system. + \item Exactly one FIELD must have ucd="pos.eq.dec;meta.main", + representing the declination of the source in the ICRS coordinate system. + \item The above right-ascension and declination FIELD(s) must have the datatype + attribute set to float or double, following the VOTable + standard \citep{2025ivoa.spec.0116O}. + \end{itemize} + + \item 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 PARAM in the RESOURCE which has a UCD that is + set to phys.angSize;obs 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 FIELD in the table having a UCD set to phys.angSize;obs. + \item There may be other FIELDs in the table. Their specification should + include a description, data-type, and UCD. +\end{itemize} + +\subsection{Error response} +\label{subsec:error} + +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. + +In the case the error is expressed in VOTable format, recommendation +expressed in Section 4.4 of DALI \textbf{should} be followed. + +Errors \textbf{must} be reported in any of the following cases: +\begin{itemize} + \item any of the three required paramaters (RA, DEC, SR) is missing; + \item their values cannot be parsed to floating point numbers; + \item the value numbers are out of range (DEC=91.0, for example). +\end{itemize} + +The service may also return an error if the search radius (given by the +SR parameter) is larger than the one set by the maxSR element of the +capability of the service described as a VO resource (see +Sec.~\ref{sec:3}). + +Queries targeting no records \textbf{should not} generate an error +response but an empty metadata one (if applicable by format). \section{The Resource Profile} \label{sec:3} @@ -638,6 +617,11 @@ \section{Changes from Previous Versions} \subsection*{Changes from WD-1.1-20200828} \begin{itemize} + \item included OVERFLOW indicator (updating MAXREC usage) + \item updated all UCD(s) to conform to the UCD1+ specification + \item explicitly stated that RA and Dec responses must be + in units of decimal degrees + \item re-instated changes done in the previous WD-1.1-20200828 \item embedded errata 1, 2 and 3 for ConeSearch-1.03 \item Complete revert of changes to restore clean 1.03 contents, in view of specific minor updates (listed here above) diff --git a/ivoatex b/ivoatex index 85a59fe..04d5819 160000 --- a/ivoatex +++ b/ivoatex @@ -1 +1 @@ -Subproject commit 85a59fe8e6abd86bbe3ef4e12fd3dade71a54924 +Subproject commit 04d5819ee835ed7a2f40e1faf757394d0ae9a4d6