Merge pull request #64 from molinaro-m/responseformat

adding RESPONSEFORMAT, DALI error responses & OVERFLOW usage

Author: molinaro-m

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]			
-<VOTABLE xmlns="http://www.ivoa.net/xml/VOTable/v1.3">
-   <INFO ID="Error" name="Error" 
-    value="Field RA: 'as3f' is not a valid literal for RA"/>
-   <RESOURCE/>
-</VOTABLE> 
-			\end{lstlisting}
-			
-			Error PARAM as child of RESOURCE (allowed)
-			
-			\begin{lstlisting}[language=XML,basicstyle=\footnotesize]
-<?xml version="1.0"?>
-<!DOCTYPE VOTABLE SYSTEM "http://us-vo.org/xml/VOTable.dtd">
-<VOTABLE version="1.0">
-  <DESCRIPTION>
-    HEASARC Browse data service
-    Please send inquiries to mailto:[email protected]
-  </DESCRIPTION>
-  <RESOURCE ID="error_resource">
-    <PARAM ID="Error" name="Error" datatype="char" arraysize="*"
-      value="Invalid data type: text/html"/>
-  </RESOURCE>
-</VOTABLE>
-			\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)