Skip to content

Clean Registry extension specification #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 22, 2025
Merged

Clean Registry extension specification #67

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cbb6b81
updated changelog from previous merges
molinaro-m Sep 19, 2025
4677ff2
first attempt at cleaning registry extension
molinaro-m Sep 19, 2025
697a124
added text on registry search, and update changelog
molinaro-m Sep 22, 2025
99dac99
fixed RegTAP ADQL query
molinaro-m Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 26 additions & 198 deletions ConeSearch.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
\usepackage{todonotes}

\usepackage{listings}
\lstloadlanguages{XML,sh}
\lstloadlanguages{XML,sh,SQL}
\lstset{flexiblecolumns=true,tagstyle=\ttfamily, showstringspaces=False}

\usepackage{multirow}
Expand Down Expand Up @@ -323,68 +323,28 @@ \subsection{Error response}
\section{The Resource Profile}
\label{sec:3}

A Cone Search service MUST
be described with a Resource Profile that includes the following
information. The Profile is composed of named metadata listed below. The
format used to encode the profile should be compliant with the
publishing standards of the IVOA throughout the time the service is
supported by the data provider. The metadata names and values used in
the profile encoding should match those given below as closely as
possible; where they do not match exactly, they should be consistent
with the IVOA metadata conventions in place at any given time and the
mapping of names and values actually used and those given below should
be well documented.

\begin{bigdescription}
\item[Editor's Note]
The original NVO specification pre-dates the IVOA standard for resource
metadata [RM], and so, obviously, some inconsistencies with that
standard exist. To deal with this, the wording of this section has been
altered to allow profiles to be constructed according to the latest
practices in the IVOA. Appendix B outlines the mapping of the metadata
listed below to that in the RM as well as the XML Schema used to render
the metadata within a Registry.
\end{bigdescription}

Several of the
metadata listed below can have values that are hierarchical; this
hierarchy should be represented in a manner most appropriate to the
format used. When the format does not provide any such mechanism, it is
recommended that the value be represented as a strings delimited by dots
with the root domain of the value appearing first.

The resource profile consists of the following metadata with the stated
definitions:

\begin{itemize}
\item[\textbf{ResponsibleParty}] The data provider's name and email.
\item[\textbf{ServiceName}] The name of the
catalog served by the service, for example "IRSA.2MASS.ExtendedSources".
\item[\textbf{Description}] A couple of paragraphs of text that describe
the nature of the catalog and its wider context.
\item[\textbf{Instrument}] The instrument that made the observations,
for example STScI.\-HST.\-WFPC2.
\item[\textbf{Waveband}] The waveband
of the observations, with ONE selected from this list: radio,
millimeter, infrared, optical, ultraviolet, xray, gammaray.
\item[\textbf{Epoch}] The epoch of the observations, as a free-form string.
\item[\textbf{Coverage}] The coverage on the sky, as a free-form string.
\item[\textbf{MaxSR}] The largest search radius, given in decimal
degrees, that will be accepted by the service without returning an error
condition. A value of 180.0 indicates that there is no restriction.
\item[\textbf{MaxRecords}] The largest number of records that the
service will return.
\item[\textbf{Verbosity}] True or false, depending
on whether the service supports the VERB keyword in the request.
\item[\textbf{BaseURL}] The base URL for the service as described in
Section \ref{sec:2}.
\end{itemize}
To describe a Cone Search service as a VOResource record the service
provider \textbf{must} follow the
SimpleDALRegExt \citep{2022ivoa.spec.0222D} Recommendation (version 1.2
at the time of writing).
More in detail, Section 2 (common requirements for Simple DAL Services)
and Section 3.1 (for the specific extension definition for
Simple Cone Search) must be followed.

ConeSearch services, described as above, should be discoverable by means
of queries to a Registry RegTAP \citep{2024ivoa.spec.1002D} interface, like:
\begin{lstlisting}[language=SQL]
SELECT ivoid, res_title, access_url, std_version
FROM rr.resource
NATURAL JOIN rr.capability
NATURAL JOIN rr.interface
WHERE standard_id like 'ivo://ivoa.net/std/conesearch%'
\end{lstlisting}

The service will be considered
published to the VO if the profile has been added to an IVOA Registry
according to the IVOA standards and conventions at the time the service
is made available, TOGETHER with maintaining the web service that is
described by the profile in compliant order.
The \texttt{std\_version} attribute (i.e the version of the interface's
capability) could help, if present on the registered resource, to inform
the client application about the ConeSearch version the service is
following.

\appendix

Expand Down Expand Up @@ -477,146 +437,14 @@ \section{Sample VOTable Response}
</VOTABLE>
\end{lstlisting}

\section{Current Practices for Representing Resource Profiles}

\subsection{Mapping for Resource Profile Metadata to the RM}

As mentioned in an Editor's Note in Section \ref{sec:3}, the original NVO
specification pre-dated the IVOA standard for resource metadata known as
the RM \citep{2004ivoa.spec.0426H}. This section indicates how the
resource profile metadata defined in this specification maps to the
metadata defined in the RM.

\begin{table}[th]
\begin{tabular}{p{0.4\textwidth}p{0.5\textwidth}}
\sptablerule
\textbf{Cone Search Metadatum} & \textbf{RM Metadatum}\\
\sptablerule
\textbf{ResponsibleParty} & Publisher, Contact.Email\\
\textbf{ServiceName} & Title\\
\textbf{Description} & Description\\
\textbf{Instrument} & Instrument\\
\textbf{Waveband} & Coverage.Spectral\\
\textbf{Epoch} & Coverage.Temporal.StartTime, Coverage.Temporal.StopTime\textsuperscript{1}\\
\textbf{Coverage} & Coverage.Spatial\\
\textbf{MaxSR} & Service.MaxSearchRadius\\
\textbf{MaxRecords} & Service.MaxReturnRecords\\
\textbf{Verbosity} & n/a\textsuperscript{2}\\
\textbf{BaseURL} & Service.BaseURL\\
\sptablerule
\label{table:b1meta}
\end{tabular} \caption{Metadata
Mapping} \end{table}

Table notes:
\begin{enumerate}
\item The notion of
the epoch the observations is captured in the RM as the temporal
coverage. The notion of the equinox of the observational positions is
captured part of the RM's Coverage.Spatial.
\item As this concept is not
covered by the RM, it should be considered service-specific capability
metadata.
\end{enumerate}

\subsection{VOResource (pre-v1.0) Schema Extension for Cone Search Services}

Just prior to the adoption of IVOA standard for registry
interfaces, v1.0, resource descriptions were encoded using the
VOResource XML Schema, v0.10 and its family of extension schemas. The
extensions used to specifically describe Cone Search services were
VODataService, v0.5 and ConeSearch, v0.3.
%%%% \todo{The references to RI,
%VOResource, VODataService and ConeSearch here, are all referring to xsd
%schemata currently obsoleted.}. See the embedded documentation in each
%of these schemas for the precise definitions and usage of the metadata
%encodable through them. %%%

The following table enumerates the mapping of resource profile metadata
defined in this specification with those defined in the XML schemas.

\begin{table}[th]
\begin{tabular}{p{0.38\textwidth}p{0.27\textwidth}p{0.34\textwidth}}
\sptablerule
\multirow{2}{*}{\textbf{Cone Search Metadatum}}&\multicolumn{2}{p{0.59\textwidth}}{\textbf{VOResource Metadatum}}\\
&\textbf{Schema Name}&\textbf{XPath Name}\\
\sptablerule
\textbf{ResponsibleParty} & VOResource & curation/publisher, curation/contact/email\\
\textbf{ServiceName} & VOResource & title\\
\textbf{Description} & VOResource & content/description\\
\textbf{Instrument} & VOResource & instrument\\
\textbf{Waveband} & VODataService & coverage/spectral/waveband\\
\textbf{Epoch} & VODataService & coverage/temporal/startTime, coverage/temporal/stopTime\textsuperscript{1}\\
\textbf{Coverage} & VODataService & coverage/spatial\textsuperscript{2}\\
\textbf{MaxSR} & ConeSearch & capability/maxSR\\
\textbf{MaxRecords} & ConeSearch & capability/maxRecords\\
\textbf{Verbosity} & ConeSearch &capability/verbosity\\
\textbf{BaseURL} & VOResource interface/accessURL\\
\sptablerule
\end{tabular}
\caption{VOResource pre-0.10 extension}
\end{table}

Table Notes:
\begin{enumerate}
\item The notion of the epoch the observations is
captured in the schema inside coverage/temporal. The notion of the
equinox of the observational positions is captured within
coverage/spatial/region, such as in
coverage/spatial/region[@xsi:type='vs:Circle']/coordFrame.
\item the coverage/spatial element encodes its information as a
complex set of child elements.
\end{enumerate}

\subsection{VOResource (v1.0) Schema Extension for Cone Search Services}

With the expected adoption of the IVOA standard for Registry
Interface, resources are described using the VOResource schema, v1.0 and
its family of extensions. Cone Search services are specifically
described using the VODataService, v1.0, and ConeSearch, v1.0, extension
schemas. Coverage information is encoded using the Space-Time
Coordinates (STC) schema.

The following table enumerates the mapping of resource profile metadata
defined in this specification with those defined in the XML schemas.

\begin{table}[th]
\begin{tabular}{p{0.4\textwidth}p{0.29\textwidth}p{0.3\textwidth}}
\sptablerule
\multirow{2}{*}{\textbf{Cone Search Metadatum}}&\multicolumn{2}{p{0.59\textwidth}}{\textbf{VOResource Metadatum}}\\
&\textbf{Schema Name}&\textbf{XPath Name}\\
\sptablerule
\textbf{ResponsibleParty} & VOResource & curation/publisher, curation/contact/email\\
\textbf{ServiceName} & VOResource & title\\
\textbf{Description} & VOResource & content/description\\
\textbf{Instrument} & VOResource & instrument\\
\textbf{Waveband} & VODataService & coverage/waveband\\
\textbf{Epoch} & VODataService & coverage-/stc:STCResourceProfile-/stc:AstroCoordArea\textsuperscript{1}\\
\textbf{Coverage} & VODataService & coverage-/stc:STCResourceProfile-/stc:AstroCoordArea\textsuperscript{1}\\
\textbf{MaxSR} & ConeSearch & capability/maxSR\\
\textbf{MaxRecords} & ConeSearch & capability/maxRecords\\
\textbf{Verbosity} & ConeSearch & capability/verbosity\\
\textbf{BaseURL} & VOResource & capability-/interface[@role='std']-/accessURL\\
\sptablerule
\end{tabular}
\caption{VOResource 1.0 extension}
\end{table}

Table Notes:
\begin{enumerate}
\item In STC, coverage on the sky and in
time are described in an integrated way within the stc:AstroCoordArea
element. The notion of the equinox of the observational positions is
captured within stc:AstroCoordSystem element.
\end{enumerate}

Subsequent versions of this document should include the ConeSearch extension
schemaas a formal part of the specification.

\section{Changes from Previous Versions}

\subsection*{Changes from WD-1.1-20200828}
\begin{itemize}
\item replaced resource description with SimpleDALRegExt references
\item clarified response behaviour when dealing with optional
parameters
\item exemplified/explicited HTTPS being allowed
\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
Expand Down