diff --git a/Makefile b/Makefile index e9d7eec..a46503b 100644 --- a/Makefile +++ b/Makefile @@ -28,7 +28,7 @@ VECTORFIGURES = # Additional files to distribute (e.g., CSS, schema files, examples...) -AUX_FILES = $(SCHEMA_FILE) sample.xml +AUX_FILES = $(SCHEMA_FILE) sample.xml -include ivoatex/Makefile @@ -37,13 +37,8 @@ ivoatex/Makefile: @echo git submodule update --init - sample.xml: make-sample.sh - ./make-sample.sh > sample.xml - -install: - # local to Markus' setup - ~/gavo/standards/fixschema $(SCHEMA_FILE) > ~/gavo/trunk/gavo/resources/schemata/TAPRegExt.xsd + ./make-sample.sh STILTS ?= stilts SCHEMA_FILE=TAPRegExt-v1.1.xsd diff --git a/TAPRegExt-v1.1.xsd b/TAPRegExt-v1.1.xsd index 82a5b4f..8149959 100644 --- a/TAPRegExt-v1.1.xsd +++ b/TAPRegExt-v1.1.xsd @@ -4,12 +4,12 @@ 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-pre2" 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"> +> TAPRegExt @@ -82,8 +82,7 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber minOccurs="0" maxOccurs="1"> - Limits on the time between job creation and - destruction time. + Default limits for how long a service will retain async jobs. @@ -92,7 +91,7 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber minOccurs="0" maxOccurs="1"> - Limits on executionDuration. + Default limits on the time after which a query will be cancelled. @@ -101,7 +100,7 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber minOccurs="0" maxOccurs="1"> - Limits on the size of data returned. + Deafult limits on the size of data returned. @@ -110,12 +109,19 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber minOccurs="0" maxOccurs="1"> - Limits on the size of uploaded data. + Default limits on the size of uploaded data. - + + + + Per-mode overrides of the limits defined gobally. + + + @@ -602,4 +608,93 @@ xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://vo.ari.uni-heidelber + + + + The limits corresponding to an access mode (auth/non-auth, sync/async). + + + + + + + + Limits for how long a service will retain async jobs + in this limit element's mode. + + + + + + + + Limits on the time after which a query will be cancelled + in this limit element's mode. + + + + + + + + Limits on the size of data returned + in this limit element's mode. + + + + + + + + Limits on the size of uploaded data + in this limit element's mode. + + + + + + + + + + + + These limits apply to unauthenticated clients running + synchronous queries. + + + + + + + These limits apply to unauthenticated clients running + asynchronous queries. + + + + + + + These limits apply to authenticated clients running + synchronous queries. + + + + + + + These limits apply to authenticated clients running + asynchronous queries. + + + + + + + + diff --git a/TAPRegExt.tex b/TAPRegExt.tex index e3fef75..bbd7362 100644 --- a/TAPRegExt.tex +++ b/TAPRegExt.tex @@ -84,6 +84,14 @@ \section{Introduction} VOResource record, the capability elements would be direct children of the \xmlel{vr:Resource} element. +The specification comes with a non-normative example +document\footnote{\auxiliaryurl{sample.xml}} showing this +specification's major features. It also declares a separate capability +for the VOSI capabilities endpoint. The example is written as a +response from a TAP service's capabilities endpoint. When embedded in a +VOResource record, the capability elements would be direct children of +the \xmlel{vr:Resource} element. + \subsection{TAPRegExt within the VO Architecture} @@ -192,12 +200,14 @@ \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 +\noindent{\small + An IVOA defined data model, identified by an IVORN intended for machine consumption and a short label - intended for human comsumption.\par} + intended for human comsumption. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:DataModelType} Type Schema Definition} @@ -217,7 +227,9 @@ \subsection{Declaring Instantiated Data Models} \item[ivo-id] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} -\item[Meaning] The IVOID of the data model. +\item[Meaning] + The IVOID of the data model. + \item[Occurrence] required \end{description} @@ -262,14 +274,18 @@ \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} +\noindent{\small + A query language supported by the service. + \par} -\noindent{\small{}Each language element can describe one or more versions +\noindent{\small + Each language element can describe one or more versions of a language. Either name alone or name-version can be - used as values for the server's LANG parameter.\par} + used as values for the server's LANG parameter. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:Language} Type Schema Definition} @@ -293,34 +309,44 @@ \subsection{Languages Supported} \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}] \begin{description} \item[Type] a prefixless XML name -\item[Meaning] The name of the language without a version suffix. +\item[Meaning] + The name of the language without a version suffix. + \item[Occurrence] required \end{description} \item[Element \xmlel{version}] \begin{description} \item[Type] a string with optional attributes -\item[Meaning] A version of the language supported by the server. +\item[Meaning] + A version of the language supported by the server. + \item[Occurrence] required; multiple occurrences allowed. \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:token} -\item[Meaning] A short, human-readable description of the +\item[Meaning] + A short, human-readable description of the query language. + \item[Occurrence] optional \end{description} \item[Element \xmlel{languageFeatures}] \begin{description} \item[Type] composite: \xmlel{tr:LanguageFeatureList} -\item[Meaning] Optional features of the query language, grouped by +\item[Meaning] + Optional features of the query language, grouped by feature type. + \item[Occurrence] optional; multiple occurrences allowed. -\item[Comment] This includes listing user defined functions, geometry support, +\item[Comment] + This includes listing user defined functions, geometry support, or similar concepts. + \end{description} @@ -334,17 +360,21 @@ \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} +\noindent{\small + One version of the language supported by the service. + \par} -\noindent{\small{}If the service supports more than one version of the +\noindent{\small + If the service supports more than one version of the language, include multiple version elements. It is recommended that you use a version numbering scheme like MAJOR.MINOR in such a way that sorting by ascending character codes will leave the most - recent version at the bottom of the list.\par} + recent version at the bottom of the list. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:Version} Type Schema Definition} @@ -364,13 +394,17 @@ \subsection{Languages Supported} \item[ivo-id] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} -\item[Meaning] An optional IVOID of the language. +\item[Meaning] + An optional IVOID of the language. + \item[Occurrence] optional -\item[Comment] To more formally define a language supported by a service, +\item[Comment] + To more formally define a language supported by a service, a resource record for the language can be created, either centrally on the Registry of Registries or by other registry operators. When such a record exists, the ivo-id attribute of language should point to it. + \end{description} @@ -463,13 +497,16 @@ \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} +\noindent{\small + An enumeration of non-standard or non-mandatory features of + a specific type implemented by the language. + \par} -\noindent{\small{}A feature type is a language-dependent concept like +\noindent{\small + A feature type is a language-dependent concept like {"}user defined function{"}, {"}geometry support{"}, or possibly {"}units supported{"}. A featureList gives all features of a given type applicable for the service. Multiple featureLists @@ -480,7 +517,8 @@ \subsection{Languages Supported} the value of which will typically be an IVOID. To see values defined in TAPRegExt, retrieve the ivo://ivoa.net/std/TAPRegExt - resource record and look for keys starting with {"}features-{"}.\par} + resource record and look for keys starting with {"}features-{"}. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:LanguageFeatureList} Type Schema Definition} @@ -500,11 +538,15 @@ \subsection{Languages Supported} \item[type] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} -\item[Meaning] The type of the features given here. +\item[Meaning] + The type of the features given here. + \item[Occurrence] required -\item[Comment] This is in general an IVOID. TAPRegExt itself gives +\item[Comment] + This is in general an IVOID. TAPRegExt itself gives IVOIDs for defining user defined functions and geometry support. + \end{description} @@ -517,8 +559,10 @@ \subsection{Languages Supported} \begingroup\small\begin{bigdescription}\item[Element \xmlel{feature}] \begin{description} \item[Type] composite: \xmlel{tr:LanguageFeature} -\item[Meaning] A language feature of the type given by the +\item[Meaning] + A language feature of the type given by the type attribute. + \item[Occurrence] optional; multiple occurrences allowed. \end{description} @@ -534,11 +578,13 @@ \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} +\noindent{\small + A non-standard or non-mandatory feature implemented + by the language.. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:LanguageFeature} Type Schema Definition} @@ -556,16 +602,22 @@ \subsection{Languages Supported} \begingroup\small\begin{bigdescription}\item[Element \xmlel{form}] \begin{description} \item[Type] string: \xmlel{xs:token} -\item[Meaning] Formal notation for the language feature. +\item[Meaning] + Formal notation for the language feature. + \item[Occurrence] required -\item[Comment] The syntax for the content of this element is defined by the +\item[Comment] + The syntax for the content of this element is defined by the type attribute of its parent language list. + \end{description} \item[Element \xmlel{description}] \begin{description} \item[Type] string: \xmlel{xs:string} -\item[Meaning] Human-readable freeform documentation for the language feature. +\item[Meaning] + Human-readable freeform documentation for the language feature. + \item[Occurrence] optional \end{description} @@ -603,12 +655,15 @@ \subsection{Output Formats} % 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} +\noindent{\small + An output format supported by the service. + \par} -\noindent{\small{}All TAP services must support VOTable output, with media types as +\noindent{\small + All TAP services must support VOTable output, with media types as requested by the FORMAT parameter if applicable (cf.~section 2.7.1 of the TAP standard). @@ -617,7 +672,8 @@ \subsection{Output Formats} use a media type (or make one up using the x- syntax), although the concrete media syntax is not enforced by the schema. - For more detailed specification, an IVOID may be used.\par} + For more detailed specification, an IVOID may be used. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:OutputFormat} Type Schema Definition} @@ -628,7 +684,6 @@ \subsection{Output Formats} - \end{lstlisting} @@ -639,15 +694,19 @@ \subsection{Output Formats} \item[ivo-id] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} -\item[Meaning] An optional IVOID of the output format. +\item[Meaning] + An optional IVOID of the output format. + \item[Occurrence] optional -\item[Comment] When the media type does not uniquely define the +\item[Comment] + When the media type does not uniquely define the format (or a generic media type like application/octet-stream or text/plain is given), the IVOID can point to a key or StandardsRegExt document defining the format more precisely. To see values defined in TAPRegExt, retrieve the ivo://ivoa.net/std/TAPRegExt resource record and look for keys starting with {"}output-{"}. + \end{description} @@ -660,18 +719,24 @@ \subsection{Output Formats} \begingroup\small\begin{bigdescription}\item[Element \xmlel{mime}] \begin{description} \item[Type] string: \xmlel{xs:token} -\item[Meaning] The media type of this format. +\item[Meaning] + The media type of this format. + \item[Occurrence] required -\item[Comment] The format of this string is specified by RFC 2046. +\item[Comment] + The format of this string is specified by RFC 2046. The service has to accept this string as a value of the FORMAT parameter. + \end{description} \item[Element \xmlel{alias}] \begin{description} \item[Type] string: \xmlel{xs:token} -\item[Meaning] Other values of FORMAT ({"}shorthands{"}) that make the service return +\item[Meaning] + Other values of FORMAT ({"}shorthands{"}) that make the service return documents with the media type. + \item[Occurrence] optional; multiple occurrences allowed. \end{description} @@ -736,12 +801,15 @@ \subsection{Upload Methods} % 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} +\noindent{\small + An upload method as defined by IVOA. + \par} -\noindent{\small{}Upload methods are always identified by an IVOID. +\noindent{\small + Upload methods are always identified by an IVOID. Descriptions can be obtained by dereferencing this IVOID. To see values defined in TAPRegExt, retrieve the ivo://ivoa.net/std/TAPRegExt @@ -749,7 +817,8 @@ \subsection{Upload Methods} You can register custom upload methods, but you must use the standard IVOIDs for the upload methods defined in the TAP - specification.\par} + specification. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:UploadMethod} Type Schema Definition} @@ -769,7 +838,9 @@ \subsection{Upload Methods} \item[ivo-id] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} -\item[Meaning] The IVOID of the upload method. +\item[Meaning] + The IVOID of the upload method. + \item[Occurrence] optional \end{description} @@ -799,13 +870,6 @@ \subsection{Resource Limits} conservative guidelines. Thus, the operators of a service implementing a complex, possibly dynamic limits policy should give lower estimates here. -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 -authentication tokens are present in the request). Limits reported to -the Registry should reflect limits for unauthenticated use unless the -service does not admit unauthenticated requests. - The resource limits applying to newly created jobs are given in \xmlel{default} elements, the limits beyond which users cannot raise the limits are given in \xmlel{hard} elements. @@ -813,6 +877,10 @@ \subsection{Resource Limits} Note that the absence of a specification of limits does not imply that no limits are enforced. +Limits can be specified as direct children of \xmlel{capability}, or in +\xmlel{limits} groups as per Sect.~\ref{sect:permode}. The limits in +direct children give defaults, overrideable in the limits groups for +specific modes. \subsubsection{Limits on Time} This document defines two time-like resource limits: @@ -834,10 +902,12 @@ \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} +\noindent{\small + Time-valued limits, all values given in seconds. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:TimeLimits} Type Schema Definition} @@ -856,14 +926,18 @@ \subsubsection{Limits on Time} \begingroup\small\begin{bigdescription}\item[Element \xmlel{default}] \begin{description} \item[Type] integer -\item[Meaning] The value of this limit for newly-created jobs, given in seconds. +\item[Meaning] + The value of this limit for newly-created jobs, given in seconds. + \item[Occurrence] optional \end{description} \item[Element \xmlel{hard}] \begin{description} \item[Type] integer -\item[Meaning] The value this limit cannot be raised above, given in seconds. +\item[Meaning] + The value this limit cannot be raised above, given in seconds. + \item[Occurrence] optional \end{description} @@ -907,10 +981,12 @@ \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} +\noindent{\small + Limits on data sizes, given in rows or bytes. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:DataLimits} Type Schema Definition} @@ -930,14 +1006,18 @@ \subsubsection{Limits on Data} \begingroup\small\begin{bigdescription}\item[Element \xmlel{default}] \begin{description} \item[Type] an integer with optional attributes -\item[Meaning] The value of this limit for newly-created jobs. +\item[Meaning] + The value of this limit for newly-created jobs. + \item[Occurrence] optional \end{description} \item[Element \xmlel{hard}] \begin{description} \item[Type] an integer with optional attributes -\item[Meaning] The value this limit cannot be raised above. +\item[Meaning] + The value this limit cannot be raised above. + \item[Occurrence] optional \end{description} @@ -953,10 +1033,12 @@ \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} +\noindent{\small + A limit on some data size, either in rows or in bytes. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:DataLimit} Type Schema Definition} @@ -983,7 +1065,9 @@ \subsubsection{Limits on Data} \item[unit] \begin{description} \item[Type] string with controlled vocabulary -\item[Meaning] The unit of the limit specified. +\item[Meaning] + The unit of the limit specified. + \item[Occurrence] required \item[Allowed Values]\hfil @@ -1000,6 +1084,163 @@ \subsubsection{Limits on Data} % /GENERATED +\subsubsection{Per-Mode Limits} +\label{sect:permode} + +TAP services may have separate policies for authenticated and anonymous +usage, and they may apply different limits to sync versus async queries. +To inform clients about these, the limits defined above can be +overridden in \xmlel{limits} elements qualifed with a \xmlel{mode} +attribute, which is restricted by the schema to be one of: + +\begin{itemize} +\item \emph{anonymous-sync} -- the limits given apply to clients that do +synchronous queries without authentication. Since this is what the +global values describe in TAPRegExt version 1.1, it should not be +necessary to override anything in a limits block with this mode. + +\item \emph{anonymous-async} -- the limits given apply to clients that +do asynchronous queries without authentication. + +\item \emph{auth-sync} -- the limits given apply to clients that do +synchronous queries with suitable authentication. + +\item \emph{auth-async} -- the limits given apply to clients that do +asynchronous queries with suitable authentication. +\end{itemize} + +No \xmlel{limits} groups need to be given when services have no reason +to override the ``global'' limits defined at the root level of the +capability. Note that the per-mode limits will be ignored by clients +supporting only TAPRegExt 1.0, and they are also invisible in RegTAP, at +least to its version 1.2. + +The \xmlel{limits} elements are of type \xmlel{tr:PerModeLimits}: + +% GENERATED: !schemadoc TAPRegExt-v1.1.xsd PerModeLimits +\begin{generated} +\begingroup + \renewcommand*\descriptionlabel[1]{% + \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{tr:PerModeLimits} Type Schema Documentation} + +\noindent{\small + The limits corresponding to an access mode (auth/non-auth, sync/async). + \par} + +\vspace{1ex}\noindent\textbf{\xmlel{tr:PerModeLimits} Type Schema Definition} + +\begin{lstlisting}[language=XML,basicstyle=\footnotesize] + + + + + + + + + + + + + + + + + + +\end{lstlisting} + +\vspace{0.5ex}\noindent\textbf{\xmlel{tr:PerModeLimits} Attributes} + +\begingroup\small\begin{bigdescription} +\item[mode] +\begin{description} +\item[Type] string +\item[Meaning] +\item[Occurrence] optional + +\item[Allowed Values]\hfil +\begin{longtermsdescription}\item[anonymous-sync] + These limits apply to unauthenticated clients running + synchronous queries. + +\item[anonymous-async] + These limits apply to unauthenticated clients running + asynchronous queries. + +\item[auth-sync] + These limits apply to authenticated clients running + synchronous queries. + +\item[auth-async] + These limits apply to authenticated clients running + asynchronous queries. + +\end{longtermsdescription} +\end{description} + + +\end{bigdescription}\endgroup + + + +\vspace{0.5ex}\noindent\textbf{\xmlel{tr:PerModeLimits} Metadata Elements} + +\begingroup\small\begin{bigdescription}\item[Element \xmlel{retentionPeriod}] +\begin{description} +\item[Type] composite: \xmlel{tr:TimeLimits} +\item[Meaning] + Limits for how long a service will retain async jobs + in this limit element's mode. + +\item[Occurrence] optional + +\end{description} +\item[Element \xmlel{executionDuration}] +\begin{description} +\item[Type] composite: \xmlel{tr:TimeLimits} +\item[Meaning] + Limits on the time after which a query will be cancelled + in this limit element's mode. + +\item[Occurrence] optional + +\end{description} +\item[Element \xmlel{outputLimit}] +\begin{description} +\item[Type] composite: \xmlel{tr:DataLimits} +\item[Meaning] + Limits on the size of data returned + in this limit element's mode. + +\item[Occurrence] optional + +\end{description} +\item[Element \xmlel{uploadLimit}] +\begin{description} +\item[Type] composite: \xmlel{tr:DataLimits} +\item[Meaning] + Limits on the size of uploaded data + in this limit element's mode. + +\item[Occurrence] optional + +\end{description} + + +\end{bigdescription}\endgroup + +\endgroup +\end{generated} + +% /GENERATED + + \subsection{Interface Declaration} \label{intfdecl} @@ -1036,16 +1277,20 @@ \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} +\noindent{\small + An interface for a complex, multi-endpoint interfaces as + regulated by DALI. + \par} -\noindent{\small{}In addition to the standard vr:Interface elements, DALIInterfaces +\noindent{\small + In addition to the standard vr:Interface elements, DALIInterfaces have endpoints, listed by name; that name doubles as a path segment to append to the interface's access URL, yielding the URI at - which the endpoint is operated.\par} + which the endpoint is operated. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:DALIInterface} Type Schema Definition} @@ -1067,7 +1312,9 @@ \subsection{Interface Declaration} \begingroup\small\begin{bigdescription}\item[Element \xmlel{endpoint}] \begin{description} \item[Type] composite: \xmlel{tr:Endpoint} -\item[Meaning] An endpoint accessible through this interface. +\item[Meaning] + An endpoint accessible through this interface. + \item[Occurrence] optional; multiple occurrences allowed. \end{description} @@ -1091,15 +1338,19 @@ \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} +\noindent{\small + An endpoint of a complex interface. + \par} -\noindent{\small{}An endpoint is characterised and addressed by its name; +\noindent{\small + An endpoint is characterised and addressed by its name; they can further be defined through RDF triples. This is a generic extension mechanism for endpoint-specific metadata, - primarily intended for custom, vendor-specific extensions.\par} + primarily intended for custom, vendor-specific extensions. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:Endpoint} Type Schema Definition} @@ -1118,18 +1369,24 @@ \subsection{Interface Declaration} \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}] \begin{description} \item[Type] string: \xmlel{xs:token} -\item[Meaning] The endpoint name, which is also the last component of the +\item[Meaning] + The endpoint name, which is also the last component of the path of its URI. + \item[Occurrence] required -\item[Comment] Names without dashes are reserved for IVOA use and are expected to +\item[Comment] + Names without dashes are reserved for IVOA use and are expected to work the same way on all services. Well-known examples for such endpoint names include sync, async, and tables. + \end{description} \item[Element \xmlel{meta}] \begin{description} \item[Type] a string with optional attributes -\item[Meaning] Auxiliary information on this endpoint. +\item[Meaning] + Auxiliary information on this endpoint. + \item[Occurrence] optional; multiple occurrences allowed. \end{description} @@ -1160,11 +1417,13 @@ \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} +\noindent{\small + A container for an RDFa triple giving information related to + an endpoint. + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:MetaTriple} Type Schema Definition} @@ -1186,27 +1445,39 @@ \subsection{Interface Declaration} \item[about] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} -\item[Meaning] The subject of the statement. +\item[Meaning] + The subject of the statement. + \item[Occurrence] optional -\item[Comment] If missing, the endpoint itself is assumed as the subject. +\item[Comment] + If missing, the endpoint itself is assumed as the subject. + \end{description} \item[property] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} -\item[Meaning] The property of the statement. +\item[Meaning] + The property of the statement. + \item[Occurrence] required -\item[Comment] This is a reference to an RDF resource. IVOA standards may define +\item[Comment] + This is a reference to an RDF resource. IVOA standards may define semantics for scheme-less URI; non-IVOA properties must use full URIs with at least scheme and authority; in this version, no vocab attributes are supported. + \end{description} \item[resource] \begin{description} \item[Type] a URI: \xmlel{xs:anyURI} -\item[Meaning] The object of the statement. +\item[Meaning] + The object of the statement. + \item[Occurrence] optional -\item[Comment] If missing, the text content of the element is used as the +\item[Comment] + If missing, the text content of the element is used as the object. + \end{description} @@ -1310,13 +1581,17 @@ \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} +\noindent{\small + The capabilities of a TAP server. + \par} -\noindent{\small{}The capabilities attempt to define most issues that the - TAP standard leaves to the implementors ({"}may{"}, {"}should{"}).\par} +\noindent{\small + The capabilities attempt to define most issues that the + TAP standard leaves to the implementors ({"}may{"}, {"}should{"}). + \par} \vspace{1ex}\noindent\textbf{\xmlel{tr:TableAccess} Type Schema Definition} @@ -1342,6 +1617,7 @@ \subsection{The Capability Record} maxOccurs="1" /> + @@ -1353,61 +1629,87 @@ \subsection{The Capability Record} \begingroup\small\begin{bigdescription}\item[Element \xmlel{dataModel}] \begin{description} \item[Type] a string with optional attributes -\item[Meaning] Identifier of IVOA-approved data model supported by the +\item[Meaning] + Identifier of IVOA-approved data model supported by the service. + \item[Occurrence] optional; multiple occurrences allowed. \end{description} \item[Element \xmlel{language}] \begin{description} \item[Type] composite: \xmlel{tr:Language} -\item[Meaning] Language supported by the service. +\item[Meaning] + Language supported by the service. + \item[Occurrence] required; multiple occurrences allowed. \end{description} \item[Element \xmlel{outputFormat}] \begin{description} \item[Type] composite: \xmlel{tr:OutputFormat} -\item[Meaning] Output format supported by the service. +\item[Meaning] + Output format supported by the service. + \item[Occurrence] required; multiple occurrences allowed. \end{description} \item[Element \xmlel{uploadMethod}] \begin{description} \item[Type] composite: \xmlel{tr:UploadMethod} -\item[Meaning] Upload method supported by the service. +\item[Meaning] + Upload method supported by the service. + \item[Occurrence] optional; multiple occurrences allowed. -\item[Comment] The absence of upload methods indicates +\item[Comment] + The absence of upload methods indicates that the service does not support uploads at all. + \end{description} \item[Element \xmlel{retentionPeriod}] \begin{description} \item[Type] composite: \xmlel{tr:TimeLimits} -\item[Meaning] Limits on the time between job creation and - destruction time. +\item[Meaning] + Default limits for how long a service will retain async jobs. + \item[Occurrence] optional \end{description} \item[Element \xmlel{executionDuration}] \begin{description} \item[Type] composite: \xmlel{tr:TimeLimits} -\item[Meaning] Limits on executionDuration. +\item[Meaning] + Default limits on the time after which a query will be cancelled. + \item[Occurrence] optional \end{description} \item[Element \xmlel{outputLimit}] \begin{description} \item[Type] composite: \xmlel{tr:DataLimits} -\item[Meaning] Limits on the size of data returned. +\item[Meaning] + Deafult limits on the size of data returned. + \item[Occurrence] optional \end{description} \item[Element \xmlel{uploadLimit}] \begin{description} \item[Type] composite: \xmlel{tr:DataLimits} -\item[Meaning] Limits on the size of uploaded data. +\item[Meaning] + Default limits on the size of uploaded data. + +\item[Occurrence] optional + +\end{description} +\item[Element \xmlel{limits}] +\begin{description} +\item[Type] composite: \xmlel{tr:PerModeLimits} +\item[Meaning] + Per-mode overrides of the limits defined gobally. + \item[Occurrence] optional \end{description} @@ -1448,6 +1750,8 @@ \subsection{Changes from REC-1.0} \item Adding tr:DALIInterface to the schema. \item Dropping the appendix with an example document. Using a standalone, validated file and auxiliaryurl instead. +\item Adding a \xmlel{limits} element to declare different limits by +access mode. \end{itemize} \subsection{Changes from WD-20110127} diff --git a/make-sample.sh b/make-sample.sh index df2225b..a76cfb0 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 \ @@ -18,4 +17,3 @@ $STILTS xsdvalidate \ schemaloc="http://www.ivoa.net/xml/VOSICapabilities/v1.0=https://www.ivoa.net/xml/VOSICapabilities/v1.0" \ schemaloc="http://www.ivoa.net/xml/VODataService/v1.1=https://www.ivoa.net/xml/VODataService/v1.1" \ doc=sample.xml - diff --git a/role_diagram.pdf b/role_diagram.pdf index 37f9449..ed27c3e 100644 Binary files a/role_diagram.pdf and b/role_diagram.pdf differ diff --git a/role_diagram.svg b/role_diagram.svg index 276d13c..ea1815e 100644 --- a/role_diagram.svg +++ b/role_diagram.svg @@ -1,43 +1,43 @@ -IVOA Architecture DiagramThis image shows the architecture of the Virtual Observatory - (cf. http://ivoa.net), together with the relevant standards.UsersComputersProvidersRegistryData Access ProtocolsUser LayerUsingResource LayerSharingVOCoreFindingGettingDesktop AppsIn-BrowserAppsUserProgramsData and Metadata CollectionStorageComputationSemanticsDataModelsVO QueryLanguagesFormats +IVOA Architecture DiagramThis image shows the architecture of the Virtual Observatory + (cf. http://ivoa.net), together with the relevant standards.UsersComputersProvidersRegistryData Access ProtocolsUser LayerUsingResource LayerSharingVOCoreFindingGettingDesktop AppsIn-BrowserAppsUserProgramsData and Metadata CollectionStorageComputationSemanticsDataModelsVO QueryLanguagesFormats VOResource Resource M.D. diff --git a/sample.xml b/sample.xml index cb884ba..635dd1a 100644 --- a/sample.xml +++ b/sample.xml @@ -476,15 +476,23 @@ of the timestamp. 172800 - 7200 + 50 20000 20000000 - 80000000 + 100000000 + + + 7200 + + + 80000000 + +