adding RESPONSEFORMAT, DALI error responses & OVERFLOW usage #64
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -107,11 +107,14 @@ \section{Service Interface Requirements} | |
| \label{sec:2} | ||
|
|
||
| A service implementation that is compliant with this standard must meet | ||
| the requirements described in the following 3 subsections | ||
| (\ref{subsec:baseurl}, \ref{subsec:response}, and \ref{subsec:error}). | ||
|
|
||
| \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,17 @@ \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 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. | ||
| \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. 2.2), 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 +207,112 @@ \section{Service Interface Requirements} | |
| A query following this syntax represents a request for | ||
| information on sources located within the specified cone on the sky. | ||
|
|
||
| \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. | ||
|
Comment on lines
+226
to
+229
There was a problem hiding this comment. Specify decimal degrees for RA & Dec output columns. There was a problem hiding this comment. OK, I have added a sentence but this wasn't in the 1.03 version... I'll add it as a discussion point for the dedicated running meeting. There was a problem hiding this comment. I see what you mean, this could in principle invalidate an existing CS 1.03-compliant service that returns RA and Dec in radians, so is maybe questionable. But I doubt that there are any such services, and being able to assume degrees here simplifies rigorous client processing a lot, so I'd say it's worth that small risk. As you say: let's discuss. There was a problem hiding this comment. From discussion at DAL Running Meeting 21 the requirement to have RA and Dec in decimal degrees stays as is. No major issues foreseen from a quick investigation of the existing services behaviour. |
||
| \end{itemize} | ||
|
|
||
| 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, depending on the service capabilities. | ||
|
||
|
|
||
| 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} 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. | ||
|
Comment on lines
+260
to
+262
There was a problem hiding this comment. OVERFLOW signalling as described in DALI 1.1 section 4.4 should be mentioned here as well. Alternatively, just defer to DALI 1.1 sec 4.4 for the whole description of how to write DALI-compliant VOTable results. There was a problem hiding this comment. Referenced DALI 1.1 Sec.4.4, even if I must say, these sort of references never look perfect to me. There was a problem hiding this comment. Agreed referencing fixed sections of fixed versions in other standards is not great, though it does a usability service to readers for as long as the version in question is current. It may be that just referring to the DALI standard without quoting section or version is better, I don't have a strong opinion. |
||
| \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{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, | ||
| inluding the OVERFLOW behaviour in case the MAXREC parameter is set. | ||
|
||
|
|
||
| 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 +613,18 @@ \section{Changes from Previous Versions} | |
|
|
||
| \subsection*{Changes from WD-1.1-20200828} | ||
| \begin{itemize} | ||
| % | ||
| % remove the constraint of one RESOURCE only, clarifying it was there | ||
| % only for the results | ||
| % | ||
| % added DALI MAXREC and RESPONSEFORMAT parameters, for response | ||
|
||
| % flexibility and DALI alignment | ||
| % | ||
| % introduced flexibility on the decimal (float or double) behaviour for | ||
| % RA and Dec in responses | ||
| % | ||
| % updated all UCD to conform to the UCD1+ specification | ||
| % | ||
| \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) | ||
|
|
||
| +53 −13 | Makefile | |
| +1 −1 | Makefile.template | |
| +6 −18 | archdiag-full.xml | |
| +80 −12 | docrepo.bib | |
| +2 −2 | fetch_from_ads.py | |
| +6 −3 | github_workflow_build.yml.template | |
| +34 −27 | github_workflow_preview.yml.template | |
| +14 −1 | ivoa.cls | |
| +50 −9 | regressiontest/run-regression.py | |
| +2 −2 | stdrec-template.xml | |
| +1 −0 | submission.py | |
| +17 −2 | tthdefs.tex | |
| +89 −0 | update-stdrec.py | |
| +19 −1 | update_generated.py |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should probably say "its usage with a value of 0" rather than "its usage".
Note however it's a bit problematic preferring MAXREC=0 to SR=0 for metadata probing, since services that don't support the optional MAXREC parameter (including all pre-v1.1 services?) will ignore it and potentially give you a lot of data. Preferred usage for metadata probing would therefore be
MAXREC=0&SR=0&. But maybe that's either obvious or too much detail to put in here.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I should have fixed this, adding a footnote for the additional consideration on MAXREC being optional