diff --git a/Makefile b/Makefile index e9d7eec..b3ed888 100644 --- a/Makefile +++ b/Makefile @@ -39,7 +39,7 @@ ivoatex/Makefile: sample.xml: make-sample.sh - ./make-sample.sh > sample.xml + ./make-sample.sh install: # local to Markus' setup diff --git a/TAPRegExt-v1.1.xsd b/TAPRegExt-v1.1.xsd index 82a5b4f..8c191b7 100644 --- a/TAPRegExt-v1.1.xsd +++ b/TAPRegExt-v1.1.xsd @@ -4,12 +4,11 @@ xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0" xmlns:vm="http://www.ivoa.net/xml/VOMetadata/v0.1" xmlns:tr="http://www.ivoa.net/xml/TAPRegExt/v1.0" -version="1.1-pre1" +version="1.1-pre3" targetNamespace="http://www.ivoa.net/xml/TAPRegExt/v1.0" elementFormDefault="unqualified" attributeFormDefault="unqualified" -xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" -xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelberg.de/docs/schemata/XMLSchema.xsd"> +xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> TAPRegExt @@ -22,6 +21,42 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + + + + + This attribute group is intended to be used wherever a TAPRegExt + declaration might depend on the access mode. Currently, only + sync vs. async is supported. + + + + + + This declaration only applies to the named mode. + + + + + + + + This declaration is for synchronous queries. + + + + + + + This declaration is for asynchronous queries. + + + + + + + + @@ -79,7 +114,7 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + minOccurs="0" maxOccurs="unbounded"> Limits on the time between job creation and @@ -89,7 +124,7 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + minOccurs="0" maxOccurs="unbounded"> Limits on executionDuration. @@ -98,7 +133,7 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + minOccurs="0" maxOccurs="unbounded"> Limits on the size of data returned. @@ -107,7 +142,7 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + minOccurs="0" maxOccurs="unbounded"> Limits on the size of uploaded data. @@ -471,6 +506,8 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + + @@ -487,7 +524,6 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber - @@ -517,6 +553,7 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + @@ -547,6 +584,8 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + + @@ -574,6 +613,8 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + + diff --git a/TAPRegExt.tex b/TAPRegExt.tex index e3fef75..8e29834 100644 --- a/TAPRegExt.tex +++ b/TAPRegExt.tex @@ -177,6 +177,43 @@ \subsection{The Schema Namespace and Location} in a TAP server's capabilities endpoint. +\subsection{Mode-dependent Declarations} +\label{sect:modedep} + +Several TAPRegExt elements have a \xmlel{forMode} attribute. This +allows operators to declare different behaviour of their services +depending on the ``mode'' used to access the service, which currently +means choosing between sync and async. For instance, certain output +formats may produce more than one physical file, in which case it would +only be available in async mode. More commonly, services may give async +services much more liberal limits for total execution time or the number +of rows retrievable. + +Elements without a \xmlel{forMode} attribute apply to all modes. The +semantics of non-empty \xmlel{forMode} attributes depends on what +elements they are on: + +\begin{itemize} +\item For \xmlel{outputFormat} and \xmlel{uploadMethod}, specifications +are accumulative (i.e., you cannot retract formats or methods per mode, +just add to them). + +\item For \xmlel{retentionPeriod}, \xmlel{executionDuration}, +\xmlel{outputLimit}, and \xmlel{uploadLimit}, limits given in elements +with a \xmlel{forMode} attribute override limits given in elements +without one for the mode specified. For these elements, only zero or +one occurrences are allowed each without \xmlel{forMode} and per +\xmlel{forMode} value\footnote{This constraint is hard to express in XML +Schema and is thus not enforced by it; its purpose is to make sure that +clients will find unique limits.}. + +\end{itemize} + +This is orthogonal to limits and features that depend on the +authentication status. Services varying these depending on who runs a +query should adjust their capability documents accordingly +(cf.~sect.~\ref{reslimits}). + \subsection{Declaring Instantiated Data Models} \label{dms} @@ -192,8 +229,8 @@ \subsection{Declaring Instantiated Data Models} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd DataModelType \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:DataModelType} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:DataModelType} Type Schema Documentation} \noindent{\small{}An IVOA defined data model, identified by an IVORN intended for machine consumption and a short label @@ -262,8 +299,8 @@ \subsection{Languages Supported} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd Language \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:Language} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:Language} Type Schema Documentation} \noindent{\small{}A query language supported by the service.\par} @@ -334,8 +371,8 @@ \subsection{Languages Supported} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd Version \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:Version} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:Version} Type Schema Documentation} \noindent{\small{}One version of the language supported by the service.\par} @@ -463,8 +500,8 @@ \subsection{Languages Supported} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd LanguageFeatureList \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:LanguageFeatureList} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:LanguageFeatureList} Type Schema Documentation} \noindent{\small{}An enumeration of non-standard or non-mandatory features of a specific type implemented by the language.\par} @@ -534,8 +571,8 @@ \subsection{Languages Supported} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd LanguageFeature \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:LanguageFeature} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:LanguageFeature} Type Schema Documentation} \noindent{\small{}A non-standard or non-mandatory feature implemented by the language..\par} @@ -600,11 +637,15 @@ \subsection{Output Formats} with a BINARY2 child \end{description} +Operators can restrict individual output formats to either sync or async +requests using the \xmlel{forMode} attribute as explained in +\ref{sect:modedep}. + % GENERATED: !schemadoc TAPRegExt-v1.1.xsd OutputFormat \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:OutputFormat} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:OutputFormat} Type Schema Documentation} \noindent{\small{}An output format supported by the service.\par} @@ -650,6 +691,17 @@ \subsection{Output Formats} resource record and look for keys starting with {"}output-{"}. \end{description} +\item[forMode] +\begin{description} +\item[Type] string +\item[Meaning] This declaration only applies to the named mode. +\item[Occurrence] optional + +\item[Allowed Values\vrule width 0pt depth 5pt]\hfil + \begin{longtermsdescription}\item[sync]This declaration is for synchronous queries. +\item[async]This declaration is for asynchronous queries. +\end{longtermsdescription} +\end{description} \end{bigdescription}\endgroup @@ -733,11 +785,15 @@ \subsection{Upload Methods} \end{lstlisting} +Operators can restrict individual upload methods to either sync or async +requests using the \xmlel{forMode} attribute as explained in +\ref{sect:modedep}. + % GENERATED: !schemadoc TAPRegExt-v1.1.xsd UploadMethod \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:UploadMethod} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:UploadMethod} Type Schema Documentation} \noindent{\small{}An upload method as defined by IVOA.\par} @@ -758,6 +814,7 @@ \subsection{Upload Methods} + @@ -773,6 +830,17 @@ \subsection{Upload Methods} \item[Occurrence] optional \end{description} +\item[forMode] +\begin{description} +\item[Type] string +\item[Meaning] This declaration only applies to the named mode. +\item[Occurrence] optional + +\item[Allowed Values\vrule width 0pt depth 5pt]\hfil + \begin{longtermsdescription}\item[sync]This declaration is for synchronous queries. +\item[async]This declaration is for asynchronous queries. +\end{longtermsdescription} +\end{description} \end{bigdescription}\endgroup @@ -799,6 +867,12 @@ \subsection{Resource Limits} conservative guidelines. Thus, the operators of a service implementing a complex, possibly dynamic limits policy should give lower estimates here. +It is rather common that operators enforce different limits depending on +the access mode (sync or async). Therefore, most limits have a +\xmlel{forMode} attribute as per sect.~\ref{sect:modedep}; for +convenience and later extensibility, that is even true for +\xmlel{retentionPeriod}, which admittedly cannot apply to sync requests. + If a service supports authentication and has different limits depending on what user is authenticated, it should make an effort to guess the limits applying to a given client (e.g., when @@ -834,8 +908,8 @@ \subsubsection{Limits on Time} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd TimeLimits \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:TimeLimits} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:TimeLimits} Type Schema Documentation} \noindent{\small{}Time-valued limits, all values given in seconds.\par} @@ -848,9 +922,28 @@ \subsubsection{Limits on Time} maxOccurs="1" /> + \end{lstlisting} +\vspace{0.5ex}\noindent\textbf{\xmlel{tr:TimeLimits} Attributes} + +\begingroup\small\begin{bigdescription}\item[forMode] +\begin{description} +\item[Type] string +\item[Meaning] This declaration only applies to the named mode. +\item[Occurrence] optional + +\item[Allowed Values\vrule width 0pt depth 5pt]\hfil + \begin{longtermsdescription}\item[sync]This declaration is for synchronous queries. +\item[async]This declaration is for asynchronous queries. +\end{longtermsdescription} +\end{description} + +\end{bigdescription}\endgroup + + + \vspace{0.5ex}\noindent\textbf{\xmlel{tr:TimeLimits} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{default}] @@ -907,8 +1000,8 @@ \subsubsection{Limits on Data} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd DataLimits \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:DataLimits} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:DataLimits} Type Schema Documentation} \noindent{\small{}Limits on data sizes, given in rows or bytes.\par} @@ -922,9 +1015,28 @@ \subsubsection{Limits on Data} + \end{lstlisting} +\vspace{0.5ex}\noindent\textbf{\xmlel{tr:DataLimits} Attributes} + +\begingroup\small\begin{bigdescription}\item[forMode] +\begin{description} +\item[Type] string +\item[Meaning] This declaration only applies to the named mode. +\item[Occurrence] optional + +\item[Allowed Values\vrule width 0pt depth 5pt]\hfil + \begin{longtermsdescription}\item[sync]This declaration is for synchronous queries. +\item[async]This declaration is for asynchronous queries. +\end{longtermsdescription} +\end{description} + +\end{bigdescription}\endgroup + + + \vspace{0.5ex}\noindent\textbf{\xmlel{tr:DataLimits} Metadata Elements} \begingroup\small\begin{bigdescription}\item[Element \xmlel{default}] @@ -953,8 +1065,8 @@ \subsubsection{Limits on Data} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd DataLimit \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:DataLimit} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:DataLimit} Type Schema Documentation} \noindent{\small{}A limit on some data size, either in rows or in bytes.\par} @@ -986,8 +1098,8 @@ \subsubsection{Limits on Data} \item[Meaning] The unit of the limit specified. \item[Occurrence] required -\item[Allowed Values]\hfil -\begin{longtermsdescription}\item[byte] +\item[Allowed Values\vrule width 0pt depth 5pt]\hfil + \begin{longtermsdescription}\item[byte] \item[row] \end{longtermsdescription} \end{description} @@ -1036,8 +1148,8 @@ \subsection{Interface Declaration} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd DALIInterface \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:DALIInterface} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:DALIInterface} Type Schema Documentation} \noindent{\small{}An interface for a complex, multi-endpoint interfaces as regulated by DALI.\par} @@ -1091,8 +1203,8 @@ \subsection{Interface Declaration} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd Endpoint \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:Endpoint} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:Endpoint} Type Schema Documentation} \noindent{\small{}An endpoint of a complex interface.\par} @@ -1160,8 +1272,8 @@ \subsection{Interface Declaration} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd MetaTriple \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:MetaTriple} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:MetaTriple} Type Schema Documentation} \noindent{\small{}A container for an RDFa triple giving information related to an endpoint.\par} @@ -1310,8 +1422,8 @@ \subsection{The Capability Record} % GENERATED: !schemadoc TAPRegExt-v1.1.xsd TableAccess \begin{generated} \begingroup - \renewcommand*\descriptionlabel[1]{% - \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:TableAccess} Type Schema Documentation} + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:TableAccess} Type Schema Documentation} \noindent{\small{}The capabilities of a TAP server.\par} @@ -1334,14 +1446,14 @@ \subsection{The Capability Record} + maxOccurs="unbounded" /> + maxOccurs="unbounded" /> + maxOccurs="unbounded" /> + maxOccurs="unbounded" /> @@ -1387,28 +1499,28 @@ \subsection{The Capability Record} \item[Type] composite: \xmlel{tr:TimeLimits} \item[Meaning] Limits on the time between job creation and destruction time. -\item[Occurrence] optional +\item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{executionDuration}] \begin{description} \item[Type] composite: \xmlel{tr:TimeLimits} \item[Meaning] Limits on executionDuration. -\item[Occurrence] optional +\item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{outputLimit}] \begin{description} \item[Type] composite: \xmlel{tr:DataLimits} \item[Meaning] Limits on the size of data returned. -\item[Occurrence] optional +\item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{uploadLimit}] \begin{description} \item[Type] composite: \xmlel{tr:DataLimits} \item[Meaning] Limits on the size of uploaded data. -\item[Occurrence] optional +\item[Occurrence] optional; multiple occurrences allowed. \end{description} @@ -1446,6 +1558,9 @@ \subsection{Changes from REC-1.0} \begin{itemize} \item Adding tr:DALIInterface to the schema. +\item Allowing a forMode attribute on outputFormat, uploadMethod, +retentionPeriod, executionDuration, outputLimit, and uploadLimit; to +make that work, allowing more than one of the limit elements now. \item Dropping the appendix with an example document. Using a standalone, validated file and auxiliaryurl instead. \end{itemize} diff --git a/make-sample.sh b/make-sample.sh index df2225b..a7b1e5e 100755 --- a/make-sample.sh +++ b/make-sample.sh @@ -8,9 +8,8 @@ curl -s http://localhost:8080/tap/capabilities \ | xmlstarlet ed \ -d "//capability[not(contains(@standardID, 'capabilities') or contains(@standardID, 'TAP'))]" \ - | xmlstarlet fo -o -s 2 + | xmlstarlet fo -o -s 2 > sample.xml -exit 0 STILTS=stilts SCHEMA_FILE=TAPRegExt-v1.1.xsd $STILTS xsdvalidate \ diff --git a/sample.xml b/sample.xml index cb884ba..2be6cb5 100644 --- a/sample.xml +++ b/sample.xml @@ -476,6 +476,9 @@ of the timestamp. 172800 + 50 + + 7200 @@ -483,6 +486,9 @@ of the timestamp. 20000000 + 10000000 + + 80000000