\documentclass[11pt,a4paper]{ivoa}
\input tthdefs

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

\title{UWS Registry Extension}

\ivoagroup{Grid and Web Services}

\author{Patrick Dowler}
\author{Markus Demleitner}
\author{Brian Major}
\author{Mark Taylor}

\editor{Brian Major}

\previousversion{This is the first public release}
       
\begin{document}
\begin{abstract}

The Universal Worker Service (UWS) Registry Extension allows for
extended metadata to be set on a VOResource \xmlel{interface} for the
purpose of tagging UWS job execution access URLs.

\end{abstract}

\section*{Conformance-related definitions}

The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
``OPTIONAL'' (in upper or lower case) used in this document are to be
interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.

The \emph{Virtual Observatory (VO)} is a
general term for a collection of federated resources that can be used
to conduct astronomical research, education, and outreach.
The \href{http://www.ivoa.net}{International
Virtual Observatory Alliance (IVOA)} is a global
collaboration of separately funded projects to develop standards and
infrastructure that enable VO applications.

\section{Introduction}

This note describes the registry extension for the Universal Worker
Service UWS \citep{std:UWS}.  Registry extensions add information to the
schema defined in VOResource \citep{std:VOR} that are specific to a
particular standard, in this case UWS.

The UWS registry extension is very simple--it allows for two new values
to be set on the \emph{type} attribute in the \xmlel{interface} element
in a VOResource \xmlel{capability}.  These types have the purpose of
identifying the \xmlel{interface} as one of the synchronous or
asynchronous UWS job execution features.

Although the UWS registry extension itself is simple, the history of the
need for it is complicated.  This history is described in section
\ref{background}.  The extension itself is described in section
\ref{uwsregext}.  

%\subsection{Role within the VO Architecture}

%\begin{figure}
%\centering

% As of ivoatex 1.2, the architecture diagram is generated by ivoatex in
% SVG; copy ivoatex/archdiag-full.xml to archdiag.xml and throw out
% all lines not relevant to your standard.
% Notes don't generally need this.  If you don't copy archdiag.xml,
% you must remove archdiag.svg from FIGURES in the Makefile.

%\includegraphics[width=0.9\textwidth]{archdiag.svg}
%\caption{Architecture diagram for this document}
%\label{fig:archdiag}
%\end{figure}

%Fig.~\ref{fig:archdiag} shows the role this document plays within the
%IVOA architecture \citep{note:VOARCH}.

\section{Background} \label{background}

\subsection{Motivation}

During the review of the TAP 1.1 specification \citep{std:TAP11}, it was
discovered that, when searching for TAP instances, there is the
potential for clients of RegTAP \citep{std:RegTAP} to discover multiple
\xmlel{interface} results per instance when only one is expected.  

TAP clients currently follow the recommendations of RegTAP 1.1 to
discover TAP access URLs and issue a query like this:

\begin{lstlisting}[language=SQL]
SELECT ivoid, access_url
    FROM rr.capability
    NATURAL JOIN rr.interface
    WHERE standard_id like 'ivo://ivoa.net/std/tap%'
    AND intf_type='vs:paramhttp'
\end{lstlisting}

This query is sufficient for most of the existing registered TAP
services and will return only one result.  Those records typically look
like this:

\begin{lstlisting}[language=XML]
  <capability standardID="ivo://ivoa.net/std/TAP">
    <interface xsi:type="vod:ParamHTTP" role="std">
      <accessURL use="base">http://example.com/tap</accessURL>
    </interface>
  </capability>
\end{lstlisting}

To then use the sync and async endpoints of the TAP service, clients
simply append /sync and /async to the end of the base access URL, as per
the recommendations of TAP version 1.0.

Two things have changed since VOResource version 1.03 that make this
query to find all TAP services incorrect:

\paragraph{Change \#1. Multiple standard IDs in TAP} TAP 1.1 originally
stated that the standard IDs of sync and async are distinct and each are
registered.  Although this gives services the flexibility to use URLs
for sync and async that don't end in precisely /sync and /async, it
breaks the pattern of TAP 1.0 service discovery.  With the search
recommended by RegTAP, clients would find the \xmlel{interfaces} within
each of the \xmlel{capabilities} and attempt to append /sync and /async
to the endpoints.

Here is an example of the \xmlel{capability} element of the (now
obsolete) synchronous endpoint in TAP 1.1:

\begin{lstlisting}[language=XML]
  <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
    <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
      <accessURL use="base">http://example.com/tap/sync</accessURL>
    </interface>
  </capability>
\end{lstlisting}

\paragraph{Change \#2. Multiple \xmlel{interfaces} per
\xmlel{capability}} Although, in VOResource, it has always been the case
that multiple \xmlel{interfaces} are allowed per \xmlel{capability}, no
services had yet to be registered with such a configuration.  This
changed when some TAP implementations introduced TAP endpoints with a
variety of \xmlel{SecurityMethod}\/s.  To document such a configuration,
multiple \xmlel{interfaces} per \xmlel{capability} must be created, each
with a different \xmlel{SecurityMethod}.  Or, when the access URLs are
the same, a single \xmlel{interface} with multiple
\xmlel{SecurityMethod}\/s could be created.  Each configuration causes
difficulties for registry service lookup.

Here is an example of the \xmlel{capability} element of the synchronous
endpoint in TAP 1.1 (now obsolete) with multiple \xmlel{interfaces} to
support multiple \xmlel{SecurityMethod}\/s:

\begin{lstlisting}[language=XML]
  <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
    <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
      <accessURL use="base">http://example.com/tap/sync</accessURL>
    </interface>
    <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
      <accessURL use="base">https://example.com/tap/sync</accessURL>
      <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
    </interface>
  </capability>
\end{lstlisting}

Note that, though this issue was discovered on the review of TAP 1.1, it
applies to all IVOA services that need to provide potentially different
access URLs for each \xmlel{SecurityMethod}.

\subsection{Reaction}

To address problem \#2 described above, RegTAP 1.1 recommends that an
additional constraint of having a null \xmlel{SecurityMethod} is
included in the where clause of the TAP service discovery query.
However, for this to work, there cannot be a case where an
\xmlel{interface} is reused by multiple \xmlel{securityMethod}\/s, as
this would not allow the constraint of a null securityMethod to work if
the endpoint supported other non-null \xmlel{securityMethod}\/s.  So,
VOResource 1.1 has ensured that at most one \xmlel{SecurityMethod} is
allowed per \xmlel{interface}.

Problem \#1 is addressed in two ways:  One:  By removing multiple
standard IDs from TAP 1.1; and, two:  by the use of this UWS Registry
Extension.  TAP 1.1 has removed the use of standardIDs for sync and
async and instead now only uses the version agnostic standardID from TAP
1.0:  \xmlel{ivo://ivoa.net/std/TAP}.  Clients can recognize the TAP
service as version 1.1 by checking for a \xmlel{version} attribute with
the value "1.1" in the various \xmlel{interface} elements within the capability.
In order to allow services to choose their own access URLs for sync and
async queries, \xmlel{interface} elements within the \xmlel{capability} are
created for each type of \xmlel{SecurityMethod} that is supported.  There
may be both sync and async versions of these \xmlel{interfaces}.  Whether
an interface is sync or async is determined by the \emph{type} attribute in
the \xmlel{interface}.  To support TAP 1.0 backwards compatibility, a
TAP 1.0 style \xmlel{interface} must remain in the \xmlel{capabilities}.

\section{UWS Registry Extension} \label{uwsregext}

A number of IVOA services have functionality built on the Universal
Worker Service.  Jobs, which perform service-specific functions, can be
created and started in either a synchronous or asynchronous manner.
These services include TAP \citep{std:TAP11}, VOSpace \citep{std:VOSpace},
and others.  It is the UWS specification itself that defines how the
lifecycle of these jobs is managed through a RESTful interface, not the
services that are built on top of them.  However, in the past, it has
been left to the services to state how the synchronous and asynchronous
endpoints are to be discovered through the IVOA registry.

This first version of the UWS Registry Extension enables UWS services to
be registered with UWS-specific interface types so that they can be
discovered by clients in a standard way defined by this note.  This
means that specifications built on UWS need not specify additional
details on how to discover UWS RESTful endpoints.

The UWS Registry Extension introduces two new \xmlel{interface} types:
one for synchronous jobs and one for asynchronous jobs.  The surrounding
\xmlel{interface} element should be marked with the minor version of
service specification, as per the recommendations in the XML schema
versioning note \citep{2018ivoa.spec.0529H}.

\begin{table}
\centering
\begin{tabular}{| c | c | c |}
\hline
 & Asynchronous & Synchronous \\
\hline
Interface Type & urx:Async & urx:Sync \\
\hline
\end{tabular}
\caption{UWS Async and Sync interface types}
\end{table}

Future versions of the UWS Registry Extension may allow for more detail
to be added about the UWS interfaces.  This first version only supplies
the two new \xmlel{interface} types so that they can be used by UWS
services to \emph{tag} their sync and async endpoints.

\subsection{Example TAP 1.1 capability}

The following example describes how a TAP 1.1 service advertises its
sync and async query endpoints under the single TAP capability.  Both
sync and async support anonymous queries and authenticated queries with
TLS \citep{std:SSOAUTH}.  The first two \xmlel{interface} are there to
provide backwards compatibility support for 1.0 TAP clients.

\begin{lstlisting}[language=XML]

<vosi:capabilities
  xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
  xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:urx="http://www.ivoa.net/xml/UWSRegExt/v0.1">

  <capability standardID="ivo://ivoa.net/std/TAP">
    
    <!-- TAP 1.0 support -->
    <interface xsi:type="vod:ParamHTTP" role="std">
      <accessURL use="base">http://example.com/tap</accessURL>
    </interface>
    <interface xsi:type="vod:ParamHTTP" role="std">
      <accessURL use="base">https://example.com/tap</accessURL>
      <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
    </interface>
    
    <!-- TAP 1.1 support -->
    <interface
         xsi:type="urx:Sync" role="std" version="1.1">
      <accessURL use="base">http://example.com/tap/sync</accessURL>
    </interface>
    <interface
         xsi:type="urx:Sync" role="std" version="1.1">
      <accessURL use="base">https://example.com/tap/sync</accessURL>
      <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
    </interface>
    <interface
         xsi:type="urx:Async" role="std" version="1.1">
      <accessURL use="base">http://example.com/tap/async</accessURL>
    </interface>
    <interface
         xsi:type="urx:Async" role="std" version="1.1">
      <accessURL use="base">https://example.com/tap/async</accessURL>
      <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
    </interface>
    
  </capability>

</vosi:capabilities>
\end{lstlisting}

In the examples in this document, the prefix \xmlel{urx} is used to refer to
the UWSRegExt namespace.  It should be noted that this prefix is arbitrary
and has no value in itselt.

The UWSRegExt namepace in the example is declared in the \xmlel{capabilities}
element so that it does not have to be repeatedly declared in the
\xmlel{interface} elements.  However, it is also technically correct for it to
be declared at the interface level or in the document root.  As best
practice we recommend it be declared in the deepest element that contains all
the references.

\subsection{XML Schema}

The following is the XML Schema Definition for the UWS Registry
Extension version 0.1.  It can be brought into an XML document's schema
as a namespace with the URI
\xmlel{http://www.ivoa.net/xml/UWSRegExt/v0.1}.

\lstinputlisting[language=XML]{UWSRegExt-v0.1.xsd}

\appendix
\section{Changes from Previous Versions}

No previous versions yet.  
% these would be subsections "Changes from v. WD-..."
% Use itemize environments.

\bibliography{UWSRegExt.bib,ivoatex/ivoabib,ivoatex/docrepo}

\end{document}
