From aae95b89cd0fc8a736152e0ccf3761bb30bfb829 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 2 Dec 2014 21:49:33 +0000 Subject: [PATCH 01/68] create TAP document From 8f2a7261b04c381247e01c307443232a2a06691d Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 4 Dec 2014 22:05:11 +0000 Subject: [PATCH 02/68] initial commit with approximately TAP-1.0 content --- Makefile | 25 + TAP.tex | 1447 ++++++++++++++++++++++++++++++++++++++++++++++++++ archdiag.png | Bin 0 -> 60491 bytes 3 files changed, 1472 insertions(+) create mode 100644 Makefile create mode 100644 TAP.tex create mode 100644 archdiag.png diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..5f4eaab --- /dev/null +++ b/Makefile @@ -0,0 +1,25 @@ +# ivoatex Makefile. The ivoatex/README for the targets available. + +# short name of your document (edit $DOCNAME.tex; would be like RegTAP) +DOCNAME = TAP + +# count up; you probably do not want to bother with versions <1.0 +DOCVERSION = 1.1 + +# Publication date, ISO format; update manually for "releases" +DOCDATE = 2014-12-15 + +# What is it you're writing: NOTE, WD, PR, or REC +DOCTYPE = WD + +# Source files for the TeX document (but the main file must always +# be called $(DOCNAME).tex +SOURCES = $(DOCNAME).tex + +# List of pixel image files to be included in submitted package +FIGURES = archdiag.png + +# List of PDF figures (for vector graphics) +VECTORFIGURES = + +include ivoatex/Makefile diff --git a/TAP.tex b/TAP.tex new file mode 100644 index 0000000..df54302 --- /dev/null +++ b/TAP.tex @@ -0,0 +1,1447 @@ +\documentclass[11pt,a4paper]{ivoa} +\input tthdefs + +\usepackage[utf8]{inputenc} + +\title{Table Access Protocol} + +\ivoagroup{Data Access Layer Working Group} + +\author{Patrick Dowler} +\author{TBD} + +\editor{Patrick Dowler} + +\previousversion[http://www.ivoa.net/Documents/TAP/1.0]{TAP-1.0} + + +\begin{document} + +\begin{abstract} +The table access protocol (TAP) defines a service protocol for accessing general +table data, including astronomical catalogs as well as general database tables. +Access is provided for both database and table metadata as well as for actual +table data. This version of the protocol includes support for multiple query +languages, including queries specified using the Astronomical Data Query +Language (ADQL [1]) and the Parameterised Query Language (PQL, under +development) within an integrated interface. It also includes support for both +synchronous and asynchronous queries. Special support is provided for spatially +indexed queries using the spatial extensions in ADQL. A multi-position query +capability permits queries against an arbitrarily large list of astronomical +targets, providing a simple spatial cross-matching capability. More +sophisticated distributed cross-matching capabilities are possible by +orchestrating a distributed query across multiple TAP services. +\end{abstract} + + +\section*{Acknowledgments} + +The authors would like to acknowledge all contributors to this and previous +versions of this standard, especially: K. Andrews, J. Good, R. Hanisch, G. +Lemson, T. McGlynn, K. Noddle, F. Ochsenbein, I. Ortiz, P. Osuna, R. Plante, G. +Rixon, J. Salgado, A. Stebe, and A. Szalay. + + +\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, \citet{std:RFC2119}. + +The \emph{Virtual Observatory (VO)} is 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} +The Table Access Protocol (TAP) is a Web-service protocol that gives access to +collections of tabular data referred to collectively as a tableset. TAP +services accept queries posed against the tableset available via the service and +return the query response as another table, in accord with the relational model. + Queries may be submitted using various query languages and may execute +synchronously or asynchronously. Support for the Astronomical Data Query +Language (ADQL, [1]) is mandatory; support for other query languages such as +Parameterised Query Language (PQL, under development) or native SQL is optional. + +The result of a TAP query is another table, normally returned as a VOTable. +Support for VOTable output is mandatory; all other formats are optional. + +The table collections made accessible via TAP are typically stored in relational +database management systems (RDBMS). A TAP service exposes the database schema +to client applications so that queries can be posed directly against arbitrary +data tables available via the service. + +Multi-table operations such as joins or cross matches are possible provided the +tables are all managed by the local TAP service, and provided the service +supports these capabilities. Larger scale operations such as a distributed +cross match are also possible, but require combining the results of multiple TAP +services. + +\subsection{Query Types} +TAP services support three kinds of queries: data queries, metadata queries, and +Virtual Observatory Support Interface (VOSI [6]) queries. + +\subsubsection{Data Queries} +Data queries apply to the astronomical content served by a TAP service. This is +the reason for providing a TAP service. All the other kinds of query support the +ability to make data queries. Data queries may be specified in any query +language supported by the service. + +\subsubsection{Metadata Queries} +Metadata queries work like data queries, using the same query languages, but +they are applied to standardized tables that are a subset of, and patterned +after, information schema in RDBMS; the content of these tables explains the +data model of a particular TAP service. Metadata queries allow a client to +discover the names of tables and columns to be used in data queries. + +\subsubsection{VOSI} +Metadata queries work like data queries, using the same query languages, but +they are applied to standardized tables that are a subset of, and patterned +after, information schema in RDBMS; the content of these tables explains the +data model of a particular TAP service. Metadata queries allow a client to +discover the names of tables and columns to be used in data queries. + +\subsection{Query Languages} +TAP supports the use of multiple query languages, some of which are described +here. + +\subsubsection{ADQL Queries} +Support for ADQL queries is mandatory. ADQL can be used to specify queries that +access one or more tables provided by the TAP service, including the standard +metadata tables. In general, the client must access table metadata in order to +discover the names of tables and columns and then formulate queries. ADQL +queries provide a direct (low-level) access to the tables; a query will be +written for a specific TAP service and will not be usable with other services +unless the query refers only to common tables and columns. It is also possible +that the service registration (in an IVOA Registry) may include sufficient +table metadata to enable queries to be written directly. + +Details of the ADQL language may be found in [1]. + +\subsubsection{PQL} +Support for PQL is optional. PQL can be used to formulate queries that access a +single table provided by the TAP service, including the standard set of metadata +tables. PQL can also be used in some cases without first querying the metadata +tables by using the PQL parameters which carry sufficient meaning to enable the +service to decide which tables and columns to use (e.g. POS, SIZE, REGION, BAND, +TIME). + +Details of the PQL language (parameters) are not part of the TAP specification. + +\subsubsection{Other Query Languages} +A TAP service may also support use of other query languages, including +pass-through of native SQL directly to an underlying DBMS, by describing such +capabilities in the service metadata and allowing custom values of the service +parameters. This mechanism allows future developments within the VOQL Working +Group and outside the IVOA to be used without revising the TAP specification. + +\subsection{Query Execution} +The TAP service specification defines both synchronous and asynchronous query +execution. Users select synchronous or asynchronous execution by chosing the +appropriate resource below the base URL for the service (see 2.2 ). A query is +synchronous if the results of the query are delivered in the HTTP response to +the request that originally posed the query. If the service returns an immediate +HTTP-response upon accepting a query and the client later obtains the results of +the query in response to a separate HTTP request, then we say the request is +asynchronous. + +\subsubsection{Asynchronous Queries} +Asynchronous query support is mandatory. Asynchronous queries require that +client and server share knowledge of the state of the query during its execution +and between HTTP exchanges. They are an example of stateful interactions. In +TAP, the mechanism by which the clients and services share the state of +transactions is based on the Universal Worker Service (UWS) pattern [3]. + +\subsubsection{Synchronous Queries} +Synchronous query support is mandatory. Synchronous queries execute immediately +and the client must wait for the query to finish. If the HTTP request times out +or the client otherwise loses the connection to the service before receiving the +response, then the query fails. + +Synchronous query execution is adequate when the query will execute quickly and +with a small number of results, or when they can at least start returning +results quickly. They are generally simple to implement using standard web +technologies and easy to use from a browser or scripting environment. However, +synchronous requests are generally not sufficient and are likely to fail for +queries that take a long time to execute, especially before returning any +results. + +\subsection{Interface Overview} +Table Access Protocol (TAP) is implemented over the HTTP protocol using standard +HTTP GET and POST requests and conventions. A TAP request specifies one or more +parameter key/value pairs; both keys and values are strings. The keys used are +discussed in this specification and in the specifications for query languages +supported by a service. The values may need to be encoded, using standard +URL-encoding. For the following examples, http://example.com/tap/ is the base +URL for a TAP service. + +This is an example of a synchronous ADQL query on r magnitude: + +\begin{verbatim} +HTTP POST htp://example.com/tap/sync +REQUEST=doQuery +LANG=ADQL +QUERY=SELECT * FROM magnitudes as m where m.r>=10 and m.r<=16 +\end{verbatim} + +NOTE: equivalent PQL that was in TAP-1.0 doc removed + +Synchronous queries return the table of results in the HTTP response to the +initial request. In the examples above, the output format defaults to VOTable; +the FORMAT parameter could be added to select a different format. + +Asynchronous queries are created in the same way as the synchronous kind, using +the /async endpoint: + +\begin{verbatim} +HTTP POST http://example.com/tap/async +REQUEST=doQuery +LANG=ADQL +QUERY=SELECT * FROM magnitudes AS m WHERE m.r>=10 AND m.r<=16 +\end{verbatim} + +NOTE: equivalent PQL that was in TAP-1.0 doc removed + +The service's response to these requests is a URL representing the query's state +and progress and where the state may be monitored and controlled. The query +result or an error document can then be retrieved from a URL associated with the +job. This is an application of the UWS pattern. The query is then executed +with a separate request to run the job URL: + +\begin{verbatim} +HTTP POST http://example.com/tap/async//phase +PHASE=RUN +\end{verbatim} + +In addition to the sync and async resources for query execution, a TAP service +also has metadata resources defined by the VOSI standard. The availability of a +service can be monitored by accessing: + +\begin{verbatim} +HTTP GET http://example.com/tap/availability +\end{verbatim} + +See 2.2.3 for details of the availability resource. + +The complete table metadata can be obtained: + +\begin{verbatim} +HTTP GET http://example.com/tap/tables +\end{verbatim} + +See 2.2.5 for details of the table metadata resource. + +The capabilities can be obtained by: + +\begin{verbatim} +HTTP GET http://example.com/tap/capabilities +\end{verbatim} + +The capabilities are also accessible via a service request to the synchronous +query resource: + +\begin{verbatim} +HTTP GET http://example.com/tap/sync?REQUEST=getCapabilities +\end{verbatim} + +This output lists support for optional TAP functionality and additional +implemented interfaces. See 2.2.4 for details. + + +\subsection{Role within the VO Architecture} + +NOTE: not in TAP-1.0 + +\begin{figure} +\centering + +% Get the architecture diagram from the TCG chair +% http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG +% If they give you a PDF, for now dumb it down to a png by +% convert -antialias -density 72x72 archdiag.pdf archdiag.png +% Oh -- Notes don't need this; you'd have to remove archdiag.png +% from FIGURES in the Makefile, too. + +\includegraphics[width=0.9\textwidth]{archdiag.png} +\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{Requirements for a TAP Service} + +NOTE: pre-amble about must, should, and may that was here in 1.0 removed since +it is alteady included above + +The TAP standard is identified using standardID="ivo://ivoa.net/std/TAP". This +document specified version 1.0 of the standard. + +\subsection{Feature Overview} +An implementation of a TAP service provides features as follows. + +\begin{tabular}{l l l l l} +synchronous query execution & /sync & must & & \\ +asynchronous query execution & /async & must & & \\ +VOSI-availability & /availability & should & & \\ +VOSI-capabilities & /capabilities & must & & \\ +VOSI-tables & /tables & should & REQUEST=getCapabilities & must \\ +ADQL queries & & & REQUEST=doQuery LANG=ADQL & must \\ +PQL queries & & & REQUEST=doQuery LANG=PQL & may \\ +other query languages & & & REQUEST=doQuery LANG= & may \\ +VOTable output & & & FORMAT & must \\ +other formats & & & FORMAT & should \\ +limiting output & & & MAXREC & must \\ +logging & & & RUNID & should \\ +\end{tabular} + +The resources and parameters are described in detail below. The description of +these resources and parameters spell out how the requirements here are to be +implemented. + +TAP service registration in the IVOA resource-registry is specified in section +3. + +\subsection{Resources} +A TAP service must be represented as a tree structure of web resources each +addressable via a URL in the http scheme, or the https scheme, or both. + +The web resource at the root of the tree must represent the service as a whole. +This specification defines no standard representation for this root resource. +Implementations may provide a representation, or may return a '404 not found' +response to requests for the root web-resource. One possible representation is +an HTML page describing the scientific usage and content of the service. TAP +clients must not depend on a specific representation of the root web-resource. + +\subsubsection{/sync} +A TAP service must provide a web resource with relative URL /sync that is a +direct child of the root web resource. This web resource represents the results +of synchronous requests. The exact form of the query, and hence the +representation of the resource, is defined by the query parameters as listed in +section 2.3. Representations of results of queries and VOSI outputs are defined +in sections 2.7.1 and 2.7.2 respectively. + +For query languages that produce a single result (e.g. ADQL) executed using the +/sync endpoint, the result of a successful query is returned in the response or +the response includes an HTTP redirect (303: See Other) to a resource (uri) from +which the result may be retrieved. + +An HTTP-GET request to the /sync web resource may return a cached copy of the +representation. This cached copy might come from an HTTP cache between the +client and the service, and the service may also maintain its own cache. Clients +which require an up-to-date representation of volatile data or metadata must use +HTTP POST. + +\subsubsection{/async} +A TAP service must provide a web resource with relative URL /async that is a +direct child of the root web resource. This web resource represents controls for +asynchronous queries. Specifically, the web resource must represent the job-list +as specified in the UWS standard [3]. + +The child web resources of the /async resource are as specified by UWS. These +are descendants of the /async web-resource, and they include a web resource that +represents the eventual result of an asynchronous query, e.g.: +\begin{verbatim} +http://example.com/tap/async/42/results/result +\end{verbatim} +where the base URL for the TAP service is: +\begin{verbatim} +http://example.com/tap +\end{verbatim} +the UWS job list is: +\begin{verbatim} +http://example.com/tap/async +\end{verbatim} +and the job resource is +\begin{verbatim} +http://example.com/tap/async/42 +\end{verbatim} +where 42 is the job identifier. A client making an asynchronous request must use +the UWS facilities to monitor or control the job. In addition to the job list +and job resource above, UWS specifies the name and semantics of the a small set +of child resources used to view and control the job, e.g.: +\begin{verbatim} +http://example.com/tap/async/42/phase +http://example.com/tap/async/42/quote +http://example.com/tap/async/42/executionduration +http://example.com/tap/async/42/destruction +http://example.com/tap/async/42/error +http://example.com/tap/async/42/parameters +http://example.com/tap/async/42/results +http://example.com/tap/async/42/owner +\end{verbatim} +Successful TAP queries produce results which must be accessible as resources +under the UWS result list, e.g.: +\begin{verbatim} +http://example.com/tap/async/42/results/ +\end{verbatim} +Failed TAP queries produce an error document (see 2.9 ) which must be accessible +as the error resource, e.g.: +\begin{verbatim} +http://example.com/tap/async/42/error +\end{verbatim} +For query languages that produce a single result executed using the /async +endpoint, the result of a successful query can be found within the result list +specified by UWS [3]; the result must be named result and thus clients are able +to access it directly, e.g.: +\begin{verbatim} +http://example.com/tap/async/42/results/result +\end{verbatim} +Access of this resource must deliver the result, either directly or as an HTTP +redirect (303: See Other) to a resource from which the result may be retrieved. + +For query languages that may produce multiple result resources, the names of the +results are not specified (they may be specified in the specification for the +language). The client can always access the result list resource as specified by +UWS [3]. + +If the query returned no rows, the result resource must exist and contain no +data rows. Details on interacting with these resources are specified in the UWS +standard; for examples specific to TAP see Section 5 below. + +\subsubsection{/availability} +The VOSI availability metadata should be accessible from a web resource with +relative URL /availability that is a direct child of the root web resource. If +implemented, the /availability resource must be accessible via the http GET +method. The content is described by [6]. + +Services which do not implement the /availability resource must respond with an +HTTP response code of 404 when this resource is accessed. + +\subsubsection{/capabilities} +The service capabilities must be accessible from a web resource with relative +URL /capabilities that is a direct child of the root web resource. The +/capabilities resource must be accessible via the http GET method. The content +is described by [8]. + +\subsubsection{/tables} +The table metadata should be accessible from a web resource with relative URL +/tables that is a direct child of the root web resource. The /tables resource +must be accessible via the http GET method. The content is described by [7] and +is equivalent to the metadata from the TAP\underline{' '}SCHEMA described in 2.6 +. + +Services which do not implement the /tables resource must respond with an HTTP +response code of 404 when this resource is accessed. + +\subsection{Parameters} +The /sync and /async web-resources must accept the parameters listed in the +following sub-sections. In a synchronous request, the parameters select the +representation returned in the response message. In an asynchronous request, the +parameters select the representation of the eventual query result rather than +the response to the initial request. + +Requirements on the presence and values of parameters described below are +enforced only when the TAP request is executed (not when individual HTTP +requests are handled). Thus, for asynchronous TAP queries, the parameter +requirements must be satisfied (and errors returned if not) only when the query +is run in (in the sense of UWS job execution). Specifically, asynchronous +queries may be created with with no parameters and multiple, subsequent HTTP +POST actions may specify the parameters in any order. + +Not all combinations of the parameters are meaningful. For example, if a request +carries LANG=ADQL then the SELECT parameter (from PQL) is spurious. If a +service receives a spurious parameter in an otherwise correct request, then the +service must ignore the spurious parameter, must respond to the request normally +and must not report errors concerning the spurious parameter. + +\subsubsection{REQUEST} +This parameter distinguishes current service operations, makes it possible to +extend the service specification (with additional or custom operations), and +specifies how other parameters should be interpreted. If a TAP service attempts +to execute a TAP request without this parameter or with an incorrect value for +this parameter, then the service must reject the request and return an error +document as the result. + +These are the standard values of the parameter: + +doQuery: execute a query + +getCapabilities: return VOSI-capabilities metadata + +All requests to execute (/async or /sync) a query using a query language must +include REQUEST=doQuery and must include the LANG parameter. For other values of +REQUEST, additional parameters may or may not be required. The +REQUEST=getCapabilities service operation must be supported for synchronous +(/sync) requests and is not defined for asynchronous (/async) requests. + +For synchronous queries, the HTTP request must also include additional +parameters (see below) with the details of the query. These are used for +metadata queries and data queries. + +For asynchronous queries, the additional parameters may be included with the +HTTP request that creates the query (the UWS job) or they may be POSTed directly +to the created job resource, in one or more separate HTTP requests. The +parameter names remain the same in both cases. + +\subsubsection{VERSION} +The VERSION parameter specifies the TAP protocol version number. The format of +the version number, and version negotiation, are described in section 2.9.2 . + +A TAP service must support the VERSION parameter. This specification is for TAP +1.0; the client would specify VERSION=1.0 if the request is made using the +protocol described here. + +\subsubsection{LANG} +The LANG parameter specifies the query language. The service must support LANG +and the client must provide a value with REQUEST=doQuery. The only standard +values for the LANG parameter are ADQL (a required language) and PQL (reserved +value for an optional language which is under development). Support for other +languages and the LANG value to use with them is described in the service +capabilities. + +For example, an ADQL query would be performed with +\begin{verbatim} +REQUEST=doQuery +LANG=ADQL +QUERY= +\end{verbatim} +A PQL query would be performed with +\begin{verbatim} +REQUEST=doQuery +LANG=PQL + +\end{verbatim} +The value of LANG is a string specifying the language and optionally the +language version used for the query parameter(s), as defined by the service +capabilities. The client may specify the version of the query language, e.g. +LANG=ADQL-2.0 (the syntax should be as shown) or it may omit the version, e.g. +LANG=ADQL. The service should return an “unknown query language” error as +described in 2.9 if an unsupported language or an incompatible language version +is specified. + +\subsubsection{QUERY} +The QUERY parameter is used to specify the ADQL query. It may also be used to +specify the query for other values of LANG (e.g. LANG=) which are not specified in this document but may be described in the +service capabilities. + +A service must support the QUERY parameter because ADQL is a required language. +The case sensitivity of the query string is defined solely by the query language +specification. In the case of ADQL 2.0, for example, the query is not case +sensitive except for character literals; schema, table, and column names, +function names, and other ADQL keywords are not case sensitive. + +Within the ADQL query, the service must support the use of timestamp values in +ISO8601 format, specifically yyyy-MM-dd['T'HH:mm:ss[.SSS]], where square +brackets denote optional parts and the 'T' denotes a single character separator +(T) between the date and time parts. + +If the tables that are queried through a service contain columns with spatial +coordinates and the service supports spatial querying via the ADQL “region” +constructs, the service must support the INTERSECTS function and it must support +the following geometry functions: REGION, POINT, BOX, CIRCLE, COORD1, COORD2, +COORDSYS. Support for the AREA, CONTAINS, and POLYGON functions are optional. If +the service supports the REGION function, it must support region encoding in +STC-S format (see section 6 ); the extent of STC-S support within the REGION +function is left up to the implementation. Coordinate system specification for +POINT, BOX, CIRCLE, and POLYGON must use values from STC-S as described in +section 6 . + +Note: Although it is allowed by the ADQL syntax, clients should be careful when +mixing constants and column references for coordinate system and coordinate +values. For example, POINT('ICRS', t.ra, t.dec) does not cause t.ra and t.dec to +be transformed to ICRS; it simply tells the service to treat the values as +being expressed in that coordinate system. + +\subsubsection{Parameters for PQL} +A number of parameters will be defined by the PQL standard for use in parametric +queries. All of the parameters for PQL are are used unchanged in TAP. + +Within the PQL query, the service must support the use of timestamp values in +ISO8601 format (see 2.3.4 ). + +If the table that is queried contains columns with spatial coordinates and the +service provider wants to enable the caller to perform spatial queries, the +service must support the PQL spatial constraint parameters (POS,SIZE and +REGION). If a service supports the REGION parameter, it must support region +encoding in STC-S as decribed in section 6 ; the extent of STC-S support within +the REGION function is left up to the implementation. Coordinate system +qualifiers must use values from from STC-S as described in section 6 . + +PQL defines symbolic values (@something). In TAP these can be used to refer to +an uploaded table (see 2.5 ) with parameters that support a table reference. +When used in this way, the uploaded table must be treated as if in the +TAP\underline{' '}UPLOAD schema (e.g. @TAP\underline{' '}UPLOAD.mytable). +Details on how to use table references in PQL will be described in the PQL +specification. + +\subsubsection{FORMAT} +The FORMAT parameter indicates the client's desired format for the table of +results of a query. Its value should be a MIME type for tabular data or one of +the following shorthand forms: + +TODO: add table here + +Both MIME types and the shorthand forms are insensitive to case. If the FORMAT +parameter is omitted, the default format is VOTable. + +A TAP service must support VOTable as an output format, should support CSV and +TSV output and may support other formats. A TAP service must accept a FORMAT +parameter indicating a format that the service supports and should reject +queries where the FORMAT parameter specifies a format not supported by the +service implementation. + +\subsubsection{MAXREC} +The service must accept a MAXREC parameter specifying the maximum number of +table records (rows) to be returned. If MAXREC is not specified in a query, the +service may apply a default value or may set no limit. If the result set for a +query exceeds this value, the service must only return the requested number of +rows. If the result set is truncated in this fashion, it must include an +overflow indicator as specified in section 2.7.4 . + +The service must support the special value of MAXREC=0. This value indicates +that, in the event of an otherwise valid request, a valid output table be +returned containing metadata, no table data rows, and an overflow indicator as +specified in section 2.7.4 . The service is not required to execute the query; +a successful MAXREC=0 request does not necessarily mean that the query is valid +and the overflow indicator does not necessarily mean that there is at least one +row satisfying the query. The service may perform validation and may try to +execute the query, in which case a MAXREC=0 request can fail. + +A query with MAXREC=0 can be used with a simple query (e.g. SELECT * FROM +some\underline{' '}table) to extract and examine the VOTable metadata (assuming +FORMAT=votable). Note: in this version of TAP, this is the only mechanism to +learn some of the detailed metadata, such as coordinate systems used. + +\subsubsection{RUNID} +The service should implement the RUNID parameter, used to tag service requests +with the job ID of a larger job of which the request may be part. The RUNID +parameter is defined in [3] for /async requests; services should also implement +it for /sync requests. + +For example, if a cross match portal issues multiple requests to remote TAP +services to carry out a cross-match operation, all would receive the same RUNID, +and the service logs could later be analyzed to reconstruct the service +operations initiated in response to the job. + +The service should ensure that RUNID is preserved in any service logs and +should pass on the RUNID value in any calls to other services. + +\subsubsection{UPLOAD} +The service should support table upload via the UPLOAD parameter. The value is a +list of table-name,URI pairs. Table names must be legal ADQL table names as +defined in [1]. URIs maybe be simple URLs (e.g. with a URI scheme of http) or +URIs (e.g. with a URI scheme of vos or param) that must be resolved to give the +location of the table content. See section 2.5 for details. + +\subsubsection{Case of Parameters} +NOTE: this is in DALI now + +\subsubsection{Order and Cardinality of Parameters} +NOTE: this is in DALI now + +\subsection{Table Names} +A fully qualified table name has the form +\begin{verbatim} +[[catalog_name”.”]schema_name”.”]table_name +\end{verbatim} +where catalog\underline{' '}name is the name of the DB catalogue (often the +“database” name) in SQL DBMS terminology, schema\underline{' '}name is the name +of the “schema” in DBMS terminology (often also called a “database”; a DBMS +schema is a type of data model where the top level data model elements are +tables), and table\underline{' '}name is the actual table name. All elements of +the table name are optional except table\underline{' '}name. Depending upon the +DBMS, “catalog” or “schema” may or may not be implemented; some DBMS implement +both, others one or the other, and the simplest database systems might not +implement either. + +The implementation of a TAP service must define the table names acceptable in +queries and must reveal these to clients through metadata queries or through +VOSI-tables output, and the names must be identical in each of these sources. A +TAP client must determine the acceptable names from one of these sources or from +the cached form of the VOSI-tables output included in the service's +registration. + +\subsection{Table Upload} +The service should implement the table upload capability. If upload is +supported, the service must accept tables in VOTable format. The client +specifies the name of the uploaded table; this name must be a legal ADQL table +name with no catalog or schema (e.g. an unqualified table name). Uploaded tables +must be referred to in queries as TAP\underline{' '}UPLOAD., where + is the specified by the user. + +Tables in the TAP\underline{' '}UPLOAD schema are transient and +persist only for the lifetime of the query (although caching might be used +behind the scenes) and are never visible in the TAP\underline{' '}SCHEMA +metadata. + +The column names in the transient database table are taken directly from the +name attribute of the VOTable FIELD and PARAM elements. The datatypes of the +transient table are determined from the FIELD and PARAM attributes as follows: + +TODO: table + +The default mapping of data types are shown above (no arraysize or xtype). If +the xtype attribute is set, this is the preferred internal datatype. If xtype is +not set, then the datatype and arraysize indicate the most suitable internal +datatype. + +In the arraysize column above, [1] means the arraysize is not set or is set to +1, n means arraysize is set to a specific value, * means arraysize=”*”, and n* +means arraysize=”n*” (variable size up to length n). A blank means the arraysize +is not set. + +Binary values (unsignedByte in VOTable, BINARY, VARBINARY, or BLOB in ADQL) can +be expressed as specified by the VOTable standard. By default, VOTable allows +them to be written as an array of decimal numbers, e.g. 12 56 0 255 0 0 255 (one +number per byte value). + +For columns of type BLOB or CLOB, most database systems support reference to +these columns in the select clause but not in any other part of the query. +Services may use these types to indicate that columns may only be selected. For +example, if service implementors want to make URL(s) available as column values +in the results, but do not actually store the URL(s) in the database, they would +specify a column with xtype=”adql:CLOB” and the column with URL(s) could be +referenced in the SELECT clause of a query, but could not be used in the WHERE +clause. The service could then process the query result and insert the URL(s) +or, more likely, transform a column value (an identifier) into a URL while +writing the results. + +TIMESTAMP values are specified using ISO8601 format without a timezone (as in +2.3.4 ) and are assumed to be in UTC. The xtype=”adql:TIMESTAMP” attribute must +be specified in an uploaded VOTable in order for the values to be inserted in a +column of type TIMESTAMP; without the xtype, the values would be inserted into a +CHAR(n) or VARCHAR column. + +POINT and REGION values are specified in STC-S format (see section 6 ). The +xtype=”adql:POINT” attribute must be specified in an uploaded VOTable in order +for the char values to be parsed and treated as POINTs (e.g. to be used with +some of the ADQL region functions). For regions, the xtype=”adql:REGION” +attribute must be specified in an uploaded VOTable in order for the char values +to be parsed and treated as REGIONs (e.g. to be used with some of the ADQL +region functions). + +\subsubsection{UPLOAD} +The UPLOAD parameter is used to reference read-only external tables via their +URI, to be uploaded for use as input tables to the query. The value of the +UPLOAD parameter is a list of table name-URI pairs. Elements of the list are +delimited by semicolon and the two parts of the pair are delimited by comma. For +example: +\begin{verbatim} +UPLOAD=table_a,http://host_a/path;table_b,http://host_b/path +\end{verbatim} + +would define two input tables table\underline{' '}a and +table\underline{' '}b, located at the given URIs. Services that implement +UPLOAD must support http as a URI scheme (e.g. must support treating an http URI +as a URL). A VOSpace URI (vos:) is a more generic example of a URI +that requires more service-side functionality; support for the vos scheme is +optional. + +\subsubsection{Inline Table Upload} +To upload a table inline, the caller must specify the UPLOAD parameter (as +above) using a special URI scheme “param”. This scheme indicates that the value +after the colon will be the name of the inline content. The content type used is +multipart/form-data, using a “file” type input element. The “name” attribute +must match that used in the UPLOAD parameter. + +For example, in the POST data we might have this parameter: +\begin{verbatim} +UPLOAD=table_c,param:table1 +\end{verbatim} +and this content: +\begin{verbatim} +Content-Type: multipart/form-data; boundary=AaB03 + +[...] + +--AaB03x + +Content-disposition: form-data; name="table1"; filename="table1.xml" + +Content-type: application/x-votable+xml + +[...] + +--AaB03x + +[...] +\end{verbatim} +The uploaded table would be referenced in queries as +TAP\underline{' '}UPLOAD.table\underline{' '}c (the table name in the UPLOAD +parameter). Services that implement table upload must support the param scheme +for inline uploads. + +In principle, any number of tables can be uploaded using the UPLOAD parameter +and any combination of URI schemes supported by the service as long as they are +assigned unique table names within the query. Services may limit the size and +number of uploaded tables; if the service refuses to accept the entire table it +must respond with an error as described in 2.7.3 . + +\subsection{Metadata and TAP SCHEMA} +There are several approaches to getting metadata for a given TAP service. All +TAP services must support a set of tables in a schema named +TAP\underline{' '}SCHEMA that describe the tables and columns included in the +service. In addition to the TAP\underline{' '}SCHEMA, there are two other ways +to get metadata from a TAP service. First, the VOSI tables resource provides +metadata on all tables and columns; this resource is described in 2.2.5 . The +VOSI tables resource provides the same metadata as the TAP\underline{' '}SCHEMA +but in a rigorously controlled format; the information in the +TAP\underline{' '}SCHEMA is equivalent to that defined by the VODataService +[7]. Second, the client may specify a query of one or more tables setting the +MAXREC parameter to 0 so that only the metadata regarding the requested fields +is returned. Use of MAXREC is described in 2.3.7 . + +The TAP\underline{' '}SCHEMA provides access to table, column, and join key +metadata through the TAP query mechanisms themselves. Users can discover tables +or columns that meet their specific criteria by querying the tables described +below. The service may enhance the TAP\underline{' '}SCHEMA with additional +metadata where that seems appropriate; since it is self-describing, the +TAP\underline{' '}SCHEMA may be queried to determine if any extended schema +metadata is defined by the service. Services must provide these tables and make +them accessible by all supported query mechanisms. + +The qualified names in the tables of the TAP schema must follow the rules +defined in section 2.4. The names must be stated in a form that is acceptable as +an operand of a query. + +All columns in the TAP\underline{' '}SCHEMA tables are of type VARCHAR except +for size, principal, indexed, and std (in Columns) which are INTEGER values. + +Implementors are permitted to include additional tables in the +TAP\underline{' '}SCHEMA to describe additional aspects of their service not +covered by this specification. Implementors may also include additional columns +in the standard tables described below. For example, one could include a column +with a timestamp saying when metadata values were was last modified. + +\subsubsection{Schemas} +The table TAP\underline{' '}SCHEMA.schemas must contain the following columns: + +TODO: table + +The schema\underline{' '}name values must be unique and may be qualified by the +catalog name or not depending on the implementation requirements. The fully +qualified schema name is defined by the ADQL language and follows the pattern +[catalog.]schema. The schema metadata are included for reference and are not +used directly to construct queries. + +\subsubsection{Tables} +The table TAP\underline{' '}SCHEMA.tables must contain the following columns: + +TODO: table + +The table\underline{' '}name values must be unique. The value of the +table\underline{' '}name should be the string that is recommended for use in +querying the table; it may or may not be qualified by schema and catalog name(s) +depending on the implementation requirements. The fully qualified table name is +defined by the ADQL language and follows the pattern [[catalog.]schema.]table. + +\subsubsection{Columns} +The table TAP\underline{' '}SCHEMA.columns must contain the following columns: + +TODO: table + +The table\underline{' '}name,column\underline{' '}name (pair) values must be +unique. + +Data types and how they map to VOTable datatypes are described in section 2.5 +above. The “size” gives the length of variable length datatypes, for example +varchar(256); this size does not map to the VOTable arraysize attribute when the +latter specifies the size and shape of a multi-dimensional array. The +“principal” flag indicates that the column is considered a core part the +content; clients can use this hint to make the principal column(s) visible, for +example by selecting them by default in generating an ADQL query. In cases where +the services selects the columns to return (such as PQL without a SELECT +parameter), the principal column indicates those columns that are returned by +default. The “indexed” flag indicates that the column is indexed, potentially +making queries run much faster if this column is used in a constraint. The “std” +is included for compatibility with the registry, which uses this value to +indicate that a given column is defined by some standard, as opposed to a custom +column defined by a particular service. + +\subsubsection{Foreign Keys} +The table TAP\underline{' '}SCHEMA.keys must contain the following columns to +describe foreign key relations between tables: + +TODO: table + +The key\underline{' '}id values are unique and used only to join with the +TAP\underline{' '}SCHEMA.key\underline{' '}columns table below. There may be +one or more rows with different key\underline{' '}id values and a pair +of tables to denote one or more ways to join the tables. + +The table TAP\underline{' '}SCHEMA.key\underline{' '}columns must contain the +following columns to describe the columns that make up a foreign key: + +TODO: table + +There may be one or more rows with a specific key\underline{' '}id to +denote single or multi-column keys. + +A TAP service must provide the tables listed above and may provide other tables +in the TAP\underline{' '}SCHEMA namespace. + +\subsection{Access to and Representation of Results} +\subsubsection{Data and Metadata Queries} +The result of a data query or a metadata query depends on the query language +used and may be one or more tables in one or more resources. Unsupportable +combinations of query result and FORMAT (e.g. queries that produce multiple +tables and an inherently single-table format like CSV) will cause the request to +fail. Currently, an ADQL query result must be a single table (in a single file). + +This table must be encoded in the output format specified by the FORMAT +parameter of the query. See section 2.3.6 for required, optional and default +formats. VOTable is the default format and VOTable support is mandatory. + +The output table must include the same number and order of columns as specified +in the SELECT clause of the query. For VOTable output, the name attribute of +FIELD elements must be the same as the column names (or aliases if specified in +the query) from the query and the datatype, arraysize, and xtype attributes of +FIELD elements must be set using the mapping specified in section 2.5 . The +xtype attribute in the output must match the datatype for the column in the +TAP\underline{' '}SCHEMA. + +VOTable structure follows the rules in section 2.9 and must be returned with an +allowed VOTable MIME type (application/x-votable+xml or text/xml). If the FORMAT +parameter (see 2.3.6 ) of the request specified a specific VOTable MIME type, +the requested MIME type must be used in the HTTP response. + +CSV formatted data should represent the output table with one row of text per +table row, with the table column values rendered as text and separated by +commas. If a column value contains a comma the entire column value should be +enclosed in double quotes. Text lines may be arbitrarily long. The first data +row should give the column name as the data value. CSV data must be returned +with a MIME type of text/csv; if the optional header line (with column names) is +included, the MIME type must be text/csv;header=present. Full details of CSV +format are defined in RFC 4180 [14]. + +TSV formatted data should represent the output table with one row of text per +table row, with the table column values rendered as text and separated by the +TAB character. TSV data must be returned with a MIME type of +text/tab-separated-values [15]. Column values may not contain the TAB +character. + +\subsubsection{VOSI} +Representations of VOSI outputs (capabilities, availability, table metadata) +must be as defined in the VOSI standard [6]. + +The representation of table metadata must include all tables in the service's +tableset. VOSI's representation of table metadata is specified in VODataService +[7]. + +The VOSI standard specifies that the capability metadata is encoded as an XML +document which lists each of the service's capabilities as a +element. The type of this element (which defines the contents) is +{http://www.ivoa.net/xml/VOResource/v1.0}Capability from the VOResource XML +standard [8]. + +In addition, the capabilities output must also comply with the following +requirements: + + •.the returned document must include one element that describes +the service's support for the TAP protocol + + •.this element must have its "standardID" attribute set to +"ivo://ivoa.net/std/TAP" + + •.this capability element must include at least one "" element +with its "role" attribute set to "std", + + •.this "" element must contain a child "" element with +the attribute "use" set to "base" which contains the root web resource for the +service as defined in section 2.2 . + +Note: VO registries recognize a service's support for a standard protocol +through this capability description. In particular, a different standard +Capability sub-type is used for each standard protocol to provide capability +metadata that is specific to that protocol. At the time of this writing, a +Capability sub-type for TAP has not yet been defined. Thus for compliance with +this standard, any legal Capability description that meets the above +restrictions is sufficient. However, once a VOResource extension for TAP is +standardized, it is strongly recommended that TAP services emit its capabilities +using that the Capability sub-type specialized for TAP. + +For example, the returned capabilities document for a service supporting TAP +might look as follows: + +\begin{verbatim} + + + + + + + + + http://myarchive.net/myTAP + + + + + + + + + + + + http://myarchive.net/myTAP/capabilities + + + + + + + + + + + + http://myarchive.net/myTAP/availability + + + + + + + + + + + + + + http://myarchive.net/myTAP/tables + + + + + + +\end{verbatim} + +\subsubsection{Errors} +If the service detects an exceptional condition, it must return an error +document with an appropriate HTTP-status code. TAP distinguishes three classes +of exceptions. + +Errors in the use of the HTTP protocol. + +Errors in the use of the TAP protocol, including both invalid requests and +failure of the service to complete valid requests. + +Error documents for HTTP-level errors are not specified in the TAP protocol. +Responses to these errors are typically generated by service containers and +cannot be controlled by TAP implementations. There are several cases where a TAP +service could return an HTTP error. First, the /async endpoint could return a +404 (not found) error if the client accesses a job within the UWS joblist that +does not exist. Second, access to a resource could result in an HTTP 401 (not +authorized) error if authentication is required or an HTTP 403 (forbidden) error +if the client is not allowed to access the resource. + +Error documents for TAP errors must be VOTable documents; any result-format +specified in the request is ignored. If the error document is being retrieved +from the /async//error resource (specified by UWS) after an asynchronous +query, the HTTP status code should be 200. If the error document is being +returned directly after a synchronous query, the service may use an appropriate +HTTP status code, including 200 (successfully returning a response to the +request) and various 4xx and 5xx values. The exception condition must be +described to the client using a status code in the VOTable header. Section +2.9 specifies the use of VOTable for error documents in TAP services. + +\subsubsection{Overflows} +If a query is executed by a TAP service, the number of rows in the table of +results may exceed a limit requested by the user (using the MAXREC parameter) or +a limit set by the service implementation (the default or maximum value of +MAXREC). In these cases, the query is said to have 'overflowed'. Typically, a +TAP service will not detect an overflow until some part of the table of results +has been sent to the client. + +If an overflow occurs, the TAP service must produce a table of results that is +valid, in the required output format, and which contains all the results up to +the point of overflow. Since an output overflow is not an error condition, the +MIME type of the output must be the same as for any successful query and the +HTTP status-code must be as for a successful, complete query. + +If the output format is VOTable, section 2.9.1 describes the method by which the +overflow is reported. No method of reporting an overflow is defined for formats +other than VOTable. + +\subsection{Versioning of the TAP Protocol} +The TAP protocol provides explicitly for versioning of the interface in order to +support version negotiation between a client and a service where one or both +parties support more than one version of the protocol. The TAP version refers +only to the TAP protocol; query languages are versioned separately and TAP and +ADQL versions may differ. + +Version numbers follow IVOA document conventions [17]. + +\subsubsection{Appearance in requests and in service metadata} +The version number may appear in at least three places: in the service metadata, +as a parameter in client requests to a server, and in the query response. The +version number used in a client’s request of a particular server must be equal +to a version number which that server has declared it supports (except during +negotiation, as described below). A server may support several versions, whose +values clients may discover according to the negotiation rules. + +\subsubsection{Version number negotiation} +If a TAP client does not specify the version number in a request, the server +assumes the highest standard version supported by the service, and no explicit +version checking takes place. If the client specifies an explicit version +number, and this does not match a version available from the service, the +service returns a version number mismatch error as described in 2.9.2 . The +client can determine what versions of the protocol the service supports by a +prior call to VOSI-capabilities or via a registry query. + +\subsection{Use of VOTable} +VOTable is a general format. TAP requires that it be used in a particular way. + +The result VOTable document must comply with VOTable v1.2 or greater [9]. For +columns containing coordinate values, the coordinate system metadata should be +provided as described in [13]. + +The VOTable must contain a RESOURCE element identified with the attribute +type="results", containing a single TABLE element with the results of the query. +Additional RESOURCE elements may be present, but the usage of any such elements +is not defined here and TAP clients should not depend upon them. + +\subsubsection{INFO elements} +The RESOURCE element must contain, before the TABLE element, an INFO element +with attribute name = "QUERY\underline{' '}STATUS". The value attribute must +contain one of the following values: + +“OK”, meaning that the query executed successfully and a result table is +included in the resource + +"ERROR”, meaning that an error was detected at the level of the TAP +protocol or the query failed to execute + +The content of the INFO element conveying the status should be a message +suitable for display to the user describing the status. + +\begin{verbatim} + +\end{verbatim} + +\begin{verbatim} +Successful query +\end{verbatim} + +\begin{verbatim} + + value out of range in POS=45,91 + +\end{verbatim} + +Additional INFO elements may be provided, e.g., to echo the input parameters +back to the client in the query response (a useful feature for debugging or to +self-document the query response), but clients should not depend on these. + +\begin{verbatim} + + + unrecognized operation + + + + + + +\end{verbatim} + +If an overflow occurs (result exceeds MAXREC), the service must close the table +and append another INFO element to the RESOURCE (after the TABLE) with +name=”QUERY\underline{' '}STATUS” and the value=”OVERFLOW”. +\begin{verbatim} + + +... +...
+ + +\end{verbatim} + +In the above example, the TABLE should have exactly MAXREC rows. + +If an error occurs while writing the rows of the VOTable, the service must close +the table and append another INFO element to the RESOURCE, after the TABLE, with +name=”QUERY\underline{' '}STATUS” and the value=”ERROR”. +\begin{verbatim} + + +... +...
+ + +\end{verbatim} +The content of these trailing INFO elements is optional and intended for users; +client software should not depend on it. + +Thus, one INFO element with name=”QUERY\underline{' '}STATUS” and value=”OK” or +value=”ERROR” must be included before the TABLE. If the TABLE does not contain +the entire query result, one INFO element with value=”OVERFLOW” or value=”ERROR” + must be included after the table. +2.9.2 Version Mismatch Errors + +Errors due to version mismatch from either the VERSION parameter (TAP version) +or specific version used in the LANG parameter (query language version) are +specified using an INFO element with name=”QUERY\underline{' '}STATUS” and +value=”ERROR” as described above. + +\section{Service Registration} +Publication of a service to the VO requires that it be registered with an IVOA +registry, including describing the identity and capabilities of the service. + +The resource document for a TAP service instance must be structured according to +VOResource [8] using the sub-type CatalogService as defined in VODataService +[7]. + +The resource document must include a capability element denoting the TAP +interface and functions. This element must contain the URL for the root web +resource (as defined in section 2.2 ). Clients would add to this URL /sync or +/async as appropriate. + +The resource document must contain capability elements for the +VOSI-capabilities, VOSI-availability and VOSI-tables outputs. These must be +formatted as in the VOSI standard [6]. + +The resource document should include the table metadata, except where the +database-schema of the archive changes frequently. Where table metadata are +provided, they must be represented as XML elements drawn from VODataService +[7]. + +\section{Extended Capabilities} +The TAP service allows for optional extended capabilities and operations. +Extensions may be defined within an information community when needed for +additional functionality or specialization. A generic client must not be +required or expected to make use of such extensions. Extended capabilities or +operations must be defined by the service metadata. Extended capabilities +provide additional metadata about the service, and may or may not enable +optional new parameters to be included in operation requests. Extended +operations may allow additional operations to be defined. + +A server must produce a valid response to the operations defined in this +document, even if parameters used by extended capabilities are missing or +malformed (i.e. the server must supply a default value for any extended +capabilities it defines), or if parameters are supplied that are not known to +the server. + +Service providers must choose extension names with care to avoid conflicting +with standard metadata fields, parameters and operations. + +\section{Use of UWS} +The UWS pattern is specified in [3] and its application to TAP in section +2.2.2. This section explains the exchange of messages between a TAP client and +service when using UWS to run an asynchronous query. + +Consider a TAP service at http://example.com/tap. TAP mandates that the +asynchronous requests be directed to http://example.com/tap/async. This URL +points to the list of 'jobs'; i.e. the list of queries currently or recently +executed. + +\subsection{Creating a Query} +To create a new query, the client POSTs a request to the job list: + +\begin{verbatim} +HTTP POST http://example.com/tap/async +REQUEST=doQuery +LANG=ADQL +QUERY=SELECT TOP 100 * FROM foo +\end{verbatim} + +The service then creates a job and assigns that job a name and a URL based on +the name. Suppose that the name is 42, then the URL will be +http://example.com/tap/async/42 because the jobs are always children of the job +list. While the job is in the PENDING phase, additional parameters may be +specified by additional POSTs to the job resource, for example: + +\begin{verbatim} +HTTP POST http://example.com/tap/async/42 +UPLOAD=mytable,http://a.b.c/mytable.xml +\end{verbatim} + +After each such POST, the service issues an HTTP redirection to the job's URL, +where the modified state may be accessed: + +\begin{verbatim} +HTTP status 303 'See other' +Location: http://example.com/tap/async/42 +\end{verbatim} + +All TAP-specific parameters are stored using the paramList mechanism of UWS and +are included in the XML representation of the job: +\begin{verbatim} +HTTP GET http://example.com/tap/async/42 +\end{verbatim} +or directly from the parameters resource: +\begin{verbatim} +HTTP GET http://example.com/tap /async/42/parameters +\end{verbatim} +Individual parameters cannot be accessed as separate web resources. + +The UWS pattern requires the following resources to describe and control the +job: +\begin{verbatim} +http://example.com/tap/async/42/phase +http://example.com/tap/async/42/quote +http://example.com/tap/async/42/executionduration +http://example.com/tap/async/42/destruction +http://example.com/tap/async/42/results +http://example.com/tap/async/42/error +\end{verbatim} +The quote resource specifies the predicted completion time for the job (query), +assuming it is started immediately. In practice, it is very hard to estimate the +time a query will take; for TAP services it is recommended that this be set to +the current time plus the maximum amount of time the query will be allowed to +run (see termination below). + +The termination resource specifies the amount of time (in seconds) the job +(query) will be allowed to run before being aborted by the service. The +termination time is set by the service and can be read from the job or directly +from the termination resource: + +\begin{verbatim} +HTTP GET http://example.com/tap/async/42/executionduration +\end{verbatim} +The service may allow the client to change the termination: +\begin{verbatim} +HTTP POST http://example.com/tap/async/42/executionduration +TERMINATION=600 +\end{verbatim} +The destruction resource specifies when the service will destroy the job. The +service is only required to keep a job for a finite period of time, after which +it may destroy the job, including the result. After this time, the client will +receive an HTTP 404 'not found' status if it tries to get any information about +the job. The destruction time of the job is chosen by the service and the client +can read it from the job or directly from the destruction resource: +\begin{verbatim} +HTTP GET http://example.com/tap/async/42/destruction +\end{verbatim} +The service may allow the client to change the destruction time: +\begin{verbatim} +HTTP POST http://example.com/tap/async/42/destruction +DESTRUCTION=2008-11-11T11:11:11Z +\end{verbatim} + +\subsection{Running a Query} +The phase URL shows the progress of the job. When the job is created by the +service it will normally be set to PENDING, but might be set to ERROR if the +service has rejected the job. If the phase is ERROR, then the error URL should +lead to a an error document explaining the problem. If the phase is PENDING, +then the client needs to commit the job for execution. + +The client runs the job by posting to the phase URL: +\begin{verbatim} +HTTP POST http://example.com/tap /async/42/phase +PHASE=RUN +\end{verbatim} + +The service replies with a redirection to the job URL +\begin{verbatim} +HTTP status 303 'see other' +Location: http://example.com/tap /async/42 +\end{verbatim} +The phase will now have changed to either QUEUED or EXECUTING, depending on the +service implementation. The client tracks the execution by polling the phase +URL: +\begin{verbatim} +HTTP GET http://example.com/tap/async/42/phase +\end{verbatim} +A job in the QUEUED or EXECUTING phase may be aborted by posting to the phase +URL: +\begin{verbatim} +HTTP POST http://example.com/tap/async/42/phase +PHASE=ABORT +\end{verbatim} + +When the query is complete, the phase changes to COMPLETED. The client then +retrieves the result from the results list: +\begin{verbatim} +HTTP GET http://example.com/tap/async/42/results/result +\end{verbatim} +The client knows that the table of results is at the URL /result relative to the +results list because the TAP protocol requires this naming. A generic UWS client +could find the name of the result and retrieve it by examining either the job +description: +\begin{verbatim} +HTTP GET http://example.com/tap/async/42 +\end{verbatim} +or by looking specifically at the result list: +\begin{verbatim} +HTTP GET http://example.com/tap/async/42/results +\end{verbatim} +If the service cannot run the query, then the final phase is ERROR and there is +no table of results. In this case, the client should expect an HTTP 404 'not +found' status if it tries to retrieve the result. The client should look instead +at the error resource to find out what went wrong: +\begin{verbatim} +HTTP GET http://example.com/tap/async/42/error +\end{verbatim} +If the job was aborted (by the client or the service), the final phase will be +ABORTED and there is no table or results. As with errors, the client should look +at the error resource to find out what went wrong. + +The basic sequence can be executed from a web browser or from a shell script +using the curl utility: +\begin{verbatim} +curl -d 'REQUEST=doQuery&LANG=PQL&POS=12,34&SIZE=0.5&FROM=foo' \ + http://example.com/tap/async + + [read Location header from curl output] + +curl -d 'PHASE=RUN' http://example.com/tap/async/42 + +curl http://example.com/tap/async/42/phase + + [repeat until phase is COMPLETED] + +curl http://example.com/tap/42/results/result +\end{verbatim} + +\section{Use of STC-S in TAP} + +NOT: not included from TAP-1.0 since it was informative and does not belong in +this docuemnt. + +\section{VOSpace Integration} +This version of TAP provides limited VOSpace integration, although better +support for VOSpace is planned for a later version following further +implementation experience. In this version, one may specify an upload table +using a URI to a table stored in a VOSpace, e.g.: +\begin{verbatim} +HTTP POST http://example.com/tap/async/42 +UPLOAD=mytable,vos://space/path/votable.xml +\end{verbatim} +The service would resolve the URI, contact the VOSpace, retrieve the table, and +make it visible to the query as TAP\underline{' '}UPLOAD.mytable. + +A future version of TAP may specify additional use and more integration with +VOSpace. + +\section{Use of HTTP} +Note: This section is in or belongs in DALI. + +\appendix + +\section{Changes from Previous Versions} + +\subsection{Changes from TAP-1.0} + + +\bibliography{ivoatex/ivoabib} + + +\end{document} diff --git a/archdiag.png b/archdiag.png new file mode 100644 index 0000000000000000000000000000000000000000..fc067816a322f5c8561a4af2a31779721d7e726f GIT binary patch literal 60491 zcmX`S2Q-}D^FOW=y^Fqj@2nQRMvWepNLc+L5haN(gdkWo5xo;7ELlNF(H7C`S|WN~ zMDKp<{rP|Y&pCVc?6ddIojWsk?!7awiF;t8M?uO$ii3kgabI8C90!L0g@c1%LV}Nd zQ;nh3#(w>HU}UL-gNs9t02bYzVMUtL}mBpkG2iFznT1-Oh3I|6< z<|B^U_I(2bO$+{T0|i;LB^>DfBl~zZpRZX%irQ*gSUg>`Zr!|IU0GOOKD_+b`S<4L`g-&F=CV>r z{~LBLxK4(8+Bk0s+4ZqM?mW}C^~1p-qr3g!;(W}xi+xG#f8SV#_zx*P2`!%y^1KBH z2ZVE9Tf_3@%yurBU$*{aU7X%e4hs(c u;feBoF1|otC@I`oEh|I{%jSXjLX=`(U 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 Date: Wed, 22 Apr 2015 16:09:54 +0000 Subject: [PATCH 03/68] first set of changes for WD-TAP-1.1: document re-org and TAPNotes issues discussed at Banff interop --- TAP.tex | 1406 +++++++++++++++++++++++++------------------------------ 1 file changed, 629 insertions(+), 777 deletions(-) diff --git a/TAP.tex b/TAP.tex index df54302..a282814 100644 --- a/TAP.tex +++ b/TAP.tex @@ -23,13 +23,12 @@ Access is provided for both database and table metadata as well as for actual table data. This version of the protocol includes support for multiple query languages, including queries specified using the Astronomical Data Query -Language (ADQL [1]) and the Parameterised Query Language (PQL, under -development) within an integrated interface. It also includes support for both -synchronous and asynchronous queries. Special support is provided for spatially -indexed queries using the spatial extensions in ADQL. A multi-position query -capability permits queries against an arbitrarily large list of astronomical -targets, providing a simple spatial cross-matching capability. More -sophisticated distributed cross-matching capabilities are possible by +Language (ADQL [1]) within an integrated interface. It also includes support +for both synchronous and asynchronous queries. Special support is provided for +spatially indexed queries using the spatial extensions in ADQL. A multi-position +query capability permits queries against an arbitrarily large list of +astronomical targets, providing a simple spatial cross-matching capability. +More sophisticated distributed cross-matching capabilities are possible by orchestrating a distributed query across multiple TAP services. \end{abstract} @@ -63,8 +62,8 @@ \section{Introduction} return the query response as another table, in accord with the relational model. Queries may be submitted using various query languages and may execute synchronously or asynchronously. Support for the Astronomical Data Query -Language (ADQL, [1]) is mandatory; support for other query languages such as -Parameterised Query Language (PQL, under development) or native SQL is optional. +Language (ADQL, [1]) is mandatory; support for other query languages is allowed +and optional. The result of a TAP query is another table, normally returned as a VOTable. Support for VOTable output is mandatory; all other formats are optional. @@ -80,96 +79,99 @@ \section{Introduction} cross match are also possible, but require combining the results of multiple TAP services. -\subsection{Query Types} -TAP services support three kinds of queries: data queries, metadata queries, and -Virtual Observatory Support Interface (VOSI [6]) queries. - -\subsubsection{Data Queries} -Data queries apply to the astronomical content served by a TAP service. This is -the reason for providing a TAP service. All the other kinds of query support the -ability to make data queries. Data queries may be specified in any query -language supported by the service. - -\subsubsection{Metadata Queries} -Metadata queries work like data queries, using the same query languages, but -they are applied to standardized tables that are a subset of, and patterned -after, information schema in RDBMS; the content of these tables explains the -data model of a particular TAP service. Metadata queries allow a client to -discover the names of tables and columns to be used in data queries. - -\subsubsection{VOSI} -Metadata queries work like data queries, using the same query languages, but -they are applied to standardized tables that are a subset of, and patterned -after, information schema in RDBMS; the content of these tables explains the -data model of a particular TAP service. Metadata queries allow a client to -discover the names of tables and columns to be used in data queries. - -\subsection{Query Languages} -TAP supports the use of multiple query languages, some of which are described -here. +\subsection{Role within the VO Architecture} + +NOTE: not in TAP-1.0 + +\begin{figure} +\centering + +% Get the architecture diagram from the TCG chair +% http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG +% If they give you a PDF, for now dumb it down to a png by +% convert -antialias -density 72x72 archdiag.pdf archdiag.png +% Oh -- Notes don't need this; you'd have to remove archdiag.png +% from FIGURES in the Makefile, too. + +\includegraphics[width=0.9\textwidth]{archdiag.png} +\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}. + + +\subsection{Motivating Use Cases} +Below are some of the more common use cases that have motivated the development +of the TAP specification. While this is not complete, it helps to understand the +problem area covered by this specification. + +\subsubsection{Discover Metadata} +Since content in relational databases is often custom and project-specific, +users of a TAP service must be able to discover the names of tables and +columns, datatypes, units, and other information necessary to construct +meaningful correct queries. + +\subsubsection{Query Custom Tables} +A large amount of astronomical data and metadata is stored in tables in +relational databases. Historically, users could query these tables through +custom user interfaces (usually web page forms), but such approaches could not +provide support for truly ad-hoc querying. A TAP service should enable users to +discover and query custom tables with a flexible and expressive input that +supports ad-hoc querying: selecting output, filtering the result, joining +multiple tables, computing aggregate quantities, etc. + +\subsubsection{Query Standard Tables} +A TAP service should enable users to query externally defined standard tables +in a uniform way such that the same web service request can be sent to multiple +services. Services must be able to declare their support for standard tables in +the service metadata. + +\subsubsection{Query Standard Data Models} +A TAP service should enable users to query (parts of) externally defined data +models that are (partially or fully) implemented by the service. Services must +be able to declare their support for data models as well as the way that model +elements are mapped to tables and columns. \subsubsection{ADQL Queries} -Support for ADQL queries is mandatory. ADQL can be used to specify queries that -access one or more tables provided by the TAP service, including the standard -metadata tables. In general, the client must access table metadata in order to -discover the names of tables and columns and then formulate queries. ADQL -queries provide a direct (low-level) access to the tables; a query will be -written for a specific TAP service and will not be usable with other services -unless the query refers only to common tables and columns. It is also possible -that the service registration (in an IVOA Registry) may include sufficient -table metadata to enable queries to be written directly. - -Details of the ADQL language may be found in [1]. - -\subsubsection{PQL} -Support for PQL is optional. PQL can be used to formulate queries that access a -single table provided by the TAP service, including the standard set of metadata -tables. PQL can also be used in some cases without first querying the metadata -tables by using the PQL parameters which carry sufficient meaning to enable the -service to decide which tables and columns to use (e.g. POS, SIZE, REGION, BAND, -TIME). - -Details of the PQL language (parameters) are not part of the TAP specification. +The Astronomical Data Query Language (ADQL) [std:ADQL] is the standard +query language for the IVOA. Support for ADQL queries is mandatory. ADQL can be +used to specify queries that access one or more tables provided by the TAP +service, including the standard metadata tables. In general, the client must +access table metadata in order to discover the names of tables and columns and +then formulate queries. ADQL queries provide a direct (low-level) access to the +tables; a query will be written for a specific TAP service and will not be +usable with other services unless the query refers only to common tables and +columns. It is also possible that the service registration (in an IVOA Registry) +may include sufficient table metadata to enable queries to be written directly. \subsubsection{Other Query Languages} -A TAP service may also support use of other query languages, including -pass-through of native SQL directly to an underlying DBMS, by describing such -capabilities in the service metadata and allowing custom values of the service -parameters. This mechanism allows future developments within the VOQL Working -Group and outside the IVOA to be used without revising the TAP specification. - -\subsection{Query Execution} -The TAP service specification defines both synchronous and asynchronous query -execution. Users select synchronous or asynchronous execution by chosing the -appropriate resource below the base URL for the service (see 2.2 ). A query is -synchronous if the results of the query are delivered in the HTTP response to -the request that originally posed the query. If the service returns an immediate -HTTP-response upon accepting a query and the client later obtains the results of -the query in response to a separate HTTP request, then we say the request is -asynchronous. +A TAP service must be able to support use of other query languages, such +pass-through of native SQL directly to an underlying DBMS or simple key-vale +(parameter-based) constraints. The service interface must allow for +this and the service capabilities must be able to describe it. This mechanism +also allows future developments within and outside the IVOA to be used without +revising the TAP specification. \subsubsection{Asynchronous Queries} -Asynchronous query support is mandatory. Asynchronous queries require that -client and server share knowledge of the state of the query during its execution -and between HTTP exchanges. They are an example of stateful interactions. In -TAP, the mechanism by which the clients and services share the state of -transactions is based on the Universal Worker Service (UWS) pattern [3]. +Asynchronous queries allow for long running queries to complete without +the client maintaining a connection to the service. Results are stored by +the service for later retrieval by the client. Asynchronous query +execution is generally more robust and not susceptible to time-outs or other +transient failures. They are especially suited to queries that run for a long +time before producing output (e.g. queries that compute or aggregate values). \subsubsection{Synchronous Queries} -Synchronous query support is mandatory. Synchronous queries execute immediately -and the client must wait for the query to finish. If the HTTP request times out -or the client otherwise loses the connection to the service before receiving the -response, then the query fails. - -Synchronous query execution is adequate when the query will execute quickly and -with a small number of results, or when they can at least start returning -results quickly. They are generally simple to implement using standard web -technologies and easy to use from a browser or scripting environment. However, -synchronous requests are generally not sufficient and are likely to fail for -queries that take a long time to execute, especially before returning any -results. - -\subsection{Interface Overview} +Synchronous queries execute immediately and the client must wait for the query +to finish. Synchronous query execution is generally simpler and provides a +faster (low latency) response and should be adequate when the query will execute +and start returning results quickly. Even with large query results, synchronous +queries are a good approach as long as the service can stream the output +and consume modest internal resources. + + +\subsection{Interface Overview -- move to examples section?} Table Access Protocol (TAP) is implemented over the HTTP protocol using standard HTTP GET and POST requests and conventions. A TAP request specifies one or more parameter key/value pairs; both keys and values are strings. The keys used are @@ -187,8 +189,6 @@ \subsection{Interface Overview} QUERY=SELECT * FROM magnitudes as m where m.r>=10 and m.r<=16 \end{verbatim} -NOTE: equivalent PQL that was in TAP-1.0 doc removed - Synchronous queries return the table of results in the HTTP response to the initial request. In the examples above, the output format defaults to VOTable; the FORMAT parameter could be added to select a different format. @@ -203,10 +203,9 @@ \subsection{Interface Overview} QUERY=SELECT * FROM magnitudes AS m WHERE m.r>=10 AND m.r<=16 \end{verbatim} -NOTE: equivalent PQL that was in TAP-1.0 doc removed - -The service's response to these requests is a URL representing the query's state -and progress and where the state may be monitored and controlled. The query +The service's response to these requests is a URL representing the query's +state and progress and where the state may be monitored and controlled. The +query result or an error document can then be retrieved from a URL associated with the job. This is an application of the UWS pattern. The query is then executed with a separate request to run the job URL: @@ -216,6 +215,20 @@ \subsection{Interface Overview} PHASE=RUN \end{verbatim} +The state of the job can be retrieved from the phase resource: + +\begin{verbatim} +HTTP GET http://example.com/tap/async//phase +\end{verbatim} + +The client may have to check the phase multiple times until the job +finishes. Once the returned value is COMPLETED, the results can be obtained +from the results resource: + +\begin{verbatim} +HTTP GET http://example.com/tap/async//results/result +\end{verbatim} + In addition to the sync and async resources for query execution, a TAP service also has metadata resources defined by the VOSI standard. The availability of a service can be monitored by accessing: @@ -224,16 +237,12 @@ \subsection{Interface Overview} HTTP GET http://example.com/tap/availability \end{verbatim} -See 2.2.3 for details of the availability resource. - The complete table metadata can be obtained: \begin{verbatim} HTTP GET http://example.com/tap/tables \end{verbatim} -See 2.2.5 for details of the table metadata resource. - The capabilities can be obtained by: \begin{verbatim} @@ -248,68 +257,33 @@ \subsection{Interface Overview} \end{verbatim} This output lists support for optional TAP functionality and additional -implemented interfaces. See 2.2.4 for details. - - -\subsection{Role within the VO Architecture} - -NOTE: not in TAP-1.0 - -\begin{figure} -\centering - -% Get the architecture diagram from the TCG chair -% http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG -% If they give you a PDF, for now dumb it down to a png by -% convert -antialias -density 72x72 archdiag.pdf archdiag.png -% Oh -- Notes don't need this; you'd have to remove archdiag.png -% from FIGURES in the Makefile, too. - -\includegraphics[width=0.9\textwidth]{archdiag.png} -\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{Requirements for a TAP Service} - -NOTE: pre-amble about must, should, and may that was here in 1.0 removed since -it is alteady included above +implemented interfaces. -The TAP standard is identified using standardID="ivo://ivoa.net/std/TAP". This -document specified version 1.0 of the standard. +\section{Resources} -\subsection{Feature Overview} -An implementation of a TAP service provides features as follows. +An implementation of a TAP service provides the following RESTful resources +under the base URL. \begin{tabular}{l l l l l} -synchronous query execution & /sync & must & & \\ -asynchronous query execution & /async & must & & \\ -VOSI-availability & /availability & should & & \\ -VOSI-capabilities & /capabilities & must & & \\ -VOSI-tables & /tables & should & REQUEST=getCapabilities & must \\ -ADQL queries & & & REQUEST=doQuery LANG=ADQL & must \\ -PQL queries & & & REQUEST=doQuery LANG=PQL & may \\ -other query languages & & & REQUEST=doQuery LANG= & may \\ -VOTable output & & & FORMAT & must \\ -other formats & & & FORMAT & should \\ -limiting output & & & MAXREC & must \\ -logging & & & RUNID & should \\ +resource type & resource name & required \\ +{sync} & /sync & must (anonymous) & \\ +{async} & /async & must (anonymous) & \\ +{sync} & service specific & may (alternate authentication method) & \\ +{async} & service specific & may (alternate authentication method) & \\ +VOSI-availability & /availability & should & \\ +VOSI-capabilities & /capabilities & must & \\ +VOSI-tables & /tables & should & \\ +DALI-examples & /examples & should & \\ \end{tabular} -The resources and parameters are described in detail below. The description of -these resources and parameters spell out how the requirements here are to be -implemented. +At least one set of {sync} and {async} resources must be named /sync and +/async respectively for backwards compatibility with TAP-1.0 (which required +these names. These resources must be used for anonymous query execution. Other +{sync} and {async} resources may have service specific names, but all resources +listed above must be siblings so that a client with one such URL can find the +VOSI-capabilities URL and thus discover other available resources. -TAP service registration in the IVOA resource-registry is specified in section -3. - -\subsection{Resources} -A TAP service must be represented as a tree structure of web resources each +A TAP service must be represented as a set of sibling web resources each addressable via a URL in the http scheme, or the https scheme, or both. The web resource at the root of the tree must represent the service as a whole. @@ -319,7 +293,7 @@ \subsection{Resources} an HTML page describing the scientific usage and content of the service. TAP clients must not depend on a specific representation of the root web-resource. -\subsubsection{/sync} +\subsection{\{sync\}} A TAP service must provide a web resource with relative URL /sync that is a direct child of the root web resource. This web resource represents the results of synchronous requests. The exact form of the query, and hence the @@ -338,7 +312,7 @@ \subsubsection{/sync} which require an up-to-date representation of volatile data or metadata must use HTTP POST. -\subsubsection{/async} +\subsection{\{async\}} A TAP service must provide a web resource with relative URL /async that is a direct child of the root web resource. This web resource represents controls for asynchronous queries. Specifically, the web resource must represent the job-list @@ -405,7 +379,7 @@ \subsubsection{/async} data rows. Details on interacting with these resources are specified in the UWS standard; for examples specific to TAP see Section 5 below. -\subsubsection{/availability} +\subsection{/availability} The VOSI availability metadata should be accessible from a web resource with relative URL /availability that is a direct child of the root web resource. If implemented, the /availability resource must be accessible via the http GET @@ -414,25 +388,164 @@ \subsubsection{/availability} Services which do not implement the /availability resource must respond with an HTTP response code of 404 when this resource is accessed. -\subsubsection{/capabilities} +\subsection{/capabilities} +The TAP-1.0 standard is identified using +\begin{verbatim} +ivo://ivoa.net/std/TAP +\end{verbatim} + +For TAP-1.1 we define new standard identifiers for each of the +features. Asynchronous query execution is described by standardID: + +\begin{verbatim} +ivo://ivoa.net/std/TAP#async-1.1 +\end{verbatim} + +Synchronous query execution is described by standardID: + +\begin{verbatim} +standardID="ivo://ivoa.net/std/TAP#sync-1.1 +\end{verbatim} + +In TAP-1.0 the base URL was described with a single standard identifier; in +TAP-1.1 and beyond, individual resources are described with their on +standardID. This allows service providers to describe multiple resources that +deliver the specified feature (e.g with different authentication methods) in +the VOSI-capabilities resource. + +The VOSI standard specifies that the capability metadata is encoded as an XML +document which lists each of the service's capabilities as a +element. The type of this element (which defines the contents) is +{http://www.ivoa.net/xml/VOResource/v1.0}Capability from the VOResource XML +standard [8]. + +In addition, the capabilities output must also comply with the following +requirements: + +* the returned document must include elements +that describes the service's support for the TAP protocol using the TAP and +VOSI standardID values + +* this capability element must include at least one element +with its "role" attribute set to "std", + +Note: VO registries recognize a service's support for a standard protocol +through this capability description. In particular, a different standard +Capability sub-type is used for each standard protocol to provide capability +metadata that is specific to that protocol. At the time of this writing, a +Capability sub-type for TAP has not yet been defined. Thus for compliance with +this standard, any legal Capability description that meets the above +restrictions is sufficient. However, once a VOResource extension for TAP is +standardized, it is strongly recommended that TAP services emit its +capabilities using that the Capability sub-type specialized for TAP. + +For example, the returned capabilities document for a service supporting TAP +might look as follows: + +\begin{verbatim} + + + + + + + http://myarchive.net/myTAP/async + + + + + + http://myarchive.net/myTAP/sync + + + + + + + http://myarchive.net/myTAP/capabilities + + + + + + + http://myarchive.net/myTAP/availability + + + + + + + + http://myarchive.net/myTAP/tables + + + + +\end{verbatim} + The service capabilities must be accessible from a web resource with relative URL /capabilities that is a direct child of the root web resource. The /capabilities resource must be accessible via the http GET method. The content is described by [8]. -\subsubsection{/tables} +\subsection{/tables} The table metadata should be accessible from a web resource with relative URL /tables that is a direct child of the root web resource. The /tables resource -must be accessible via the http GET method. The content is described by [7] and -is equivalent to the metadata from the TAP\underline{' '}SCHEMA described in 2.6 -. +must be accessible via the http GET method. The content is described by [7] and +is equivalent to the metadata from the TAP\underline{' '}SCHEMA described in +XREF. Services which do not implement the /tables resource must respond with an HTTP response code of 404 when this resource is accessed. -\subsection{Parameters} -The /sync and /async web-resources must accept the parameters listed in the -following sub-sections. In a synchronous request, the parameters select the +\subsection{/examples} +A GET from this endpoint MUST yield a document with a MIME type of either +application/xhtml+xml or text/html. A service that does not provide examples +MUST return a 404 HTTP status on accessing this resource. + +If present, the endpoint must be represented in a capability in the TAP +service's registry record. The capability's standardID is defined by +[std:DALI]. A capability element could hence look like this: + +\begin{verbatim} + + + http://myarchive.net/myTAP/examples + + +\end{verbatim} + +TAP defines two additional properties vocabulary: + +* query -- each example MUST have a unique child element with simple text +content having a property attribute valued query. It contains the query itself, +preferably with extra whitespace for easy human consumption and editing. This +will usually be a HTML pre element. + +* table -- examples MAY also have descendants with property attributes having +the value table. These must have pure text content and contain fully qualified +table names to which the query is somehow "pertaining". Suitable HTML elements +holding these include span, or a (which would allow linking to further +information on the table). + +When using elements with src or href attributes to carry the property +attributes, note that the element content must be repeated in a content +attribute, as otherwise RDFa clients would interpret the embedded link rather +than the element content as the object in the triple. + +TODO: add example(s) here + +\subsection{Parameters for \{async\} and \{sync\}} +The \{async\} and \{sync\} web-resources must accept the parameters listed in +the following sub-sections. In a synchronous request, the parameters select the representation returned in the response message. In an asynchronous request, the parameters select the representation of the eventual query result rather than the response to the initial request. @@ -449,9 +562,9 @@ \subsection{Parameters} carries LANG=ADQL then the SELECT parameter (from PQL) is spurious. If a service receives a spurious parameter in an otherwise correct request, then the service must ignore the spurious parameter, must respond to the request normally -and must not report errors concerning the spurious parameter. +and must not report errors concerning the spurious parameter. -\subsubsection{REQUEST} +\subsubsection{REQUEST - remove? } This parameter distinguishes current service operations, makes it possible to extend the service specification (with additional or custom operations), and specifies how other parameters should be interpreted. If a TAP service attempts @@ -465,7 +578,7 @@ \subsubsection{REQUEST} getCapabilities: return VOSI-capabilities metadata -All requests to execute (/async or /sync) a query using a query language must +All requests to execute a query using a query language must include REQUEST=doQuery and must include the LANG parameter. For other values of REQUEST, additional parameters may or may not be required. The REQUEST=getCapabilities service operation must be supported for synchronous @@ -480,19 +593,10 @@ \subsubsection{REQUEST} to the created job resource, in one or more separate HTTP requests. The parameter names remain the same in both cases. -\subsubsection{VERSION} -The VERSION parameter specifies the TAP protocol version number. The format of -the version number, and version negotiation, are described in section 2.9.2 . - -A TAP service must support the VERSION parameter. This specification is for TAP -1.0; the client would specify VERSION=1.0 if the request is made using the -protocol described here. - \subsubsection{LANG} The LANG parameter specifies the query language. The service must support LANG and the client must provide a value with REQUEST=doQuery. The only standard -values for the LANG parameter are ADQL (a required language) and PQL (reserved -value for an optional language which is under development). Support for other +values for the LANG parameter is ADQL (a required language). Support for other languages and the LANG value to use with them is described in the service capabilities. @@ -528,10 +632,8 @@ \subsubsection{QUERY} sensitive except for character literals; schema, table, and column names, function names, and other ADQL keywords are not case sensitive. -Within the ADQL query, the service must support the use of timestamp values in -ISO8601 format, specifically yyyy-MM-dd['T'HH:mm:ss[.SSS]], where square -brackets denote optional parts and the 'T' denotes a single character separator -(T) between the date and time parts. +Within the ADQL query, the service must support the use of timestamp values as +described in [std:DALI]. If the tables that are queried through a service contain columns with spatial coordinates and the service supports spatial querying via the ADQL “region” @@ -550,233 +652,322 @@ \subsubsection{QUERY} be transformed to ICRS; it simply tells the service to treat the values as being expressed in that coordinate system. -\subsubsection{Parameters for PQL} -A number of parameters will be defined by the PQL standard for use in parametric -queries. All of the parameters for PQL are are used unchanged in TAP. - -Within the PQL query, the service must support the use of timestamp values in -ISO8601 format (see 2.3.4 ). - -If the table that is queried contains columns with spatial coordinates and the -service provider wants to enable the caller to perform spatial queries, the -service must support the PQL spatial constraint parameters (POS,SIZE and -REGION). If a service supports the REGION parameter, it must support region -encoding in STC-S as decribed in section 6 ; the extent of STC-S support within -the REGION function is left up to the implementation. Coordinate system -qualifiers must use values from from STC-S as described in section 6 . - -PQL defines symbolic values (@something). In TAP these can be used to refer to -an uploaded table (see 2.5 ) with parameters that support a table reference. -When used in this way, the uploaded table must be treated as if in the -TAP\underline{' '}UPLOAD schema (e.g. @TAP\underline{' '}UPLOAD.mytable). -Details on how to use table references in PQL will be described in the PQL -specification. - -\subsubsection{FORMAT} -The FORMAT parameter indicates the client's desired format for the table of -results of a query. Its value should be a MIME type for tabular data or one of -the following shorthand forms: - -TODO: add table here - -Both MIME types and the shorthand forms are insensitive to case. If the FORMAT -parameter is omitted, the default format is VOTable. - -A TAP service must support VOTable as an output format, should support CSV and -TSV output and may support other formats. A TAP service must accept a FORMAT -parameter indicating a format that the service supports and should reject -queries where the FORMAT parameter specifies a format not supported by the -service implementation. +\subsubsection{FORMAT and RESPONSEFORMAT} +The RESPONSEFORMAT parameter is fully described in [std:DALI]. For backwards +compatibility, TAP-1.1 must also accept the FORMAT parameter as equivalent to +RESPONSEFORMAT. \subsubsection{MAXREC} -The service must accept a MAXREC parameter specifying the maximum number of -table records (rows) to be returned. If MAXREC is not specified in a query, the -service may apply a default value or may set no limit. If the result set for a -query exceeds this value, the service must only return the requested number of -rows. If the result set is truncated in this fashion, it must include an -overflow indicator as specified in section 2.7.4 . - -The service must support the special value of MAXREC=0. This value indicates -that, in the event of an otherwise valid request, a valid output table be -returned containing metadata, no table data rows, and an overflow indicator as -specified in section 2.7.4 . The service is not required to execute the query; -a successful MAXREC=0 request does not necessarily mean that the query is valid -and the overflow indicator does not necessarily mean that there is at least one -row satisfying the query. The service may perform validation and may try to -execute the query, in which case a MAXREC=0 request can fail. - -A query with MAXREC=0 can be used with a simple query (e.g. SELECT * FROM +The MAXREC parameter and its effect on the query result is fully described in +[std:DALI]. If the result set is truncated in this fashion, it must include an +overflow indicator as specified in section XREF. + +For the special value of MAXREC=0, the service is not required to execute the +query; a successful MAXREC=0 request does not necessarily mean that the query +is valid and the overflow indicator does not necessarily mean that there is at +least one row satisfying the query. The service may perform validation and may +try to execute the query, in which case a MAXREC=0 request can fail. A query +with MAXREC=0 can be used with a simple query (e.g. SELECT * FROM some\underline{' '}table) to extract and examine the VOTable metadata (assuming FORMAT=votable). Note: in this version of TAP, this is the only mechanism to learn some of the detailed metadata, such as coordinate systems used. \subsubsection{RUNID} -The service should implement the RUNID parameter, used to tag service requests -with the job ID of a larger job of which the request may be part. The RUNID -parameter is defined in [3] for /async requests; services should also implement -it for /sync requests. - -For example, if a cross match portal issues multiple requests to remote TAP -services to carry out a cross-match operation, all would receive the same RUNID, -and the service logs could later be analyzed to reconstruct the service -operations initiated in response to the job. +The RUNID parameter is fully described in [std:DALI]. -The service should ensure that RUNID is preserved in any service logs and -should pass on the RUNID value in any calls to other services. +\subsubsection{VERSION} +The VERSION parameter is fully described in {std:DALI]. \subsubsection{UPLOAD} -The service should support table upload via the UPLOAD parameter. The value is a -list of table-name,URI pairs. Table names must be legal ADQL table names as -defined in [1]. URIs maybe be simple URLs (e.g. with a URI scheme of http) or -URIs (e.g. with a URI scheme of vos or param) that must be resolved to give the -location of the table content. See section 2.5 for details. - -\subsubsection{Case of Parameters} -NOTE: this is in DALI now - -\subsubsection{Order and Cardinality of Parameters} -NOTE: this is in DALI now +The UPLOAD parameter is described in [std:DALI]. Services should support the +upload of temporary tables (in [std:VOTable] format) via the standard UPLOAD +parameter. The table-name(s) must be legal ADQL table names as defined in +[std:ADQL] but restricted as described below XREF. URIs maybe be simple URLs +(e.g. with a URI scheme of http) or URIs (e.g. with a URI scheme of vos or +param) that must be resolved to give the location of the table content. See +section XREF for details. + +If table upload supported, the service must accept tables in VOTable format. +The client specifies the name of the uploaded table; this name must be a legal +ADQL table name with no catalog or schema (i.e., a string following the +regular identifier production of [std:ADQL]). Uploaded tables must be referred +to in queries as TAP\underline{' '}UPLOAD., where is the +specified by the user. Tables in the TAP\underline{' '}UPLOAD schema are +transient and persist only for the lifetime of the query (although caching might +be used behind the scenes) and are never visible in the +TAP\underline{' '}SCHEMA metadata. + +The [std:DALI] UPLOAD parameter supports both external resources and in-line +content. For external resources, one provides a URI (usually an HTTP URL) the +TAP service can use to obtain the table content. For example, +\begin{verbatim} +HTTP POST http://example.com/tap/async/42 +UPLOAD=mytable,http://otherplace.com/path/votable.xml +\end{verbatim} +The service would retrieve the table from the provided URL and +make it visible to the query as TAP\underline{' '}UPLOAD.mytable. -\subsection{Table Names} -A fully qualified table name has the form +If the TAP service supports VOSpace (TBD: how to declare this?), one may +specify an upload table using a URI to a table stored in a VOSpace, for example: \begin{verbatim} -[[catalog_name”.”]schema_name”.”]table_name +HTTP POST http://example.com/tap/async/42 +UPLOAD=mytable,vos://space/path/votable.xml \end{verbatim} -where catalog\underline{' '}name is the name of the DB catalogue (often the -“database” name) in SQL DBMS terminology, schema\underline{' '}name is the name -of the “schema” in DBMS terminology (often also called a “database”; a DBMS -schema is a type of data model where the top level data model elements are -tables), and table\underline{' '}name is the actual table name. All elements of -the table name are optional except table\underline{' '}name. Depending upon the -DBMS, “catalog” or “schema” may or may not be implemented; some DBMS implement -both, others one or the other, and the simplest database systems might not -implement either. - -The implementation of a TAP service must define the table names acceptable in -queries and must reveal these to clients through metadata queries or through -VOSI-tables output, and the names must be identical in each of these sources. A -TAP client must determine the acceptable names from one of these sources or from -the cached form of the VOSI-tables output included in the service's -registration. - -\subsection{Table Upload} -The service should implement the table upload capability. If upload is -supported, the service must accept tables in VOTable format. The client -specifies the name of the uploaded table; this name must be a legal ADQL table -name with no catalog or schema (e.g. an unqualified table name). Uploaded tables -must be referred to in queries as TAP\underline{' '}UPLOAD., where - is the specified by the user. - -Tables in the TAP\underline{' '}UPLOAD schema are transient and -persist only for the lifetime of the query (although caching might be used -behind the scenes) and are never visible in the TAP\underline{' '}SCHEMA -metadata. +The service would resolve the URI, contact the VOSpace, retrieve the table, and +make it visible to the query as TAP\underline{' '}UPLOAD.mytable. -The column names in the transient database table are taken directly from the -name attribute of the VOTable FIELD and PARAM elements. The datatypes of the -transient table are determined from the FIELD and PARAM attributes as follows: +UPLOADs are accumulating, i.e., each UPLOAD parameter given will create one or +more tables in TAP\underline{' '}UPLOAD. When the table names from two or more +upload items agree after case folding, the service behaviour is unspecified. +Clients thus cannot reliably overwrite uploaded tables; to correct errors, they +have to tear down the existing job and create a new one. In principle, any +number of tables can be uploaded using the UPLOAD parameter and any combination +of URI schemes supported by the service as long as they are assigned unique +table names within the query. Services may limit the size and number of +uploaded tables; if the service refuses to accept the entire table it must +respond with an error as described in 2.7.3 . -TODO: table -The default mapping of data types are shown above (no arraysize or xtype). If -the xtype attribute is set, this is the preferred internal datatype. If xtype is -not set, then the datatype and arraysize indicate the most suitable internal -datatype. +\section{Use of VOTable} +The [std:VOTable] format is the standard format for output (query results) and +input (table upload) in a TAP service. -In the arraysize column above, [1] means the arraysize is not set or is set to -1, n means arraysize is set to a specific value, * means arraysize=”*”, and n* -means arraysize=”n*” (variable size up to length n). A blank means the arraysize -is not set. -Binary values (unsignedByte in VOTable, BINARY, VARBINARY, or BLOB in ADQL) can -be expressed as specified by the VOTable standard. By default, VOTable allows -them to be written as an array of decimal numbers, e.g. 12 56 0 255 0 0 255 (one -number per byte value). +\subsection{INFO elements} +The RESOURCE element must contain an INFO element with attribute +name="QUERY\underline{' '}STATUS" indicating the success of the operation. For +RESOURCE elements that contain a TABLE element, this INFO element must appear +lexically before the TABLE. The following values are defined for this INFO +element's value attribute: -For columns of type BLOB or CLOB, most database systems support reference to -these columns in the select clause but not in any other part of the query. -Services may use these types to indicate that columns may only be selected. For -example, if service implementors want to make URL(s) available as column values -in the results, but do not actually store the URL(s) in the database, they would -specify a column with xtype=”adql:CLOB” and the column with URL(s) could be -referenced in the SELECT clause of a query, but could not be used in the WHERE -clause. The service could then process the query result and insert the URL(s) -or, more likely, transform a column value (an identifier) into a URL while -writing the results. +“OK”, meaning that the query executed successfully and a result table is +included in the resource -TIMESTAMP values are specified using ISO8601 format without a timezone (as in -2.3.4 ) and are assumed to be in UTC. The xtype=”adql:TIMESTAMP” attribute must -be specified in an uploaded VOTable in order for the values to be inserted in a -column of type TIMESTAMP; without the xtype, the values would be inserted into a -CHAR(n) or VARCHAR column. +"ERROR”, meaning that an error was detected at the level of the TAP +protocol or the query failed to execute -POINT and REGION values are specified in STC-S format (see section 6 ). The -xtype=”adql:POINT” attribute must be specified in an uploaded VOTable in order -for the char values to be parsed and treated as POINTs (e.g. to be used with -some of the ADQL region functions). For regions, the xtype=”adql:REGION” -attribute must be specified in an uploaded VOTable in order for the char values -to be parsed and treated as REGIONs (e.g. to be used with some of the ADQL -region functions). +The content of the INFO element conveying the status should be a message +suitable for display to the user describing the status. -\subsubsection{UPLOAD} -The UPLOAD parameter is used to reference read-only external tables via their -URI, to be uploaded for use as input tables to the query. The value of the -UPLOAD parameter is a list of table name-URI pairs. Elements of the list are -delimited by semicolon and the two parts of the pair are delimited by comma. For -example: \begin{verbatim} -UPLOAD=table_a,http://host_a/path;table_b,http://host_b/path + \end{verbatim} - -would define two input tables table\underline{' '}a and -table\underline{' '}b, located at the given URIs. Services that implement -UPLOAD must support http as a URI scheme (e.g. must support treating an http URI -as a URL). A VOSpace URI (vos:) is a more generic example of a URI -that requires more service-side functionality; support for the vos scheme is -optional. - -\subsubsection{Inline Table Upload} -To upload a table inline, the caller must specify the UPLOAD parameter (as -above) using a special URI scheme “param”. This scheme indicates that the value -after the colon will be the name of the inline content. The content type used is -multipart/form-data, using a “file” type input element. The “name” attribute -must match that used in the UPLOAD parameter. - -For example, in the POST data we might have this parameter: + \begin{verbatim} -UPLOAD=table_c,param:table1 +Successful query \end{verbatim} -and this content: -\begin{verbatim} -Content-Type: multipart/form-data; boundary=AaB03 -[...] - ---AaB03x +\begin{verbatim} + + value out of range in POS=45,91 + +\end{verbatim} -Content-disposition: form-data; name="table1"; filename="table1.xml" +Additional INFO elements may be provided, e.g., to echo the input parameters +back to the client in the query response (a useful feature for debugging or to +self-document the query response), but clients should not depend on these. -Content-type: application/x-votable+xml +\begin{verbatim} + + + unrecognized operation + + + + + + +\end{verbatim} -[...] +If an overflow occurs (result exceeds MAXREC), the service must close the table +and append another INFO element to the RESOURCE (after the TABLE) with +name=”QUERY\underline{' '}STATUS” and the value=”OVERFLOW”. +\begin{verbatim} + + +... +...
+ + +\end{verbatim} ---AaB03x +In the above example, the TABLE should have exactly MAXREC rows. -[...] +If an error occurs while writing the rows of the VOTable, the service must +close the table and append another INFO element to the RESOURCE, after the +TABLE, with name=”QUERY\underline{' '}STATUS” and the value=”ERROR”. +\begin{verbatim} + + +... +...
+ + \end{verbatim} -The uploaded table would be referenced in queries as -TAP\underline{' '}UPLOAD.table\underline{' '}c (the table name in the UPLOAD -parameter). Services that implement table upload must support the param scheme -for inline uploads. - -In principle, any number of tables can be uploaded using the UPLOAD parameter -and any combination of URI schemes supported by the service as long as they are -assigned unique table names within the query. Services may limit the size and -number of uploaded tables; if the service refuses to accept the entire table it -must respond with an error as described in 2.7.3 . - -\subsection{Metadata and TAP SCHEMA} -There are several approaches to getting metadata for a given TAP service. All +The content of these trailing INFO elements is optional and intended for users; +client software should not depend on it. + +Thus, one INFO element with name=”QUERY\underline{' '}STATUS” and value=”OK” or +value=”ERROR” must be included before the TABLE. If the TABLE does not contain +the entire query result, one INFO element with value=”OVERFLOW” or +value=”ERROR” + must be included after the table. +2.9.2 Version Mismatch Errors + +Errors due to version mismatch from either the VERSION parameter (TAP version) +or specific version used in the LANG parameter (query language version) are +specified using an INFO element with name=”QUERY\underline{' '}STATUS” and +value=”ERROR” as described above. + +\subsection{Successful Queries} + +The result of a query depends on the query language used and may be one or more +tables in one or more resources. Unsupportable combinations of query result and +FORMAT (e.g. queries that produce multiple tables and an inherently +single-table format like CSV) will cause the request to fail. Currently, an ADQL +query result must be a single table (in a single file). + +The output table must include the same number and order of columns as specified +in the SELECT clause of the query. For VOTable output, the name attribute of +FIELD elements must be the same as the column names (or aliases if specified in +the query) from the query and the datatype, arraysize, and xtype attributes of +FIELD elements must be set using the mapping specified in section 2.5 . The +xtype attribute in the output must match the datatype for the column in the +TAP\underline{' '}SCHEMA. + +VOTable structure follows the rules in section 2.9 and must be returned with an +allowed VOTable MIME type (application/x-votable+xml or text/xml). If the +FORMAT parameter (see 2.3.6 ) of the request specified a specific VOTable MIME +type, the requested MIME type must be used in the HTTP response. + +CSV formatted data should represent the output table with one row of text per +table row, with the table column values rendered as text and separated by +commas. If a column value contains a comma the entire column value should be +enclosed in double quotes. Text lines may be arbitrarily long. The first data +row should give the column name as the data value. CSV data must be returned +with a MIME type of text/csv; if the optional header line (with column names) +is included, the MIME type must be text/csv;header=present. Full details of CSV +format are defined in RFC 4180 [14]. + +TSV formatted data should represent the output table with one row of text per +table row, with the table column values rendered as text and separated by the +TAB character. TSV data must be returned with a MIME type of +text/tab-separated-values [15]. Column values may not contain the TAB +character. + +\subsection{Errors} +If the service detects an exceptional condition, it must return an error +document with an appropriate HTTP-status code. TAP distinguishes three classes +of exceptions. + +Errors in the use of the HTTP protocol. + +Errors in the use of the TAP protocol, including both invalid requests and +failure of the service to complete valid requests. + +Error documents for HTTP-level errors are not specified in the TAP protocol. +Responses to these errors are typically generated by service containers and +cannot be controlled by TAP implementations. There are several cases where a +TAP +service could return an HTTP error. First, the /async endpoint could return a +404 (not found) error if the client accesses a job within the UWS joblist that +does not exist. Second, access to a resource could result in an HTTP 401 (not +authorized) error if authentication is required or an HTTP 403 (forbidden) +error if the client is not allowed to access the resource. + +Error documents for TAP errors must be VOTable documents; any result-format +specified in the request is ignored. If the error document is being retrieved +from the /async//error resource (specified by UWS) after an asynchronous +query, the HTTP status code should be 200. If the error document is being +returned directly after a synchronous query, the service may use an appropriate +HTTP status code, including 200 (successfully returning a response to the +request) and various 4xx and 5xx values. The exception condition must be +described to the client using a status code in the VOTable header. Section +2.9 specifies the use of VOTable for error documents in TAP services. + +\subsection{Overflows} +If a query is executed by a TAP service, the number of rows in the table of +results may exceed a limit requested by the user (using the MAXREC parameter) +or a limit set by the service implementation (the default or maximum value of +MAXREC). In these cases, the query is said to have 'overflowed'. Typically, a +TAP service will not detect an overflow until some part of the table of results +has been sent to the client. + +If an overflow occurs, the TAP service must produce a table of results that is +valid, in the required output format, and which contains all the results up to +the point of overflow. Since an output overflow is not an error condition, the +MIME type of the output must be the same as for any successful query and the +HTTP status-code must be as for a successful, complete query. + +If the output format is VOTable, section 2.9.1 describes the method by which +the overflow is reported. No method of reporting an overflow is defined for +formats other than VOTable. + +\subsection{VOTable vs RDBMS Tables and Columns} + +TODO: describe the bi-directional mapping of VOTable <-> RDBMS table aka the +old section on uploading tables... should this come earlier in the doc? + +The column names in the transient database table are taken directly from the +name attribute of the VOTable FIELD and PARAM elements. TODO: add column name +restrictions here to avoid quoted identifiers. The datatypes of the +transient table are determined from the FIELD and PARAM attributes as follows: + +TODO: something like the table from TAP-1.0 + +The default mapping of data types are shown above (no arraysize or xtype). If +the xtype attribute is set, this is the preferred internal datatype. If xtype is +not set, then the datatype and arraysize indicate the most suitable internal +datatype. Note that the last column of Table (x) is not normative. +Implementations SHOULD try to make sure that the actual types chosen are at +least signature-compatible with the recommended types (i.e., integers should +remain integers, floating-point values floating-point values, etc.), such that +clients can reliably write queries against uploaded tables. + +For columns with xtype adql:REGION, this is particularly critical, since +databases typically use different types to represent various STC-S objects. +Clients are advised to assume that such columns will be approximated with +polygons in the actual database table. + +In the arraysize column above, [1] means the arraysize is not set or is set to +1, n means arraysize is set to a specific value, * means arraysize=”*”, and n* +means arraysize=”n*” (variable size up to length n). A blank means the arraysize +is not set. + +Binary values (unsignedByte in VOTable, BINARY, VARBINARY, or BLOB in ADQL) can +be expressed as specified by the VOTable standard. By default, VOTable allows +them to be written as an array of decimal numbers, e.g. 12 56 0 255 0 0 255 (one +number per byte value). + +For columns of type BLOB or CLOB, most database systems support reference to +these columns in the select clause but not in any other part of the query. +Services may use these types to indicate that columns may only be selected. For +example, if service implementors want to make URL(s) available as column values +in the results, but do not actually store the URL(s) in the database, they would +specify a column with xtype=”adql:CLOB” and the column with URL(s) could be +referenced in the SELECT clause of a query, but could not be used in the WHERE +clause. The service could then process the query result and insert the URL(s) +or, more likely, transform a column value (an identifier) into a URL while +writing the results. + +TIMESTAMP values are specified as described in [std:DALI]. The +xtype=”adql:TIMESTAMP” attribute must be specified in an uploaded VOTable in +order for the values to be inserted in a column of type TIMESTAMP; without the +xtype, the values would be inserted into a CHAR(n) or VARCHAR column. + +POINT and REGION values are specified in STC-S format (see section 6 ). The +xtype=”adql:POINT” attribute must be specified in an uploaded VOTable in order +for the char values to be parsed and treated as POINTs (e.g. to be used with +some of the ADQL region functions). For regions, the xtype=”adql:REGION” +attribute must be specified in an uploaded VOTable in order for the char values +to be parsed and treated as REGIONs (e.g. to be used with some of the ADQL +region functions). + +\section{Metadata: TAP SCHEMA} + +There are several approaches to getting metadata for a given TAP service. All TAP services must support a set of tables in a schema named TAP\underline{' '}SCHEMA that describe the tables and columns included in the service. In addition to the TAP\underline{' '}SCHEMA, there are two other ways @@ -811,7 +1002,7 @@ \subsection{Metadata and TAP SCHEMA} in the standard tables described below. For example, one could include a column with a timestamp saying when metadata values were was last modified. -\subsubsection{Schemas} +\subsection{Schemas} The table TAP\underline{' '}SCHEMA.schemas must contain the following columns: TODO: table @@ -822,7 +1013,7 @@ \subsubsection{Schemas} [catalog.]schema. The schema metadata are included for reference and are not used directly to construct queries. -\subsubsection{Tables} +\subsection{Tables} The table TAP\underline{' '}SCHEMA.tables must contain the following columns: TODO: table @@ -833,7 +1024,7 @@ \subsubsection{Tables} depending on the implementation requirements. The fully qualified table name is defined by the ADQL language and follows the pattern [[catalog.]schema.]table. -\subsubsection{Columns} +\subsection{Columns} The table TAP\underline{' '}SCHEMA.columns must contain the following columns: TODO: table @@ -844,19 +1035,28 @@ \subsubsection{Columns} Data types and how they map to VOTable datatypes are described in section 2.5 above. The “size” gives the length of variable length datatypes, for example varchar(256); this size does not map to the VOTable arraysize attribute when the -latter specifies the size and shape of a multi-dimensional array. The -“principal” flag indicates that the column is considered a core part the +latter specifies the size and shape of a multi-dimensional array. To use size in +a query, it must be put in double quotes since it collides with an ADQL reserved +word. Since delimited identifiers are case-sensitive, for the size column both +clients and servers MUST always (in particular, in the DDL for +TAP\underline{' '}SCHEMA) use lower case exclusively. In the next major version +of TAP, this column will be called arraysize. + +The “principal” flag indicates that the column is considered a core part the content; clients can use this hint to make the principal column(s) visible, for example by selecting them by default in generating an ADQL query. In cases where the services selects the columns to return (such as PQL without a SELECT parameter), the principal column indicates those columns that are returned by -default. The “indexed” flag indicates that the column is indexed, potentially -making queries run much faster if this column is used in a constraint. The “std” -is included for compatibility with the registry, which uses this value to -indicate that a given column is defined by some standard, as opposed to a custom -column defined by a particular service. +default. -\subsubsection{Foreign Keys} +The “indexed” flag indicates that the column is indexed, potentially +making queries run much faster if this column is used in a constraint. + +The “std” is included for compatibility with the registry, which uses this value +to indicate that a given column is defined by some standard, as opposed to a +custom column defined by a particular service. + +\subsection{Foreign Keys} The table TAP\underline{' '}SCHEMA.keys must contain the following columns to describe foreign key relations between tables: @@ -878,381 +1078,19 @@ \subsubsection{Foreign Keys} A TAP service must provide the tables listed above and may provide other tables in the TAP\underline{' '}SCHEMA namespace. -\subsection{Access to and Representation of Results} -\subsubsection{Data and Metadata Queries} -The result of a data query or a metadata query depends on the query language -used and may be one or more tables in one or more resources. Unsupportable -combinations of query result and FORMAT (e.g. queries that produce multiple -tables and an inherently single-table format like CSV) will cause the request to -fail. Currently, an ADQL query result must be a single table (in a single file). - -This table must be encoded in the output format specified by the FORMAT -parameter of the query. See section 2.3.6 for required, optional and default -formats. VOTable is the default format and VOTable support is mandatory. - -The output table must include the same number and order of columns as specified -in the SELECT clause of the query. For VOTable output, the name attribute of -FIELD elements must be the same as the column names (or aliases if specified in -the query) from the query and the datatype, arraysize, and xtype attributes of -FIELD elements must be set using the mapping specified in section 2.5 . The -xtype attribute in the output must match the datatype for the column in the -TAP\underline{' '}SCHEMA. - -VOTable structure follows the rules in section 2.9 and must be returned with an -allowed VOTable MIME type (application/x-votable+xml or text/xml). If the FORMAT -parameter (see 2.3.6 ) of the request specified a specific VOTable MIME type, -the requested MIME type must be used in the HTTP response. - -CSV formatted data should represent the output table with one row of text per -table row, with the table column values rendered as text and separated by -commas. If a column value contains a comma the entire column value should be -enclosed in double quotes. Text lines may be arbitrarily long. The first data -row should give the column name as the data value. CSV data must be returned -with a MIME type of text/csv; if the optional header line (with column names) is -included, the MIME type must be text/csv;header=present. Full details of CSV -format are defined in RFC 4180 [14]. - -TSV formatted data should represent the output table with one row of text per -table row, with the table column values rendered as text and separated by the -TAB character. TSV data must be returned with a MIME type of -text/tab-separated-values [15]. Column values may not contain the TAB -character. - -\subsubsection{VOSI} -Representations of VOSI outputs (capabilities, availability, table metadata) -must be as defined in the VOSI standard [6]. - -The representation of table metadata must include all tables in the service's -tableset. VOSI's representation of table metadata is specified in VODataService -[7]. - -The VOSI standard specifies that the capability metadata is encoded as an XML -document which lists each of the service's capabilities as a -element. The type of this element (which defines the contents) is -{http://www.ivoa.net/xml/VOResource/v1.0}Capability from the VOResource XML -standard [8]. - -In addition, the capabilities output must also comply with the following -requirements: - - •.the returned document must include one element that describes -the service's support for the TAP protocol - - •.this element must have its "standardID" attribute set to -"ivo://ivoa.net/std/TAP" - - •.this capability element must include at least one "" element -with its "role" attribute set to "std", - - •.this "" element must contain a child "" element with -the attribute "use" set to "base" which contains the root web resource for the -service as defined in section 2.2 . - -Note: VO registries recognize a service's support for a standard protocol -through this capability description. In particular, a different standard -Capability sub-type is used for each standard protocol to provide capability -metadata that is specific to that protocol. At the time of this writing, a -Capability sub-type for TAP has not yet been defined. Thus for compliance with -this standard, any legal Capability description that meets the above -restrictions is sufficient. However, once a VOResource extension for TAP is -standardized, it is strongly recommended that TAP services emit its capabilities -using that the Capability sub-type specialized for TAP. - -For example, the returned capabilities document for a service supporting TAP -might look as follows: - -\begin{verbatim} - - - - - - - - - http://myarchive.net/myTAP - - - - - - - - - - - - http://myarchive.net/myTAP/capabilities - - - - - - - - - - - - http://myarchive.net/myTAP/availability - - - - - - - - - - - - - - http://myarchive.net/myTAP/tables - - - - - - -\end{verbatim} - -\subsubsection{Errors} -If the service detects an exceptional condition, it must return an error -document with an appropriate HTTP-status code. TAP distinguishes three classes -of exceptions. - -Errors in the use of the HTTP protocol. - -Errors in the use of the TAP protocol, including both invalid requests and -failure of the service to complete valid requests. - -Error documents for HTTP-level errors are not specified in the TAP protocol. -Responses to these errors are typically generated by service containers and -cannot be controlled by TAP implementations. There are several cases where a TAP -service could return an HTTP error. First, the /async endpoint could return a -404 (not found) error if the client accesses a job within the UWS joblist that -does not exist. Second, access to a resource could result in an HTTP 401 (not -authorized) error if authentication is required or an HTTP 403 (forbidden) error -if the client is not allowed to access the resource. - -Error documents for TAP errors must be VOTable documents; any result-format -specified in the request is ignored. If the error document is being retrieved -from the /async//error resource (specified by UWS) after an asynchronous -query, the HTTP status code should be 200. If the error document is being -returned directly after a synchronous query, the service may use an appropriate -HTTP status code, including 200 (successfully returning a response to the -request) and various 4xx and 5xx values. The exception condition must be -described to the client using a status code in the VOTable header. Section -2.9 specifies the use of VOTable for error documents in TAP services. - -\subsubsection{Overflows} -If a query is executed by a TAP service, the number of rows in the table of -results may exceed a limit requested by the user (using the MAXREC parameter) or -a limit set by the service implementation (the default or maximum value of -MAXREC). In these cases, the query is said to have 'overflowed'. Typically, a -TAP service will not detect an overflow until some part of the table of results -has been sent to the client. - -If an overflow occurs, the TAP service must produce a table of results that is -valid, in the required output format, and which contains all the results up to -the point of overflow. Since an output overflow is not an error condition, the -MIME type of the output must be the same as for any successful query and the -HTTP status-code must be as for a successful, complete query. - -If the output format is VOTable, section 2.9.1 describes the method by which the -overflow is reported. No method of reporting an overflow is defined for formats -other than VOTable. - -\subsection{Versioning of the TAP Protocol} -The TAP protocol provides explicitly for versioning of the interface in order to -support version negotiation between a client and a service where one or both -parties support more than one version of the protocol. The TAP version refers -only to the TAP protocol; query languages are versioned separately and TAP and -ADQL versions may differ. - -Version numbers follow IVOA document conventions [17]. - -\subsubsection{Appearance in requests and in service metadata} -The version number may appear in at least three places: in the service metadata, -as a parameter in client requests to a server, and in the query response. The -version number used in a client’s request of a particular server must be equal -to a version number which that server has declared it supports (except during -negotiation, as described below). A server may support several versions, whose -values clients may discover according to the negotiation rules. - -\subsubsection{Version number negotiation} -If a TAP client does not specify the version number in a request, the server -assumes the highest standard version supported by the service, and no explicit -version checking takes place. If the client specifies an explicit version -number, and this does not match a version available from the service, the -service returns a version number mismatch error as described in 2.9.2 . The -client can determine what versions of the protocol the service supports by a -prior call to VOSI-capabilities or via a registry query. - -\subsection{Use of VOTable} -VOTable is a general format. TAP requires that it be used in a particular way. - -The result VOTable document must comply with VOTable v1.2 or greater [9]. For -columns containing coordinate values, the coordinate system metadata should be -provided as described in [13]. - -The VOTable must contain a RESOURCE element identified with the attribute -type="results", containing a single TABLE element with the results of the query. -Additional RESOURCE elements may be present, but the usage of any such elements -is not defined here and TAP clients should not depend upon them. - -\subsubsection{INFO elements} -The RESOURCE element must contain, before the TABLE element, an INFO element -with attribute name = "QUERY\underline{' '}STATUS". The value attribute must -contain one of the following values: - -“OK”, meaning that the query executed successfully and a result table is -included in the resource - -"ERROR”, meaning that an error was detected at the level of the TAP -protocol or the query failed to execute - -The content of the INFO element conveying the status should be a message -suitable for display to the user describing the status. - -\begin{verbatim} - -\end{verbatim} - -\begin{verbatim} -Successful query -\end{verbatim} - -\begin{verbatim} - - value out of range in POS=45,91 - -\end{verbatim} - -Additional INFO elements may be provided, e.g., to echo the input parameters -back to the client in the query response (a useful feature for debugging or to -self-document the query response), but clients should not depend on these. - -\begin{verbatim} - - - unrecognized operation - - - - - - -\end{verbatim} - -If an overflow occurs (result exceeds MAXREC), the service must close the table -and append another INFO element to the RESOURCE (after the TABLE) with -name=”QUERY\underline{' '}STATUS” and the value=”OVERFLOW”. -\begin{verbatim} - - -... -...
- - -\end{verbatim} - -In the above example, the TABLE should have exactly MAXREC rows. - -If an error occurs while writing the rows of the VOTable, the service must close -the table and append another INFO element to the RESOURCE, after the TABLE, with -name=”QUERY\underline{' '}STATUS” and the value=”ERROR”. -\begin{verbatim} - - -... -...
- - -\end{verbatim} -The content of these trailing INFO elements is optional and intended for users; -client software should not depend on it. - -Thus, one INFO element with name=”QUERY\underline{' '}STATUS” and value=”OK” or -value=”ERROR” must be included before the TABLE. If the TABLE does not contain -the entire query result, one INFO element with value=”OVERFLOW” or value=”ERROR” - must be included after the table. -2.9.2 Version Mismatch Errors - -Errors due to version mismatch from either the VERSION parameter (TAP version) -or specific version used in the LANG parameter (query language version) are -specified using an INFO element with name=”QUERY\underline{' '}STATUS” and -value=”ERROR” as described above. - -\section{Service Registration} -Publication of a service to the VO requires that it be registered with an IVOA -registry, including describing the identity and capabilities of the service. - -The resource document for a TAP service instance must be structured according to -VOResource [8] using the sub-type CatalogService as defined in VODataService -[7]. - -The resource document must include a capability element denoting the TAP -interface and functions. This element must contain the URL for the root web -resource (as defined in section 2.2 ). Clients would add to this URL /sync or -/async as appropriate. - -The resource document must contain capability elements for the -VOSI-capabilities, VOSI-availability and VOSI-tables outputs. These must be -formatted as in the VOSI standard [6]. - -The resource document should include the table metadata, except where the -database-schema of the archive changes frequently. Where table metadata are -provided, they must be represented as XML elements drawn from VODataService -[7]. - -\section{Extended Capabilities} -The TAP service allows for optional extended capabilities and operations. -Extensions may be defined within an information community when needed for -additional functionality or specialization. A generic client must not be -required or expected to make use of such extensions. Extended capabilities or -operations must be defined by the service metadata. Extended capabilities -provide additional metadata about the service, and may or may not enable -optional new parameters to be included in operation requests. Extended -operations may allow additional operations to be defined. - -A server must produce a valid response to the operations defined in this -document, even if parameters used by extended capabilities are missing or -malformed (i.e. the server must supply a default value for any extended -capabilities it defines), or if parameters are supplied that are not known to -the server. - -Service providers must choose extension names with care to avoid conflicting -with standard metadata fields, parameters and operations. - -\section{Use of UWS} +\section{Examples} The UWS pattern is specified in [3] and its application to TAP in section -2.2.2. This section explains the exchange of messages between a TAP client and -service when using UWS to run an asynchronous query. +XREF. This section gives examples of the exchange of messages between a +TAP client and service when using UWS to run an asynchronous query. +\subsection{Example: Asynchronous Query} Consider a TAP service at http://example.com/tap. TAP mandates that the -asynchronous requests be directed to http://example.com/tap/async. This URL -points to the list of 'jobs'; i.e. the list of queries currently or recently -executed. +asynchronous requests be directed to http://example.com/tap/async (e.g. for +anonymous queries). This URL points to the list of 'jobs'; i.e. the list of +queries currently or recently executed. -\subsection{Creating a Query} +\subsubsection{Creating a Query} To create a new query, the client POSTs a request to the job list: \begin{verbatim} @@ -1336,7 +1174,7 @@ \subsection{Creating a Query} DESTRUCTION=2008-11-11T11:11:11Z \end{verbatim} -\subsection{Running a Query} +\subsubsection{Running a Query} The phase URL shows the progress of the job. When the job is created by the service it will normally be set to PENDING, but might be set to ERROR if the service has rejected the job. If the phase is ERROR, then the error URL should @@ -1411,27 +1249,27 @@ \subsection{Running a Query} curl http://example.com/tap/42/results/result \end{verbatim} -\section{Use of STC-S in TAP} +\subsubsection{Example: Synchronous Query} -NOT: not included from TAP-1.0 since it was informative and does not belong in -this docuemnt. +TODO -\section{VOSpace Integration} -This version of TAP provides limited VOSpace integration, although better -support for VOSpace is planned for a later version following further -implementation experience. In this version, one may specify an upload table -using a URI to a table stored in a VOSpace, e.g.: -\begin{verbatim} -HTTP POST http://example.com/tap/async/42 -UPLOAD=mytable,vos://space/path/votable.xml -\end{verbatim} -The service would resolve the URI, contact the VOSpace, retrieve the table, and -make it visible to the query as TAP\underline{' '}UPLOAD.mytable. +\subsubsection{Example: DALI-examples Document} + +TODO -A future version of TAP may specify additional use and more integration with -VOSpace. +\section{Use of STC-S in TAP - deprecated} -\section{Use of HTTP} +NOTE: The old section 6 is not included from TAP-1.0 since it was informative +and does not belong in this document. If we need to define syntax for +points, circles, and polygons then that should be done in [std:DALI], which +already defines timestamp syntax. + +\section{VOSpace Integration - deprecated} + +Note: some text moved to the UPLOAD section; may propose DEST parameter for +outout. + +\section{Use of HTTP - deprecated} Note: This section is in or belongs in DALI. \appendix @@ -1440,6 +1278,20 @@ \section{Changes from Previous Versions} \subsection{Changes from TAP-1.0} +Restructured the document and removed text that duplicates material from DALI. +Rewrite the overly long introduction with some basic use cases to help define +the scope and tell readers what TAP is supposed to accomplish. + +Made clarifications: restricted allowed table names for UPLOAD, clarified that +multiple UPLOAD pamaters accumulate, deprecated the size column in +TAP\underline{' '}SCHEMA.columns and added advice to quote it as a delimited +identifier, made presence of a TABLE element on VOTable output only required for +successful queries, added optional DALI-examples endpoint (text TBD). + +Defined standardID values for the async and sync resource types and explicitly +allow for multiple of each resource (typically to support authentication). The +fixed paths /async and /sync are still required and are to provide anonymous +query access, which should be compatible with existing services. \bibliography{ivoatex/ivoabib} From a88cb388c5828f83e30cb633e88c121acbf0ca0d Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 6 May 2015 04:46:56 +0000 Subject: [PATCH 04/68] added tables describing the tap_schema tables; added section labels and cross-references --- TAP.tex | 192 +++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 135 insertions(+), 57 deletions(-) diff --git a/TAP.tex b/TAP.tex index a282814..f85381c 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1,4 +1,4 @@ -\documentclass[11pt,a4paper]{ivoa} +\documentclass[11pt,letter]{ivoa} \input tthdefs \usepackage[utf8]{inputenc} @@ -7,8 +7,7 @@ \ivoagroup{Data Access Layer Working Group} -\author{Patrick Dowler} -\author{TBD} +\author{Patrick Dowler, ...} \editor{Patrick Dowler} @@ -23,7 +22,7 @@ Access is provided for both database and table metadata as well as for actual table data. This version of the protocol includes support for multiple query languages, including queries specified using the Astronomical Data Query -Language (ADQL [1]) within an integrated interface. It also includes support +Language ([std:ADQL]) within an integrated interface. It also includes support for both synchronous and asynchronous queries. Special support is provided for spatially indexed queries using the spatial extensions in ADQL. A multi-position query capability permits queries against an arbitrarily large list of @@ -56,14 +55,14 @@ \section*{Conformance-related definitions} \section{Introduction} -The Table Access Protocol (TAP) is a Web-service protocol that gives access to +The Table Access Protocol (TAP) is a web-service protocol that gives access to collections of tabular data referred to collectively as a tableset. TAP services accept queries posed against the tableset available via the service and return the query response as another table, in accord with the relational model. Queries may be submitted using various query languages and may execute synchronously or asynchronously. Support for the Astronomical Data Query -Language (ADQL, [1]) is mandatory; support for other query languages is allowed -and optional. +Language ([std:ADQL]) is mandatory; support for other query languages is supported +but optional. The result of a TAP query is another table, normally returned as a VOTable. Support for VOTable output is mandatory; all other formats are optional. @@ -98,7 +97,7 @@ \subsection{Role within the VO Architecture} \label{fig:archdiag} \end{figure} -Fig.~\ref{fig:archdiag} shows the role this document plays within the +Fig.~section~\ref{fig:archdiag} shows the role this document plays within the IVOA architecture \citep{note:VOARCH}. @@ -135,7 +134,7 @@ \subsubsection{Query Standard Data Models} elements are mapped to tables and columns. \subsubsection{ADQL Queries} -The Astronomical Data Query Language (ADQL) [std:ADQL] is the standard +The Astronomical Data Query Language ([std:ADQL]) is the standard query language for the IVOA. Support for ADQL queries is mandatory. ADQL can be used to specify queries that access one or more tables provided by the TAP service, including the standard metadata tables. In general, the client must @@ -260,16 +259,18 @@ \subsection{Interface Overview -- move to examples section?} implemented interfaces. \section{Resources} +\label{sec:resources} An implementation of a TAP service provides the following RESTful resources under the base URL. \begin{tabular}{l l l l l} +\label{tab:resources} resource type & resource name & required \\ {sync} & /sync & must (anonymous) & \\ {async} & /async & must (anonymous) & \\ -{sync} & service specific & may (alternate authentication method) & \\ -{async} & service specific & may (alternate authentication method) & \\ +{sync} & service-specific & may (alternate authentication method) & \\ +{async} & service-specific & may (alternate authentication method) & \\ VOSI-availability & /availability & should & \\ VOSI-capabilities & /capabilities & must & \\ VOSI-tables & /tables & should & \\ @@ -294,16 +295,18 @@ \section{Resources} clients must not depend on a specific representation of the root web-resource. \subsection{\{sync\}} +\label{sec:tap-sync} + A TAP service must provide a web resource with relative URL /sync that is a direct child of the root web resource. This web resource represents the results of synchronous requests. The exact form of the query, and hence the representation of the resource, is defined by the query parameters as listed in -section 2.3. Representations of results of queries and VOSI outputs are defined -in sections 2.7.1 and 2.7.2 respectively. +section~\ref{sec:parameters}. Representations of results of queries if defined in +section~\ref{sec:RESPONSEFORMAT} and section~\ref{sec:votable}. For query languages that produce a single result (e.g. ADQL) executed using the /sync endpoint, the result of a successful query is returned in the response or -the response includes an HTTP redirect (303: See Other) to a resource (uri) from +the response includes an HTTP redirect (303: See Other) to a resource from which the result may be retrieved. An HTTP-GET request to the /sync web resource may return a cached copy of the @@ -313,10 +316,12 @@ \subsection{\{sync\}} HTTP POST. \subsection{\{async\}} +\label{sec:tap-async} + A TAP service must provide a web resource with relative URL /async that is a direct child of the root web resource. This web resource represents controls for asynchronous queries. Specifically, the web resource must represent the job-list -as specified in the UWS standard [3]. +as specified in the UWS standard [std:UWS]. The child web resources of the /async resource are as specified by UWS. These are descendants of the /async web-resource, and they include a web resource that @@ -355,14 +360,14 @@ \subsection{\{async\}} \begin{verbatim} http://example.com/tap/async/42/results/ \end{verbatim} -Failed TAP queries produce an error document (see 2.9 ) which must be accessible +Failed TAP queries produce an error document (see section~\ref{sec:vot-error}) which must be accessible as the error resource, e.g.: \begin{verbatim} http://example.com/tap/async/42/error \end{verbatim} For query languages that produce a single result executed using the /async endpoint, the result of a successful query can be found within the result list -specified by UWS [3]; the result must be named result and thus clients are able +specified by UWS [std:UWS]; the result must be named result and thus clients are able to access it directly, e.g.: \begin{verbatim} http://example.com/tap/async/42/results/result @@ -377,31 +382,35 @@ \subsection{\{async\}} If the query returned no rows, the result resource must exist and contain no data rows. Details on interacting with these resources are specified in the UWS -standard; for examples specific to TAP see Section 5 below. +standard; for examples specific to TAP see section~\ref{sec:examples} below. \subsection{/availability} +\label{sec:vosi-availability} + The VOSI availability metadata should be accessible from a web resource with relative URL /availability that is a direct child of the root web resource. If implemented, the /availability resource must be accessible via the http GET -method. The content is described by [6]. +method. The content is described by [std:VOSI]. Services which do not implement the /availability resource must respond with an HTTP response code of 404 when this resource is accessed. \subsection{/capabilities} +\label{sec:vosi-capabilities} + The TAP-1.0 standard is identified using \begin{verbatim} ivo://ivoa.net/std/TAP \end{verbatim} For TAP-1.1 we define new standard identifiers for each of the -features. Asynchronous query execution is described by standardID: +features. Asynchronous query resources (section~\ref{sec:async}) are described by standardID: \begin{verbatim} ivo://ivoa.net/std/TAP#async-1.1 \end{verbatim} -Synchronous query execution is described by standardID: +Synchronous query resources (section~\ref{sec:sync}) are described by standardID: \begin{verbatim} standardID="ivo://ivoa.net/std/TAP#sync-1.1 @@ -410,7 +419,7 @@ \subsection{/capabilities} In TAP-1.0 the base URL was described with a single standard identifier; in TAP-1.1 and beyond, individual resources are described with their on standardID. This allows service providers to describe multiple resources that -deliver the specified feature (e.g with different authentication methods) in +deliver the specified feature (e.g. with different authentication methods) in the VOSI-capabilities resource. The VOSI standard specifies that the capability metadata is encoded as an XML @@ -497,16 +506,20 @@ \subsection{/capabilities} is described by [8]. \subsection{/tables} +\label{sec:vosi-tables} + The table metadata should be accessible from a web resource with relative URL /tables that is a direct child of the root web resource. The /tables resource -must be accessible via the http GET method. The content is described by [7] and -is equivalent to the metadata from the TAP\underline{' '}SCHEMA described in -XREF. +must be accessible via the http GET method. The content is described by +[std:VODataService] and is equivalent to the metadata from the +TAP\underline{' '}SCHEMA described in section~\ref{sec:tap-schema}. Services which do not implement the /tables resource must respond with an HTTP response code of 404 when this resource is accessed. \subsection{/examples} +\label{sec:dali-examples} + A GET from this endpoint MUST yield a document with a MIME type of either application/xhtml+xml or text/html. A service that does not provide examples MUST return a 404 HTTP status on accessing this resource. @@ -523,7 +536,7 @@ \subsection{/examples} \end{verbatim} -TAP defines two additional properties vocabulary: +TAP defines two additional properties for the examples vocabulary: * query -- each example MUST have a unique child element with simple text content having a property attribute valued query. It contains the query itself, @@ -543,7 +556,9 @@ \subsection{/examples} TODO: add example(s) here -\subsection{Parameters for \{async\} and \{sync\}} +\subsection{Parameters} +\label{sec:parameters} + The \{async\} and \{sync\} web-resources must accept the parameters listed in the following sub-sections. In a synchronous request, the parameters select the representation returned in the response message. In an asynchronous request, the @@ -594,6 +609,8 @@ \subsubsection{REQUEST - remove? } parameter names remain the same in both cases. \subsubsection{LANG} +\label{sec:LANG} + The LANG parameter specifies the query language. The service must support LANG and the client must provide a value with REQUEST=doQuery. The only standard values for the LANG parameter is ADQL (a required language). Support for other @@ -617,10 +634,12 @@ \subsubsection{LANG} capabilities. The client may specify the version of the query language, e.g. LANG=ADQL-2.0 (the syntax should be as shown) or it may omit the version, e.g. LANG=ADQL. The service should return an “unknown query language” error as -described in 2.9 if an unsupported language or an incompatible language version -is specified. +described in section~\ref{sec:vot-error} if an unsupported language or an incompatible +language version is specified. \subsubsection{QUERY} +\label{sec:QUERY} + The QUERY parameter is used to specify the ADQL query. It may also be used to specify the query for other values of LANG (e.g. LANG=) which are not specified in this document but may be described in the @@ -643,8 +662,7 @@ \subsubsection{QUERY} the service supports the REGION function, it must support region encoding in STC-S format (see section 6 ); the extent of STC-S support within the REGION function is left up to the implementation. Coordinate system specification for -POINT, BOX, CIRCLE, and POLYGON must use values from STC-S as described in -section 6 . +POINT, BOX, CIRCLE, and POLYGON must use values from STC-S as described in ???. Note: Although it is allowed by the ADQL syntax, clients should be careful when mixing constants and column references for coordinate system and coordinate @@ -653,11 +671,15 @@ \subsubsection{QUERY} being expressed in that coordinate system. \subsubsection{FORMAT and RESPONSEFORMAT} +\label{sec:RESPONSEFORMAT} + The RESPONSEFORMAT parameter is fully described in [std:DALI]. For backwards compatibility, TAP-1.1 must also accept the FORMAT parameter as equivalent to RESPONSEFORMAT. \subsubsection{MAXREC} +\label{sec:MAXREC} + The MAXREC parameter and its effect on the query result is fully described in [std:DALI]. If the result set is truncated in this fashion, it must include an overflow indicator as specified in section XREF. @@ -679,6 +701,8 @@ \subsubsection{VERSION} The VERSION parameter is fully described in {std:DALI]. \subsubsection{UPLOAD} +\label{sec:UPLOAD} + The UPLOAD parameter is described in [std:DALI]. Services should support the upload of temporary tables (in [std:VOTable] format) via the standard UPLOAD parameter. The table-name(s) must be legal ADQL table names as defined in @@ -725,15 +749,19 @@ \subsubsection{UPLOAD} of URI schemes supported by the service as long as they are assigned unique table names within the query. Services may limit the size and number of uploaded tables; if the service refuses to accept the entire table it must -respond with an error as described in 2.7.3 . +respond with an error as described in section~\ref{sec:vot-error}. \section{Use of VOTable} +\label{sec:votable} + The [std:VOTable] format is the standard format for output (query results) and input (table upload) in a TAP service. \subsection{INFO elements} +\label{sec:vot-info} + The RESOURCE element must contain an INFO element with attribute name="QUERY\underline{' '}STATUS" indicating the success of the operation. For RESOURCE elements that contain a TABLE element, this INFO element must appear @@ -812,16 +840,10 @@ \subsection{INFO elements} Thus, one INFO element with name=”QUERY\underline{' '}STATUS” and value=”OK” or value=”ERROR” must be included before the TABLE. If the TABLE does not contain the entire query result, one INFO element with value=”OVERFLOW” or -value=”ERROR” - must be included after the table. -2.9.2 Version Mismatch Errors - -Errors due to version mismatch from either the VERSION parameter (TAP version) -or specific version used in the LANG parameter (query language version) are -specified using an INFO element with name=”QUERY\underline{' '}STATUS” and -value=”ERROR” as described above. +value=”ERROR” must be included after the table. \subsection{Successful Queries} +\label{sec:query-ok} The result of a query depends on the query language used and may be one or more tables in one or more resources. Unsupportable combinations of query result and @@ -839,8 +861,9 @@ \subsection{Successful Queries} VOTable structure follows the rules in section 2.9 and must be returned with an allowed VOTable MIME type (application/x-votable+xml or text/xml). If the -FORMAT parameter (see 2.3.6 ) of the request specified a specific VOTable MIME -type, the requested MIME type must be used in the HTTP response. +RESPONSEFORMAT parameter (section~\ref{sec:RESPONSEFORMAT}) of the request +specified a specific VOTable MIME type, the requested MIME type must be used +in the HTTP response. CSV formatted data should represent the output table with one row of text per table row, with the table column values rendered as text and separated by @@ -849,15 +872,17 @@ \subsection{Successful Queries} row should give the column name as the data value. CSV data must be returned with a MIME type of text/csv; if the optional header line (with column names) is included, the MIME type must be text/csv;header=present. Full details of CSV -format are defined in RFC 4180 [14]. +format are defined in RFC 4180 [std:CSV]. TSV formatted data should represent the output table with one row of text per table row, with the table column values rendered as text and separated by the TAB character. TSV data must be returned with a MIME type of -text/tab-separated-values [15]. Column values may not contain the TAB +text/tab-separated-values [std:TSV]. Column values may not contain the TAB character. \subsection{Errors} +\label{sec:query-error} + If the service detects an exceptional condition, it must return an error document with an appropriate HTTP-status code. TAP distinguishes three classes of exceptions. @@ -888,6 +913,8 @@ \subsection{Errors} 2.9 specifies the use of VOTable for error documents in TAP services. \subsection{Overflows} +\label{sec:query-overflow} + If a query is executed by a TAP service, the number of rows in the table of results may exceed a limit requested by the user (using the MAXREC parameter) or a limit set by the service implementation (the default or maximum value of @@ -906,6 +933,7 @@ \subsection{Overflows} formats other than VOTable. \subsection{VOTable vs RDBMS Tables and Columns} +\label{sec:votable-rdbms} TODO: describe the bi-directional mapping of VOTable <-> RDBMS table aka the old section on uploading tables... should this come earlier in the doc? @@ -966,6 +994,7 @@ \subsection{VOTable vs RDBMS Tables and Columns} region functions). \section{Metadata: TAP SCHEMA} +\label{sec:tap-schema} There are several approaches to getting metadata for a given TAP service. All TAP services must support a set of tables in a schema named @@ -978,7 +1007,7 @@ \section{Metadata: TAP SCHEMA} TAP\underline{' '}SCHEMA is equivalent to that defined by the VODataService [7]. Second, the client may specify a query of one or more tables setting the MAXREC parameter to 0 so that only the metadata regarding the requested fields -is returned. Use of MAXREC is described in 2.3.7 . +is returned. Use of MAXREC is described in section~\ref{sec:MAXREC}. The TAP\underline{' '}SCHEMA provides access to table, column, and join key metadata through the TAP query mechanisms themselves. Users can discover tables @@ -1003,9 +1032,17 @@ \section{Metadata: TAP SCHEMA} with a timestamp saying when metadata values were was last modified. \subsection{Schemas} +\label{sec:tap-schema-schemas} + The table TAP\underline{' '}SCHEMA.schemas must contain the following columns: -TODO: table +\begin{tabular}{l l l} +\label{tab:resources} +column name & datatype & not-null \\ +schema\underline{' '}name & VARCHAR & true \\ +utype & VARCHAR & false \\ +description & VARCHAR & false \\ +\end{tabular} The schema\underline{' '}name values must be unique and may be qualified by the catalog name or not depending on the implementation requirements. The fully @@ -1014,9 +1051,18 @@ \subsection{Schemas} used directly to construct queries. \subsection{Tables} +\label{sec:tap-schema-tables} The table TAP\underline{' '}SCHEMA.tables must contain the following columns: -TODO: table +\begin{tabular}{l l l} +\label{tab:tap-schema-tables} +column name & datatype & not-null \\ +schema\underline{' '}name & VARCHAR & true \\ +table\underline{' '}name & VARCHAR & true \\ +table\underline{' '}type & VARCHAR & true \\ +utype & VARCHAR & false \\ +description & VARCHAR & false \\ +\end{tabular} The table\underline{' '}name values must be unique. The value of the table\underline{' '}name should be the string that is recommended for use in @@ -1025,18 +1071,33 @@ \subsection{Tables} defined by the ADQL language and follows the pattern [[catalog.]schema.]table. \subsection{Columns} +\label{sec:tap-schema-columns} The table TAP\underline{' '}SCHEMA.columns must contain the following columns: -TODO: table +\begin{tabular}{l l l} +\label{tab:tap-schema-columns} +column name & datatype & not-null \\ +table\underline{' '}name & VARCHAR & true \\ +column\underline{' '}name & VARCHAR & true \\ +datatype & VARCHAR & true \\ +"size" arraysize? datasize? & INTEGER & false \\ +description & VARCHAR & false \\ +utype & VARCHAR & false \\ +unit & VARCHAR & false \\ +ucd & VARCHAR & false \\ +indexed & BOOLEAN? & true \\ +principal & BOOLEAN? & true \\ +std & BOOLEAN? & true \\ +\end{tabular} The table\underline{' '}name,column\underline{' '}name (pair) values must be unique. -Data types and how they map to VOTable datatypes are described in section 2.5 -above. The “size” gives the length of variable length datatypes, for example -varchar(256); this size does not map to the VOTable arraysize attribute when the -latter specifies the size and shape of a multi-dimensional array. To use size in -a query, it must be put in double quotes since it collides with an ADQL reserved +Data types and how they map to VOTable datatypes are described in Section +xref{sec:vot-rdbms} above. The “size” gives the length of variable length datatypes, +for example varchar(256); this size does not map to the VOTable arraysize attribute +when the latter specifies the size and shape of a multi-dimensional array. To use the +size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the DDL for TAP\underline{' '}SCHEMA) use lower case exclusively. In the next major version @@ -1057,10 +1118,19 @@ \subsection{Columns} custom column defined by a particular service. \subsection{Foreign Keys} +\label{sec:tap-schema-keys} The table TAP\underline{' '}SCHEMA.keys must contain the following columns to describe foreign key relations between tables: -TODO: table +\begin{tabular}{l l l} +\label{tab:tap-schema-keys} +column name & datatype & not-null \\ +key\underline{' '}id & VARCHAR & true \\ +from\underline{' '}table & VARCHAR & true \\ +target\underline{' '}table & VARCHAR & true \\ +description & VARCHAR & false \\ +utype & VARCHAR & false \\ +\end{tabular} The key\underline{' '}id values are unique and used only to join with the TAP\underline{' '}SCHEMA.key\underline{' '}columns table below. There may be @@ -1070,7 +1140,13 @@ \subsection{Foreign Keys} The table TAP\underline{' '}SCHEMA.key\underline{' '}columns must contain the following columns to describe the columns that make up a foreign key: -TODO: table +\begin{tabular}{l l l} +\label{tab:tap-schema-key-columns} +column name & datatype & not-null \\ +key\underline{' '}id & VARCHAR & true \\ +from\underline{' '}column & VARCHAR & true \\ +target\underline{' '}column & VARCHAR & true \\ +\end{tabular} There may be one or more rows with a specific key\underline{' '}id to denote single or multi-column keys. @@ -1080,8 +1156,10 @@ \subsection{Foreign Keys} \section{Examples} -The UWS pattern is specified in [3] and its application to TAP in section -XREF. This section gives examples of the exchange of messages between a +\label{sec:examples} + +The UWS pattern is specified in [std:UWS] and its application to TAP in section +section~\ref{sec:async}. This section gives examples of the exchange of messages between a TAP client and service when using UWS to run an asynchronous query. \subsection{Example: Asynchronous Query} From ec99e283ad0337608ad1e158c3126b36b31eebe9 Mon Sep 17 00:00:00 2001 From: Marco Merot Date: Thu, 7 May 2015 08:22:48 +0000 Subject: [PATCH 05/68] TAP-1.1 WD: ref&underscore fix --- TAP.tex | 114 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/TAP.tex b/TAP.tex index f85381c..56624d9 100644 --- a/TAP.tex +++ b/TAP.tex @@ -360,7 +360,7 @@ \subsection{\{async\}} \begin{verbatim} http://example.com/tap/async/42/results/ \end{verbatim} -Failed TAP queries produce an error document (see section~\ref{sec:vot-error}) which must be accessible +Failed TAP queries produce an error document (see section~\ref{sec:query-error}) which must be accessible as the error resource, e.g.: \begin{verbatim} http://example.com/tap/async/42/error @@ -404,13 +404,13 @@ \subsection{/capabilities} \end{verbatim} For TAP-1.1 we define new standard identifiers for each of the -features. Asynchronous query resources (section~\ref{sec:async}) are described by standardID: +features. Asynchronous query resources (section~\ref{sec:tap-async}) are described by standardID: \begin{verbatim} ivo://ivoa.net/std/TAP#async-1.1 \end{verbatim} -Synchronous query resources (section~\ref{sec:sync}) are described by standardID: +Synchronous query resources (section~\ref{sec:tap-sync}) are described by standardID: \begin{verbatim} standardID="ivo://ivoa.net/std/TAP#sync-1.1 @@ -512,7 +512,7 @@ \subsection{/tables} /tables that is a direct child of the root web resource. The /tables resource must be accessible via the http GET method. The content is described by [std:VODataService] and is equivalent to the metadata from the -TAP\underline{' '}SCHEMA described in section~\ref{sec:tap-schema}. +TAP\_SCHEMA described in section~\ref{sec:tap-schema}. Services which do not implement the /tables resource must respond with an HTTP response code of 404 when this resource is accessed. @@ -634,7 +634,7 @@ \subsubsection{LANG} capabilities. The client may specify the version of the query language, e.g. LANG=ADQL-2.0 (the syntax should be as shown) or it may omit the version, e.g. LANG=ADQL. The service should return an “unknown query language” error as -described in section~\ref{sec:vot-error} if an unsupported language or an incompatible +described in section~\ref{sec:query-error} if an unsupported language or an incompatible language version is specified. \subsubsection{QUERY} @@ -690,7 +690,7 @@ \subsubsection{MAXREC} least one row satisfying the query. The service may perform validation and may try to execute the query, in which case a MAXREC=0 request can fail. A query with MAXREC=0 can be used with a simple query (e.g. SELECT * FROM -some\underline{' '}table) to extract and examine the VOTable metadata (assuming +some\_table) to extract and examine the VOTable metadata (assuming FORMAT=votable). Note: in this version of TAP, this is the only mechanism to learn some of the detailed metadata, such as coordinate systems used. @@ -715,11 +715,11 @@ \subsubsection{UPLOAD} The client specifies the name of the uploaded table; this name must be a legal ADQL table name with no catalog or schema (i.e., a string following the regular identifier production of [std:ADQL]). Uploaded tables must be referred -to in queries as TAP\underline{' '}UPLOAD., where is the -specified by the user. Tables in the TAP\underline{' '}UPLOAD schema are +to in queries as TAP\_UPLOAD., where is the +specified by the user. Tables in the TAP\_UPLOAD schema are transient and persist only for the lifetime of the query (although caching might be used behind the scenes) and are never visible in the -TAP\underline{' '}SCHEMA metadata. +TAP\_SCHEMA metadata. The [std:DALI] UPLOAD parameter supports both external resources and in-line content. For external resources, one provides a URI (usually an HTTP URL) the @@ -729,7 +729,7 @@ \subsubsection{UPLOAD} UPLOAD=mytable,http://otherplace.com/path/votable.xml \end{verbatim} The service would retrieve the table from the provided URL and -make it visible to the query as TAP\underline{' '}UPLOAD.mytable. +make it visible to the query as TAP\_UPLOAD.mytable. If the TAP service supports VOSpace (TBD: how to declare this?), one may specify an upload table using a URI to a table stored in a VOSpace, for example: @@ -738,10 +738,10 @@ \subsubsection{UPLOAD} UPLOAD=mytable,vos://space/path/votable.xml \end{verbatim} The service would resolve the URI, contact the VOSpace, retrieve the table, and -make it visible to the query as TAP\underline{' '}UPLOAD.mytable. +make it visible to the query as TAP\_UPLOAD.mytable. UPLOADs are accumulating, i.e., each UPLOAD parameter given will create one or -more tables in TAP\underline{' '}UPLOAD. When the table names from two or more +more tables in TAP\_UPLOAD. When the table names from two or more upload items agree after case folding, the service behaviour is unspecified. Clients thus cannot reliably overwrite uploaded tables; to correct errors, they have to tear down the existing job and create a new one. In principle, any @@ -749,7 +749,7 @@ \subsubsection{UPLOAD} of URI schemes supported by the service as long as they are assigned unique table names within the query. Services may limit the size and number of uploaded tables; if the service refuses to accept the entire table it must -respond with an error as described in section~\ref{sec:vot-error}. +respond with an error as described in section~\ref{sec:query-error}. \section{Use of VOTable} @@ -763,7 +763,7 @@ \subsection{INFO elements} \label{sec:vot-info} The RESOURCE element must contain an INFO element with attribute -name="QUERY\underline{' '}STATUS" indicating the success of the operation. For +name="QUERY\_STATUS" indicating the success of the operation. For RESOURCE elements that contain a TABLE element, this INFO element must appear lexically before the TABLE. The following values are defined for this INFO element's value attribute: @@ -811,7 +811,7 @@ \subsection{INFO elements} If an overflow occurs (result exceeds MAXREC), the service must close the table and append another INFO element to the RESOURCE (after the TABLE) with -name=”QUERY\underline{' '}STATUS” and the value=”OVERFLOW”. +name=”QUERY\_STATUS” and the value=”OVERFLOW”. \begin{verbatim} @@ -825,7 +825,7 @@ \subsection{INFO elements} If an error occurs while writing the rows of the VOTable, the service must close the table and append another INFO element to the RESOURCE, after the -TABLE, with name=”QUERY\underline{' '}STATUS” and the value=”ERROR”. +TABLE, with name=”QUERY\_STATUS” and the value=”ERROR”. \begin{verbatim} @@ -837,7 +837,7 @@ \subsection{INFO elements} The content of these trailing INFO elements is optional and intended for users; client software should not depend on it. -Thus, one INFO element with name=”QUERY\underline{' '}STATUS” and value=”OK” or +Thus, one INFO element with name=”QUERY\_STATUS” and value=”OK” or value=”ERROR” must be included before the TABLE. If the TABLE does not contain the entire query result, one INFO element with value=”OVERFLOW” or value=”ERROR” must be included after the table. @@ -857,7 +857,7 @@ \subsection{Successful Queries} the query) from the query and the datatype, arraysize, and xtype attributes of FIELD elements must be set using the mapping specified in section 2.5 . The xtype attribute in the output must match the datatype for the column in the -TAP\underline{' '}SCHEMA. +TAP\_SCHEMA. VOTable structure follows the rules in section 2.9 and must be returned with an allowed VOTable MIME type (application/x-votable+xml or text/xml). If the @@ -993,28 +993,28 @@ \subsection{VOTable vs RDBMS Tables and Columns} to be parsed and treated as REGIONs (e.g. to be used with some of the ADQL region functions). -\section{Metadata: TAP SCHEMA} +\section{Metadata: TAP\_SCHEMA} \label{sec:tap-schema} There are several approaches to getting metadata for a given TAP service. All TAP services must support a set of tables in a schema named -TAP\underline{' '}SCHEMA that describe the tables and columns included in the -service. In addition to the TAP\underline{' '}SCHEMA, there are two other ways +TAP\_SCHEMA that describe the tables and columns included in the +service. In addition to the TAP\_SCHEMA, there are two other ways to get metadata from a TAP service. First, the VOSI tables resource provides metadata on all tables and columns; this resource is described in 2.2.5 . The -VOSI tables resource provides the same metadata as the TAP\underline{' '}SCHEMA +VOSI tables resource provides the same metadata as the TAP\_SCHEMA but in a rigorously controlled format; the information in the -TAP\underline{' '}SCHEMA is equivalent to that defined by the VODataService +TAP\_SCHEMA is equivalent to that defined by the VODataService [7]. Second, the client may specify a query of one or more tables setting the MAXREC parameter to 0 so that only the metadata regarding the requested fields is returned. Use of MAXREC is described in section~\ref{sec:MAXREC}. -The TAP\underline{' '}SCHEMA provides access to table, column, and join key +The TAP\_SCHEMA provides access to table, column, and join key metadata through the TAP query mechanisms themselves. Users can discover tables or columns that meet their specific criteria by querying the tables described -below. The service may enhance the TAP\underline{' '}SCHEMA with additional +below. The service may enhance the TAP\_SCHEMA with additional metadata where that seems appropriate; since it is self-describing, the -TAP\underline{' '}SCHEMA may be queried to determine if any extended schema +TAP\_SCHEMA may be queried to determine if any extended schema metadata is defined by the service. Services must provide these tables and make them accessible by all supported query mechanisms. @@ -1022,11 +1022,11 @@ \section{Metadata: TAP SCHEMA} defined in section 2.4. The names must be stated in a form that is acceptable as an operand of a query. -All columns in the TAP\underline{' '}SCHEMA tables are of type VARCHAR except +All columns in the TAP\_SCHEMA tables are of type VARCHAR except for size, principal, indexed, and std (in Columns) which are INTEGER values. Implementors are permitted to include additional tables in the -TAP\underline{' '}SCHEMA to describe additional aspects of their service not +TAP\_SCHEMA to describe additional aspects of their service not covered by this specification. Implementors may also include additional columns in the standard tables described below. For example, one could include a column with a timestamp saying when metadata values were was last modified. @@ -1034,17 +1034,17 @@ \section{Metadata: TAP SCHEMA} \subsection{Schemas} \label{sec:tap-schema-schemas} -The table TAP\underline{' '}SCHEMA.schemas must contain the following columns: +The table TAP\_SCHEMA.schemas must contain the following columns: \begin{tabular}{l l l} \label{tab:resources} column name & datatype & not-null \\ -schema\underline{' '}name & VARCHAR & true \\ +schema\_name & VARCHAR & true \\ utype & VARCHAR & false \\ description & VARCHAR & false \\ \end{tabular} -The schema\underline{' '}name values must be unique and may be qualified by the +The schema\_name values must be unique and may be qualified by the catalog name or not depending on the implementation requirements. The fully qualified schema name is defined by the ADQL language and follows the pattern [catalog.]schema. The schema metadata are included for reference and are not @@ -1052,33 +1052,33 @@ \subsection{Schemas} \subsection{Tables} \label{sec:tap-schema-tables} -The table TAP\underline{' '}SCHEMA.tables must contain the following columns: +The table TAP\_SCHEMA.tables must contain the following columns: \begin{tabular}{l l l} \label{tab:tap-schema-tables} column name & datatype & not-null \\ -schema\underline{' '}name & VARCHAR & true \\ -table\underline{' '}name & VARCHAR & true \\ -table\underline{' '}type & VARCHAR & true \\ +schema\_name & VARCHAR & true \\ +table\_name & VARCHAR & true \\ +table\_type & VARCHAR & true \\ utype & VARCHAR & false \\ description & VARCHAR & false \\ \end{tabular} -The table\underline{' '}name values must be unique. The value of the -table\underline{' '}name should be the string that is recommended for use in +The table\_name values must be unique. The value of the +table\_name should be the string that is recommended for use in querying the table; it may or may not be qualified by schema and catalog name(s) depending on the implementation requirements. The fully qualified table name is defined by the ADQL language and follows the pattern [[catalog.]schema.]table. \subsection{Columns} \label{sec:tap-schema-columns} -The table TAP\underline{' '}SCHEMA.columns must contain the following columns: +The table TAP\_SCHEMA.columns must contain the following columns: \begin{tabular}{l l l} \label{tab:tap-schema-columns} column name & datatype & not-null \\ -table\underline{' '}name & VARCHAR & true \\ -column\underline{' '}name & VARCHAR & true \\ +table\_name & VARCHAR & true \\ +column\_name & VARCHAR & true \\ datatype & VARCHAR & true \\ "size" arraysize? datasize? & INTEGER & false \\ description & VARCHAR & false \\ @@ -1090,7 +1090,7 @@ \subsection{Columns} std & BOOLEAN? & true \\ \end{tabular} -The table\underline{' '}name,column\underline{' '}name (pair) values must be +The table\_name,column\_name (pair) values must be unique. Data types and how they map to VOTable datatypes are described in Section @@ -1100,7 +1100,7 @@ \subsection{Columns} size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the DDL for -TAP\underline{' '}SCHEMA) use lower case exclusively. In the next major version +TAP\_SCHEMA) use lower case exclusively. In the next major version of TAP, this column will be called arraysize. The “principal” flag indicates that the column is considered a core part the @@ -1119,47 +1119,47 @@ \subsection{Columns} \subsection{Foreign Keys} \label{sec:tap-schema-keys} -The table TAP\underline{' '}SCHEMA.keys must contain the following columns to +The table TAP\_SCHEMA.keys must contain the following columns to describe foreign key relations between tables: \begin{tabular}{l l l} \label{tab:tap-schema-keys} column name & datatype & not-null \\ -key\underline{' '}id & VARCHAR & true \\ -from\underline{' '}table & VARCHAR & true \\ -target\underline{' '}table & VARCHAR & true \\ +key\_id & VARCHAR & true \\ +from\_table & VARCHAR & true \\ +target\_table & VARCHAR & true \\ description & VARCHAR & false \\ utype & VARCHAR & false \\ \end{tabular} -The key\underline{' '}id values are unique and used only to join with the -TAP\underline{' '}SCHEMA.key\underline{' '}columns table below. There may be -one or more rows with different key\underline{' '}id values and a pair +The key\_id values are unique and used only to join with the +TAP\_SCHEMA.key\_columns table below. There may be +one or more rows with different key\_id values and a pair of tables to denote one or more ways to join the tables. -The table TAP\underline{' '}SCHEMA.key\underline{' '}columns must contain the +The table TAP\_SCHEMA.key\_columns must contain the following columns to describe the columns that make up a foreign key: \begin{tabular}{l l l} \label{tab:tap-schema-key-columns} column name & datatype & not-null \\ -key\underline{' '}id & VARCHAR & true \\ -from\underline{' '}column & VARCHAR & true \\ -target\underline{' '}column & VARCHAR & true \\ +key\_id & VARCHAR & true \\ +from\_column & VARCHAR & true \\ +target\_column & VARCHAR & true \\ \end{tabular} -There may be one or more rows with a specific key\underline{' '}id to +There may be one or more rows with a specific key\_id to denote single or multi-column keys. A TAP service must provide the tables listed above and may provide other tables -in the TAP\underline{' '}SCHEMA namespace. +in the TAP\_SCHEMA namespace. \section{Examples} \label{sec:examples} The UWS pattern is specified in [std:UWS] and its application to TAP in section -section~\ref{sec:async}. This section gives examples of the exchange of messages between a +section~\ref{sec:tap-async}. This section gives examples of the exchange of messages between a TAP client and service when using UWS to run an asynchronous query. \subsection{Example: Asynchronous Query} @@ -1362,7 +1362,7 @@ \subsection{Changes from TAP-1.0} Made clarifications: restricted allowed table names for UPLOAD, clarified that multiple UPLOAD pamaters accumulate, deprecated the size column in -TAP\underline{' '}SCHEMA.columns and added advice to quote it as a delimited +TAP\_SCHEMA.columns and added advice to quote it as a delimited identifier, made presence of a TABLE element on VOTable output only required for successful queries, added optional DALI-examples endpoint (text TBD). From 9f39e9a64f3883976e1c92045d22b1a6256a02f6 Mon Sep 17 00:00:00 2001 From: Marco Merot Date: Tue, 12 May 2015 14:51:32 +0000 Subject: [PATCH 06/68] tap-1.1: changed draft date --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 5f4eaab..b1c4013 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2014-12-15 +DOCDATE = 20155555-05-12 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = WD From 13c90e9da6cb5fb4a993a4c8116187eb076bd344 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 13 Oct 2015 09:11:32 +0000 Subject: [PATCH 07/68] All around: Updated svn:externals to use volute.g-vo.org (rather than google code). From 41c17cbea8e83ae12c081ffd562c5acdd013697c Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 14 Apr 2016 23:25:21 +0000 Subject: [PATCH 08/68] WD-TAP-1.1-20160415: completed table describing mapping of VOTable FIELD metadata and DALI-1.1 xtype values into RDBMS datatypes, made section on resources consistent with DALI-1.1 and clarified the use of anonymous and authenticated access to resources --- Makefile | 2 +- TAP.tex | 694 +++++++++++++++++++++++++++++++------------------------ 2 files changed, 390 insertions(+), 306 deletions(-) diff --git a/Makefile b/Makefile index b1c4013..7173e89 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 20155555-05-12 +DOCDATE = 2016-04-15 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = WD diff --git a/TAP.tex b/TAP.tex index 56624d9..2e5e368 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1,6 +1,9 @@ \documentclass[11pt,letter]{ivoa} \input tthdefs +\usepackage{listings} +\lstloadlanguages{XML} +\lstset{flexiblecolumns=true,basicstyle=\small,tagstyle=\ttfamily} \usepackage[utf8]{inputenc} \title{Table Access Protocol} @@ -22,7 +25,8 @@ Access is provided for both database and table metadata as well as for actual table data. This version of the protocol includes support for multiple query languages, including queries specified using the Astronomical Data Query -Language ([std:ADQL]) within an integrated interface. It also includes support +Language \citep{std:ADQL} within an integrated interface. It also includes +support for both synchronous and asynchronous queries. Special support is provided for spatially indexed queries using the spatial extensions in ADQL. A multi-position query capability permits queries against an arbitrarily large list of @@ -61,7 +65,8 @@ \section{Introduction} return the query response as another table, in accord with the relational model. Queries may be submitted using various query languages and may execute synchronously or asynchronously. Support for the Astronomical Data Query -Language ([std:ADQL]) is mandatory; support for other query languages is supported +Language \citep{std:ADQL} is mandatory; support for other query languages is +supported but optional. The result of a TAP query is another table, normally returned as a VOTable. @@ -100,7 +105,6 @@ \subsection{Role within the VO Architecture} Fig.~section~\ref{fig:archdiag} shows the role this document plays within the IVOA architecture \citep{note:VOARCH}. - \subsection{Motivating Use Cases} Below are some of the more common use cases that have motivated the development of the TAP specification. While this is not complete, it helps to understand the @@ -134,7 +138,7 @@ \subsubsection{Query Standard Data Models} elements are mapped to tables and columns. \subsubsection{ADQL Queries} -The Astronomical Data Query Language ([std:ADQL]) is the standard +The Astronomical Data Query Language \citep{std:ADQL} is the standard query language for the IVOA. Support for ADQL queries is mandatory. ADQL can be used to specify queries that access one or more tables provided by the TAP service, including the standard metadata tables. In general, the client must @@ -169,95 +173,6 @@ \subsubsection{Synchronous Queries} queries are a good approach as long as the service can stream the output and consume modest internal resources. - -\subsection{Interface Overview -- move to examples section?} -Table Access Protocol (TAP) is implemented over the HTTP protocol using standard -HTTP GET and POST requests and conventions. A TAP request specifies one or more -parameter key/value pairs; both keys and values are strings. The keys used are -discussed in this specification and in the specifications for query languages -supported by a service. The values may need to be encoded, using standard -URL-encoding. For the following examples, http://example.com/tap/ is the base -URL for a TAP service. - -This is an example of a synchronous ADQL query on r magnitude: - -\begin{verbatim} -HTTP POST htp://example.com/tap/sync -REQUEST=doQuery -LANG=ADQL -QUERY=SELECT * FROM magnitudes as m where m.r>=10 and m.r<=16 -\end{verbatim} - -Synchronous queries return the table of results in the HTTP response to the -initial request. In the examples above, the output format defaults to VOTable; -the FORMAT parameter could be added to select a different format. - -Asynchronous queries are created in the same way as the synchronous kind, using -the /async endpoint: - -\begin{verbatim} -HTTP POST http://example.com/tap/async -REQUEST=doQuery -LANG=ADQL -QUERY=SELECT * FROM magnitudes AS m WHERE m.r>=10 AND m.r<=16 -\end{verbatim} - -The service's response to these requests is a URL representing the query's -state and progress and where the state may be monitored and controlled. The -query -result or an error document can then be retrieved from a URL associated with the -job. This is an application of the UWS pattern. The query is then executed -with a separate request to run the job URL: - -\begin{verbatim} -HTTP POST http://example.com/tap/async//phase -PHASE=RUN -\end{verbatim} - -The state of the job can be retrieved from the phase resource: - -\begin{verbatim} -HTTP GET http://example.com/tap/async//phase -\end{verbatim} - -The client may have to check the phase multiple times until the job -finishes. Once the returned value is COMPLETED, the results can be obtained -from the results resource: - -\begin{verbatim} -HTTP GET http://example.com/tap/async//results/result -\end{verbatim} - -In addition to the sync and async resources for query execution, a TAP service -also has metadata resources defined by the VOSI standard. The availability of a -service can be monitored by accessing: - -\begin{verbatim} -HTTP GET http://example.com/tap/availability -\end{verbatim} - -The complete table metadata can be obtained: - -\begin{verbatim} -HTTP GET http://example.com/tap/tables -\end{verbatim} - -The capabilities can be obtained by: - -\begin{verbatim} -HTTP GET http://example.com/tap/capabilities -\end{verbatim} - -The capabilities are also accessible via a service request to the synchronous -query resource: - -\begin{verbatim} -HTTP GET http://example.com/tap/sync?REQUEST=getCapabilities -\end{verbatim} - -This output lists support for optional TAP functionality and additional -implemented interfaces. - \section{Resources} \label{sec:resources} @@ -267,25 +182,32 @@ \section{Resources} \begin{tabular}{l l l l l} \label{tab:resources} resource type & resource name & required \\ -{sync} & /sync & must (anonymous) & \\ -{async} & /async & must (anonymous) & \\ -{sync} & service-specific & may (alternate authentication method) & \\ -{async} & service-specific & may (alternate authentication method) & \\ -VOSI-availability & /availability & should & \\ +{sync} & /sync & must & \\ +{async} & /async & must & \\ +{sync} & service specific & may (alternate authentication method) & \\ +{async} & service specific & may (alternate authentication method) & \\ +VOSI-availability & service specific & must & \\ +VOSI-availability & service specific & may (alternate authentication method) & \\ VOSI-capabilities & /capabilities & must & \\ +VOSI-capabilities & service specific & may (alternate authentication method) & \\ VOSI-tables & /tables & should & \\ +VOSI-tables & service specific & may (alternate authentication method) & \\ DALI-examples & /examples & should & \\ +DALI-examples & service specific & may (alternate authentication method) & \\ \end{tabular} At least one set of {sync} and {async} resources must be named /sync and /async respectively for backwards compatibility with TAP-1.0 (which required -these names. These resources must be used for anonymous query execution. Other -{sync} and {async} resources may have service specific names, but all resources -listed above must be siblings so that a client with one such URL can find the -VOSI-capabilities URL and thus discover other available resources. +these names. Other {sync} and {async} resources may have service specific names. +As required by \citep{std:DALI}, all resources except the VOSI-availability must +be siblings of the VOSI-capabilities resource. -A TAP service must be represented as a set of sibling web resources each -addressable via a URL in the http scheme, or the https scheme, or both. +If a TAP service allows anonymous access, the fixed name resources and VOSI-availability +must be used for anonymous access; other resource names may be used for authenticated access. +If the entire service requires authentication then the fixed names may be used for +authenticated access. [Note: There is probably no use for authenticated VOSI-availability, +VOSI-capabilities, or DALI-examples resources when anonymous is allowed so those options +are not precent in the table above... should they be for completeness?] The web resource at the root of the tree must represent the service as a whole. This specification defines no standard representation for this root resource. @@ -297,9 +219,9 @@ \section{Resources} \subsection{\{sync\}} \label{sec:tap-sync} -A TAP service must provide a web resource with relative URL /sync that is a -direct child of the root web resource. This web resource represents the results -of synchronous requests. The exact form of the query, and hence the +A TAP service must provide one or more web resources that represents the results +of synchronous query execution. The {sync} resources must conform to the general rules for +DALI-sync \citep{std:DALI} resources. The exact form of the query, and hence the representation of the resource, is defined by the query parameters as listed in section~\ref{sec:parameters}. Representations of results of queries if defined in section~\ref{sec:RESPONSEFORMAT} and section~\ref{sec:votable}. @@ -318,10 +240,10 @@ \subsection{\{sync\}} \subsection{\{async\}} \label{sec:tap-async} -A TAP service must provide a web resource with relative URL /async that is a -direct child of the root web resource. This web resource represents controls for -asynchronous queries. Specifically, the web resource must represent the job-list -as specified in the UWS standard [std:UWS]. +A TAP service must provide one or more web resource representing controls for +asynchronous queries. Specifically, the web resource must conform to the general rules +for DALI-async \citep{std:DALI} resources and thus represent a job-list +as specified in \citep{std:UWS}. The child web resources of the /async resource are as specified by UWS. These are descendants of the /async web-resource, and they include a web resource that @@ -341,7 +263,8 @@ \subsection{\{async\}} \begin{verbatim} http://example.com/tap/async/42 \end{verbatim} -where 42 is the job identifier. A client making an asynchronous request must use +where 42 is an example job identifier. A client making an asynchronous request +must use the UWS facilities to monitor or control the job. In addition to the job list and job resource above, UWS specifies the name and semantics of the a small set of child resources used to view and control the job, e.g.: @@ -367,8 +290,8 @@ \subsection{\{async\}} \end{verbatim} For query languages that produce a single result executed using the /async endpoint, the result of a successful query can be found within the result list -specified by UWS [std:UWS]; the result must be named result and thus clients are able -to access it directly, e.g.: +specified by UWS; the result must be named result and thus +clients are able to access it directly, e.g.: \begin{verbatim} http://example.com/tap/async/42/results/result \end{verbatim} @@ -378,22 +301,16 @@ \subsection{\{async\}} For query languages that may produce multiple result resources, the names of the results are not specified (they may be specified in the specification for the language). The client can always access the result list resource as specified by -UWS [3]. +UWS. If the query returned no rows, the result resource must exist and contain no data rows. Details on interacting with these resources are specified in the UWS standard; for examples specific to TAP see section~\ref{sec:examples} below. -\subsection{/availability} +\subsection{availability} \label{sec:vosi-availability} -The VOSI availability metadata should be accessible from a web resource with -relative URL /availability that is a direct child of the root web resource. If -implemented, the /availability resource must be accessible via the http GET -method. The content is described by [std:VOSI]. - -Services which do not implement the /availability resource must respond with an -HTTP response code of 404 when this resource is accessed. +The use of the VOSI-availability resource is described in \citep{std:DALI}. \subsection{/capabilities} \label{sec:vosi-capabilities} @@ -413,45 +330,22 @@ \subsection{/capabilities} Synchronous query resources (section~\ref{sec:tap-sync}) are described by standardID: \begin{verbatim} -standardID="ivo://ivoa.net/std/TAP#sync-1.1 +ivo://ivoa.net/std/TAP#sync-1.1 \end{verbatim} In TAP-1.0 the base URL was described with a single standard identifier; in -TAP-1.1 and beyond, individual resources are described with their on +TAP-1.1 and beyond, individual resources are described with their own standardID. This allows service providers to describe multiple resources that deliver the specified feature (e.g. with different authentication methods) in the VOSI-capabilities resource. -The VOSI standard specifies that the capability metadata is encoded as an XML -document which lists each of the service's capabilities as a -element. The type of this element (which defines the contents) is -{http://www.ivoa.net/xml/VOResource/v1.0}Capability from the VOResource XML -standard [8]. +The use of the VOSI-capabilities resource is described in \citep{std:DALI}. -In addition, the capabilities output must also comply with the following -requirements: - -* the returned document must include elements -that describes the service's support for the TAP protocol using the TAP and -VOSI standardID values - -* this capability element must include at least one element -with its "role" attribute set to "std", - -Note: VO registries recognize a service's support for a standard protocol -through this capability description. In particular, a different standard -Capability sub-type is used for each standard protocol to provide capability -metadata that is specific to that protocol. At the time of this writing, a -Capability sub-type for TAP has not yet been defined. Thus for compliance with -this standard, any legal Capability description that meets the above -restrictions is sufficient. However, once a VOResource extension for TAP is -standardized, it is strongly recommended that TAP services emit its -capabilities using that the Capability sub-type specialized for TAP. For example, the returned capabilities document for a service supporting TAP might look as follows: -\begin{verbatim} +\begin{lstlisting}[language=XML] + + + http://example.net/myTAP + + + https://example.net/myTAP + + + + + - - http://myarchive.net/myTAP/async + + http://example.net/myTAP/async + + + http://example.net/myTAP/auth-async + + + + https://example.net/myTAP/async + - - http://myarchive.net/myTAP/sync + + http://example.net/myTAP/sync + + + http://example.net/myTAP/auth-sync + + + + https://example.net/myTAP/sync + - http://myarchive.net/myTAP/capabilities + http://example.net/myTAP/capabilities - http://myarchive.net/myTAP/availability + http://example.net/myTAP/availability - - http://myarchive.net/myTAP/tables + http://myarchive.net/myTAP/tables + + + https://myarchive.net/myTAP/tables + + + + http://myarchive.net/myTAP/auth-tables + -\end{verbatim} +\end{lstlisting} The service capabilities must be accessible from a web resource with relative URL /capabilities that is a direct child of the root web resource. The @@ -511,7 +439,7 @@ \subsection{/tables} The table metadata should be accessible from a web resource with relative URL /tables that is a direct child of the root web resource. The /tables resource must be accessible via the http GET method. The content is described by -[std:VODataService] and is equivalent to the metadata from the +\citep{std:VODS11} and is equivalent to the metadata from the TAP\_SCHEMA described in section~\ref{sec:tap-schema}. Services which do not implement the /tables resource must respond with an HTTP @@ -526,15 +454,15 @@ \subsection{/examples} If present, the endpoint must be represented in a capability in the TAP service's registry record. The capability's standardID is defined by -[std:DALI]. A capability element could hence look like this: +\citep{std:DALI}. A capability element could hence look like this: -\begin{verbatim} - - - http://myarchive.net/myTAP/examples - - -\end{verbatim} +\begin{lstlisting}[language=XML] + + + http://myarchive.net/myTAP/examples + + +\end{lstlisting} TAP defines two additional properties for the examples vocabulary: @@ -554,8 +482,6 @@ \subsection{/examples} attribute, as otherwise RDFa clients would interpret the embedded link rather than the element content as the object in the triple. -TODO: add example(s) here - \subsection{Parameters} \label{sec:parameters} @@ -579,35 +505,6 @@ \subsection{Parameters} service must ignore the spurious parameter, must respond to the request normally and must not report errors concerning the spurious parameter. -\subsubsection{REQUEST - remove? } -This parameter distinguishes current service operations, makes it possible to -extend the service specification (with additional or custom operations), and -specifies how other parameters should be interpreted. If a TAP service attempts -to execute a TAP request without this parameter or with an incorrect value for -this parameter, then the service must reject the request and return an error -document as the result. - -These are the standard values of the parameter: - -doQuery: execute a query - -getCapabilities: return VOSI-capabilities metadata - -All requests to execute a query using a query language must -include REQUEST=doQuery and must include the LANG parameter. For other values of -REQUEST, additional parameters may or may not be required. The -REQUEST=getCapabilities service operation must be supported for synchronous -(/sync) requests and is not defined for asynchronous (/async) requests. - -For synchronous queries, the HTTP request must also include additional -parameters (see below) with the details of the query. These are used for -metadata queries and data queries. - -For asynchronous queries, the additional parameters may be included with the -HTTP request that creates the query (the UWS job) or they may be POSTed directly -to the created job resource, in one or more separate HTTP requests. The -parameter names remain the same in both cases. - \subsubsection{LANG} \label{sec:LANG} @@ -619,13 +516,11 @@ \subsubsection{LANG} For example, an ADQL query would be performed with \begin{verbatim} -REQUEST=doQuery LANG=ADQL QUERY= \end{verbatim} A PQL query would be performed with \begin{verbatim} -REQUEST=doQuery LANG=PQL \end{verbatim} @@ -652,7 +547,9 @@ \subsubsection{QUERY} function names, and other ADQL keywords are not case sensitive. Within the ADQL query, the service must support the use of timestamp values as -described in [std:DALI]. +described in \citep{std:DALI}. + +TAP-1.0 text about ADQL region functions: If the tables that are queried through a service contain columns with spatial coordinates and the service supports spatial querying via the ADQL “region” @@ -664,6 +561,13 @@ \subsubsection{QUERY} function is left up to the implementation. Coordinate system specification for POINT, BOX, CIRCLE, and POLYGON must use values from STC-S as described in ???. +Proposed TAP-1.1 text: + +INTERSECTS and CONTAINS are required. POINT, CIRCLE, and POLYGON are required. +POINT (and point-valued columns) cannot be used as an argument to INTERSECTS. +AREA, CENTROID, COORDSYS, COORD1, and COORD2 are optional. REGION is not +supported (and hopefully gone from ADQL-2.1). + Note: Although it is allowed by the ADQL syntax, clients should be careful when mixing constants and column references for coordinate system and coordinate values. For example, POINT('ICRS', t.ra, t.dec) does not cause t.ra and t.dec to @@ -673,7 +577,8 @@ \subsubsection{QUERY} \subsubsection{FORMAT and RESPONSEFORMAT} \label{sec:RESPONSEFORMAT} -The RESPONSEFORMAT parameter is fully described in [std:DALI]. For backwards +The RESPONSEFORMAT parameter is fully described in \citep{std:DALI}. For +backwards compatibility, TAP-1.1 must also accept the FORMAT parameter as equivalent to RESPONSEFORMAT. @@ -681,8 +586,8 @@ \subsubsection{MAXREC} \label{sec:MAXREC} The MAXREC parameter and its effect on the query result is fully described in -[std:DALI]. If the result set is truncated in this fashion, it must include an -overflow indicator as specified in section XREF. +\citep{std:DALI}. If the result set is truncated in this fashion, it must +include an overflow indicator as specified in section~\ref{sec:query-overflow}. For the special value of MAXREC=0, the service is not required to execute the query; a successful MAXREC=0 request does not necessarily mean that the query @@ -694,19 +599,34 @@ \subsubsection{MAXREC} FORMAT=votable). Note: in this version of TAP, this is the only mechanism to learn some of the detailed metadata, such as coordinate systems used. -\subsubsection{RUNID} -The RUNID parameter is fully described in [std:DALI]. +The output truncation caused by the MAXREC parameter occurs after any +limitations imposed by the query and the overflow indicator is only added if +the query result is actually truncated. For example: + +\begin{verbatim} +MAXREC=A +QUERY=select TOP B * from foo +\end{verbatim} + +for integer values A and B. Assuming the table contains many rows, if A > B +then the result table will contain B rows and no overflow indicator. If A < B +then the result table will contain A rows and an overflow indicator. If the +table contains A or fewer rows then the result will not contain an overflow +indicator. -\subsubsection{VERSION} -The VERSION parameter is fully described in {std:DALI]. +\subsubsection{RUNID} +The RUNID parameter is fully described in \citep{std:DALI}. \subsubsection{UPLOAD} \label{sec:UPLOAD} -The UPLOAD parameter is described in [std:DALI]. Services should support the -upload of temporary tables (in [std:VOTable] format) via the standard UPLOAD +The UPLOAD parameter is described in \citep{std:DALI}. Services should support +the +upload of temporary tables (in \citep{std:VOTable} format) via the standard +UPLOAD parameter. The table-name(s) must be legal ADQL table names as defined in -[std:ADQL] but restricted as described below XREF. URIs maybe be simple URLs +\citep{std:ADQL} but restricted as described below XREF. URIs maybe be simple +URLs (e.g. with a URI scheme of http) or URIs (e.g. with a URI scheme of vos or param) that must be resolved to give the location of the table content. See section XREF for details. @@ -714,14 +634,16 @@ \subsubsection{UPLOAD} If table upload supported, the service must accept tables in VOTable format. The client specifies the name of the uploaded table; this name must be a legal ADQL table name with no catalog or schema (i.e., a string following the -regular identifier production of [std:ADQL]). Uploaded tables must be referred +regular identifier production of \citep{std:ADQL}). Uploaded tables must be +referred to in queries as TAP\_UPLOAD., where is the specified by the user. Tables in the TAP\_UPLOAD schema are transient and persist only for the lifetime of the query (although caching might be used behind the scenes) and are never visible in the TAP\_SCHEMA metadata. -The [std:DALI] UPLOAD parameter supports both external resources and in-line +The \citep{std:DALI} UPLOAD parameter supports both external resources and +in-line content. For external resources, one provides a URI (usually an HTTP URL) the TAP service can use to obtain the table content. For example, \begin{verbatim} @@ -755,9 +677,10 @@ \subsubsection{UPLOAD} \section{Use of VOTable} \label{sec:votable} -The [std:VOTable] format is the standard format for output (query results) and -input (table upload) in a TAP service. - +The \citep{std:VOTable} format is the standard format for output (query +results) and input (table upload) in a TAP service so most of this section +deals with how VOTable is used. However, rules about serialising column values +also apply to other formats (e.g. CSV and TSV). \subsection{INFO elements} \label{sec:vot-info} @@ -872,12 +795,13 @@ \subsection{Successful Queries} row should give the column name as the data value. CSV data must be returned with a MIME type of text/csv; if the optional header line (with column names) is included, the MIME type must be text/csv;header=present. Full details of CSV -format are defined in RFC 4180 [std:CSV]. +format are defined in \citep{std:CSV}. TSV formatted data should represent the output table with one row of text per table row, with the table column values rendered as text and separated by the TAB character. TSV data must be returned with a MIME type of -text/tab-separated-values [std:TSV]. Column values may not contain the TAB +text/tab-separated-values \citep{std:TSV}. Column values may not contain the +TAB character. \subsection{Errors} @@ -932,37 +856,95 @@ \subsection{Overflows} the overflow is reported. No method of reporting an overflow is defined for formats other than VOTable. -\subsection{VOTable vs RDBMS Tables and Columns} -\label{sec:votable-rdbms} +\subsection{Mapping Table Datatypes} +\label{sec:vot-rdbms} + +This section describes the bi-directional mapping between VOTable and RDBMS + +geometric datatypes and extends the basic rules for serialising such values in +VOTable described in \citep{std:DALI}. These rules apply to input tables +supplied via an UPLOAD parameter (see ??) and to result tables after successful +query execution. + +For input tables, the name attribute of the FIELD element is used as the column +name. This name must be a legal ADQL column name (i.e., a string following the +regular identifier production of \citep{std:ADQL}). For result tables, the +column name or an alias specified in the query is used to set the name attribute +of the FIELD elements in the output table (the alias oevrrides the normal +column name). -TODO: describe the bi-directional mapping of VOTable <-> RDBMS table aka the -old section on uploading tables... should this come earlier in the doc? +NOTE: output column names from aliases may not be valid input +column names because users can put what they like in quotes... can we +or ADQL restrict the definition of a valid alias? -The column names in the transient database table are taken directly from the -name attribute of the VOTable FIELD and PARAM elements. TODO: add column name -restrictions here to avoid quoted identifiers. The datatypes of the -transient table are determined from the FIELD and PARAM attributes as follows: +NOTE2: if the select has a +fully-qualified column name (tab.col or alias.col) is that the output FIELD +name? Those are always going to be invalid input names and here users would +have to use aliases to make them valid for later input... is the goal that all +result tables would be valid input tables? Can we achieve that? -TODO: something like the table from TAP-1.0 +The mapping between VOTable datatype, arraysize, and type attributes and +RDBMS datatypes are as follows: + +\begin{tabular}{l l l l l} +\label{tab:vot-rdbms-mapping} +datatype & arraysize & xtype & RDBMS datatype & required \\ +char & [1] & & CHAR or CHAR(1) & yes \\ +char & * & & VARCHAR & yes \\ +char & n & & CHAR(n) & yes \\ +char & n* & & VARCHAR(n) & yes \\ +char & n, *, n* & CLOB & CLOB & yes \\ +unsignedByte & [1] & & BINARY(1) & yes \\ +unsignedByte & * & & VARBINARY(*) & yes \\ +unsignedByte & n & & BINARY(n) & yes \\ +unsignedByte & n* & & VARBINARY(n) & yes \\ +unsignedByte & n, *, n* & BLOB & BLOB & yes \\ +short & [1] & & SMALLINT? & yes \\ +short & * & & implementation-specific & no \\ +short & n & & implementation-specific & no \\ +short & n* & & implementation-specific & no \\ +int & [1] & & INTEGER & yes \\ +int & * & & implementation-specific & no \\ +int & n & & implementation-specific & no \\ +int & n* & & implementation-specific & no \\ +long & [1] & & BIGINT & yes \\ +long & * & & implementation-specific & no \\ +long & n & & implementation-specific & no \\ +long & n* & & implementation-specific & no \\ +float & [1] & & REAL & yes \\ +float & * & & implementation-specific & no \\ +float & n & & implementation-specific & no \\ +float & n* & & implementation-specific & no \\ +double & [1] & & DOUBLE [PRECISION] & yes \\ +double & * & & implementation-specific & no \\ +double & n & & implementation-specific & no \\ +double & n* & & implementation-specific & no \\ +char & n or n* & timestamp & timestamp & yes \\ +double & 2 & point & implementation-specific & no \\ +double & 3 & circle & implementation-specific & no \\ +double & * & polygon & implementation-specific & no \\ +float & 2 & point & implementation-specific & no \\ +float & 3 & circle & implementation-specific & no \\ +float & * & polygon & implementation-specific & no \\ +short & 2 & interval & implementation-specific & no \\ +int & 2 & interval & implementation-specific & no \\ +long & 2 & interval & implementation-specific & no \\ +float & 2 & interval & implementation-specific & no \\ +double & 2 & interval & implementation-specific & no \\ +\end{tabular} The default mapping of data types are shown above (no arraysize or xtype). If the xtype attribute is set, this is the preferred internal datatype. If xtype is not set, then the datatype and arraysize indicate the most suitable internal -datatype. Note that the last column of Table (x) is not normative. +datatype. Note that the RDBMS type i +s not normative. Implementations SHOULD try to make sure that the actual types chosen are at least signature-compatible with the recommended types (i.e., integers should remain integers, floating-point values floating-point values, etc.), such that clients can reliably write queries against uploaded tables. -For columns with xtype adql:REGION, this is particularly critical, since -databases typically use different types to represent various STC-S objects. -Clients are advised to assume that such columns will be approximated with -polygons in the actual database table. - In the arraysize column above, [1] means the arraysize is not set or is set to 1, n means arraysize is set to a specific value, * means arraysize=”*”, and n* -means arraysize=”n*” (variable size up to length n). A blank means the arraysize -is not set. +means arraysize=”n*” (variable size up to length n). Binary values (unsignedByte in VOTable, BINARY, VARBINARY, or BLOB in ADQL) can be expressed as specified by the VOTable standard. By default, VOTable allows @@ -974,24 +956,21 @@ \subsection{VOTable vs RDBMS Tables and Columns} Services may use these types to indicate that columns may only be selected. For example, if service implementors want to make URL(s) available as column values in the results, but do not actually store the URL(s) in the database, they would -specify a column with xtype=”adql:CLOB” and the column with URL(s) could be +specify a column with xtype=”CLOB” and the column with URL(s) could be referenced in the SELECT clause of a query, but could not be used in the WHERE clause. The service could then process the query result and insert the URL(s) or, more likely, transform a column value (an identifier) into a URL while writing the results. -TIMESTAMP values are specified as described in [std:DALI]. The -xtype=”adql:TIMESTAMP” attribute must be specified in an uploaded VOTable in +TIMESTAMP values are specified as described in \citep{std:DALI}. The +xtype=timestamp attribute must be specified in an uploaded VOTable in order for the values to be inserted in a column of type TIMESTAMP; without the xtype, the values would be inserted into a CHAR(n) or VARCHAR column. -POINT and REGION values are specified in STC-S format (see section 6 ). The -xtype=”adql:POINT” attribute must be specified in an uploaded VOTable in order -for the char values to be parsed and treated as POINTs (e.g. to be used with -some of the ADQL region functions). For regions, the xtype=”adql:REGION” -attribute must be specified in an uploaded VOTable in order for the char values -to be parsed and treated as REGIONs (e.g. to be used with some of the ADQL -region functions). +POINT, CIRCLE, and POLYGON values are specified as arrays of double values as +described in \citep{std:DALI}. The xtype attribute must be specified in +an uploaded VOTable in order for the array values to be parsed and treated as +geometric values and thus to be used with some of the ADQL features. \section{Metadata: TAP\_SCHEMA} \label{sec:tap-schema} @@ -1001,11 +980,13 @@ \section{Metadata: TAP\_SCHEMA} TAP\_SCHEMA that describe the tables and columns included in the service. In addition to the TAP\_SCHEMA, there are two other ways to get metadata from a TAP service. First, the VOSI tables resource provides -metadata on all tables and columns; this resource is described in 2.2.5 . The +metadata on all tables and columns; this resource is described in +(section~\ref{sec:vosi-tables}). The VOSI tables resource provides the same metadata as the TAP\_SCHEMA but in a rigorously controlled format; the information in the TAP\_SCHEMA is equivalent to that defined by the VODataService -[7]. Second, the client may specify a query of one or more tables setting the +\citep{std:VODS11}. Second, the client may specify a query of one or more +tables setting the MAXREC parameter to 0 so that only the metadata regarding the requested fields is returned. Use of MAXREC is described in section~\ref{sec:MAXREC}. @@ -1062,6 +1043,7 @@ \subsection{Tables} table\_type & VARCHAR & true \\ utype & VARCHAR & false \\ description & VARCHAR & false \\ +table\_index & INTEGER & false \\ \end{tabular} The table\_name values must be unique. The value of the @@ -1069,6 +1051,12 @@ \subsection{Tables} querying the table; it may or may not be qualified by schema and catalog name(s) depending on the implementation requirements. The fully qualified table name is defined by the ADQL language and follows the pattern [[catalog.]schema.]table. +If the table name is such that the name must be quoted (quoted identifier in +\citep{std:ADQL}) then the value must include the quotes. + +The table\_index is used to recommended table ordering for clients. Clients +may order by table\_index (ascending) so lower index tables would appear +earlier in a listing. \subsection{Columns} \label{sec:tap-schema-columns} @@ -1080,7 +1068,8 @@ \subsection{Columns} table\_name & VARCHAR & true \\ column\_name & VARCHAR & true \\ datatype & VARCHAR & true \\ -"size" arraysize? datasize? & INTEGER & false \\ +arraysize & INTEGER & false \\ +"size" & INTEGER & false \\ description & VARCHAR & false \\ utype & VARCHAR & false \\ unit & VARCHAR & false \\ @@ -1088,27 +1077,32 @@ \subsection{Columns} indexed & BOOLEAN? & true \\ principal & BOOLEAN? & true \\ std & BOOLEAN? & true \\ +column\_index & false \\ \end{tabular} The table\_name,column\_name (pair) values must be unique. Data types and how they map to VOTable datatypes are described in Section -xref{sec:vot-rdbms} above. The “size” gives the length of variable length datatypes, -for example varchar(256); this size does not map to the VOTable arraysize attribute -when the latter specifies the size and shape of a multi-dimensional array. To use the +xref{sec:vot-rdbms} above. The arraysize column gives the length of variable +length datatypes, +for example varchar(256); this arraysize does not map exactly to the VOTable +arraysize attribute because +the latter can specify the size and shape of a multi-dimensional array as well +as the variable size. The "size" column is retained for backwards compatiblity +to TAP-1.0 and must contain the same value as arrayaize. To use the size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the DDL for TAP\_SCHEMA) use lower case exclusively. In the next major version -of TAP, this column will be called arraysize. +of TAP, the "size" column will be removed. The “principal” flag indicates that the column is considered a core part the content; clients can use this hint to make the principal column(s) visible, for example by selecting them by default in generating an ADQL query. In cases where -the services selects the columns to return (such as PQL without a SELECT -parameter), the principal column indicates those columns that are returned by -default. +the services selects the columns to return (such as a query language without an +explicit output selection), the principal column indicates those columns that +are returned by default. The “indexed” flag indicates that the column is indexed, potentially making queries run much faster if this column is used in a constraint. @@ -1117,6 +1111,11 @@ \subsection{Columns} to indicate that a given column is defined by some standard, as opposed to a custom column defined by a particular service. +The column\_index is used to recommended column ordering for clients. Clients +may order by column\_index (ascending) so lower index columns would appear +earlier in a listing. This is useful for keeping related columns together in +output or display. + \subsection{Foreign Keys} \label{sec:tap-schema-keys} The table TAP\_SCHEMA.keys must contain the following columns to @@ -1158,7 +1157,8 @@ \subsection{Foreign Keys} \section{Examples} \label{sec:examples} -The UWS pattern is specified in [std:UWS] and its application to TAP in section +The UWS pattern is specified in \citep{std:UWS} and its application to TAP in +section section~\ref{sec:tap-async}. This section gives examples of the exchange of messages between a TAP client and service when using UWS to run an asynchronous query. @@ -1168,27 +1168,85 @@ \subsection{Example: Asynchronous Query} anonymous queries). This URL points to the list of 'jobs'; i.e. the list of queries currently or recently executed. -\subsubsection{Creating a Query} +\subsubsection{Creating and Executing a Simple Query} + +Asynchronous queries are created in the same way as synchronous, using +one of the {async} endpoints, for example: + +\begin{verbatim} +HTTP POST http://example.com/tap/async +LANG=ADQL +QUERY=SELECT * FROM magnitudes AS m WHERE m.r>=10 AND m.r<=16 +\end{verbatim} + +The service's response to this request is an HTTP redirect with a URL fo the +query job: + +\begin{verbatim} +HTTP status 303 'See other' +Location: http://example.com/tap/async/42 +\end{verbatim} + +The query result or an error document can then be retrieved from a URL +associated with the job. This is an application of the UWS pattern. The query is +then executed with a separate request to run the job URL: + +\begin{verbatim} +HTTP POST http://example.com/tap/async/42/phase +PHASE=RUN +\end{verbatim} + +The state of the job can be retrieved from the phase resource: + +\begin{verbatim} +HTTP GET http://example.com/tap/async/42/phase +\end{verbatim} + +The client may have to check the phase multiple times until the job +finishes. Once the returned value is COMPLETED, the results can be obtained +from the results resource: + +\begin{verbatim} +HTTP GET http://example.com/tap/async/42/results/result +\end{verbatim} + +\subsubsection{Modify a Query Job Before Execution} To create a new query, the client POSTs a request to the job list: \begin{verbatim} HTTP POST http://example.com/tap/async -REQUEST=doQuery LANG=ADQL -QUERY=SELECT TOP 100 * FROM foo \end{verbatim} -The service then creates a job and assigns that job a name and a URL based on -the name. Suppose that the name is 42, then the URL will be -http://example.com/tap/async/42 because the jobs are always children of the job -list. While the job is in the PENDING phase, additional parameters may be -specified by additional POSTs to the job resource, for example: +The response with the job URL: \begin{verbatim} -HTTP POST http://example.com/tap/async/42 +HTTP status 303 'See other' +Location: http://example.com/tap/async/42 +\end{verbatim} + +While the job is in the PENDING phase, the job parameters may be modified +by additional POST(s) to the parameters resource (see +\citep{std:DALI}), for example: + +\begin{verbatim} +HTTP POST http://example.com/tap/async/42/parameters UPLOAD=mytable,http://a.b.c/mytable.xml +QUERY=select * from TAP_UPLOAD.mytable t join magnitudes m on t.target = +m.target \end{verbatim} +Here we have specified with the UPLOAD parameter that the service create a +temporary table named mytable with content from the VOTable at the specified +URL. The QUERY parameter can then reference the uploaded table with the +specified name (but in the TAP\_UPLOAD schema). + +Parameter-value pairs accumulate when POSTed to the parameters resource, so an +additional POST of the UPLOAD parameter in this example would add another +parameter-value pair (essentially a multi-valued parameter as described in +\citep{std:DALI}). There is no mechanism to replace or remove a parameter in a +PENDING job. + After each such POST, the service issues an HTTP redirection to the job's URL, where the modified state may be accessed: @@ -1197,8 +1255,9 @@ \subsubsection{Creating a Query} Location: http://example.com/tap/async/42 \end{verbatim} -All TAP-specific parameters are stored using the paramList mechanism of UWS and -are included in the XML representation of the job: + +All TAP-specific parameters are stored using the parameter list mechanism of +UWS and are included in the XML representation of the job: \begin{verbatim} HTTP GET http://example.com/tap/async/42 \end{verbatim} @@ -1222,21 +1281,20 @@ \subsubsection{Creating a Query} assuming it is started immediately. In practice, it is very hard to estimate the time a query will take; for TAP services it is recommended that this be set to the current time plus the maximum amount of time the query will be allowed to -run (see termination below). - -The termination resource specifies the amount of time (in seconds) the job -(query) will be allowed to run before being aborted by the service. The -termination time is set by the service and can be read from the job or directly -from the termination resource: +run. The executionduration resource specifies the amount of time (in seconds) +the job (query) will be allowed to run before being aborted by the service. The +execution duration is set by the service and can be read from the job or +directly from the executionduration resource: \begin{verbatim} HTTP GET http://example.com/tap/async/42/executionduration \end{verbatim} -The service may allow the client to change the termination: +The service may allow the client to change the duration: \begin{verbatim} HTTP POST http://example.com/tap/async/42/executionduration -TERMINATION=600 +EXECUTIONDURATION=600 \end{verbatim} + The destruction resource specifies when the service will destroy the job. The service is only required to keep a job for a finite period of time, after which it may destroy the job, including the result. After this time, the client will @@ -1252,6 +1310,9 @@ \subsubsection{Creating a Query} DESTRUCTION=2008-11-11T11:11:11Z \end{verbatim} +In general, clients should fully specify the query job parameters and then +check and possibly negotiate the UWS job control parameters. + \subsubsection{Running a Query} The phase URL shows the progress of the job. When the job is created by the service it will normally be set to PENDING, but might be set to ERROR if the @@ -1261,14 +1322,14 @@ \subsubsection{Running a Query} The client runs the job by posting to the phase URL: \begin{verbatim} -HTTP POST http://example.com/tap /async/42/phase +HTTP POST http://example.com/tap/async/42/phase PHASE=RUN \end{verbatim} The service replies with a redirection to the job URL \begin{verbatim} HTTP status 303 'see other' -Location: http://example.com/tap /async/42 +Location: http://example.com/tap/async/42 \end{verbatim} The phase will now have changed to either QUEUED or EXECUTING, depending on the service implementation. The client tracks the execution by polling the phase @@ -1283,8 +1344,9 @@ \subsubsection{Running a Query} PHASE=ABORT \end{verbatim} -When the query is complete, the phase changes to COMPLETED. The client then -retrieves the result from the results list: +When the query job is complete, the phase changes will normally be one of +COMPLETED, ABORTED, or ERROR (although there are other less used phases defined +in \citep{std:UWS}). The client then retrieves the result from the results list: \begin{verbatim} HTTP GET http://example.com/tap/async/42/results/result \end{verbatim} @@ -1310,52 +1372,74 @@ \subsubsection{Running a Query} ABORTED and there is no table or results. As with errors, the client should look at the error resource to find out what went wrong. -The basic sequence can be executed from a web browser or from a shell script -using the curl utility: -\begin{verbatim} -curl -d 'REQUEST=doQuery&LANG=PQL&POS=12,34&SIZE=0.5&FROM=foo' \ - http://example.com/tap/async +\subsubsection{Example: Synchronous Query} - [read Location header from curl output] +Synchronous queries return the table of results in the HTTP response to the +initial request. This is an example of a synchronous ADQL query on r magnitude: -curl -d 'PHASE=RUN' http://example.com/tap/async/42 +\begin{verbatim} +HTTP POST http://example.com/tap/sync +REQUEST=doQuery +LANG=ADQL +QUERY=SELECT * FROM magnitudes as m where m.r>=10 and m.r<=16 +\end{verbatim} -curl http://example.com/tap/async/42/phase +In this examples, the output format defaults to VOTable; +the FORMAT parameter could be added to select a different format. - [repeat until phase is COMPLETED] +Many implementations will implement synchronous query execution using the +common POST-redirect-GET pattern. If this is the case, the response from the +initial POST will be a redirect (HTTP reponse code 303) and another URL for the +results, e.g.: -curl http://example.com/tap/42/results/result +\begin{verbatim} +Location: http://example.com/tap/sync/53/go \end{verbatim} -\subsubsection{Example: Synchronous Query} - -TODO +As described in \citep{std:DALI}, clients must be prepared to follow such +redirects to obtain the result. \subsubsection{Example: DALI-examples Document} TODO -\section{Use of STC-S in TAP - deprecated} +\appendix + +\section{Changes from Previous Versions} -NOTE: The old section 6 is not included from TAP-1.0 since it was informative -and does not belong in this document. If we need to define syntax for -points, circles, and polygons then that should be done in [std:DALI], which -already defines timestamp syntax. +\subsection{WD-TAP-1.1-20160415} -\section{VOSpace Integration - deprecated} +Completed the mapping table from VOTable to RDBMS datatypes using DALI-1.1 xtype values. -Note: some text moved to the UPLOAD section; may propose DEST parameter for -outout. +Added details and VOSI-capabilities example for providing multiple resources with different +authentication requirements. Clarified that VOSI-availability is no longer restricted to a +specific name or location. -\section{Use of HTTP - deprecated} -Note: This section is in or belongs in DALI. +\subsection{WD-TAP-1.1-20150930} -\appendix +Clarified that MAXREC always overrides limitations in the query (e.g. +TOP in an ADQL query). -\section{Changes from Previous Versions} +Clarified that services are not required to support queries that reference tables +in different schema. This is primarily to allow the TAP\_SCHEMA to be implemented +in a different server from the content. + +Completed the references section. \subsection{Changes from TAP-1.0} +Added table\_index and column\_index to TAP\_SCHEMA. + +Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow +indicator. + +Added advice that the size column TAP\_SCHEMA.columns must always be used +as a quoted identifier becayse it is a reserved word in many RDBMS +servers. Added arraysize column to TAP\_SCHEMA.columns to replace size and +deprecated size (which will be removed in the next major version). + +Removed REQUEST and VERSION parameters from interface. + Restructured the document and removed text that duplicates material from DALI. Rewrite the overly long introduction with some basic use cases to help define the scope and tell readers what TAP is supposed to accomplish. From bc04234a9ac58fa455b422b679b19e4daba974db Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 29 Apr 2016 05:35:49 +0000 Subject: [PATCH 09/68] added section on mapping VOTable datatypes to and from TAP; clarified naming of std resources --- Makefile | 2 +- TAP.tex | 86 ++++++++++++++++++++++++-------------------------------- 2 files changed, 38 insertions(+), 50 deletions(-) diff --git a/Makefile b/Makefile index 7173e89..fc6a830 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2016-04-15 +DOCDATE = 2016-04-28 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = WD diff --git a/TAP.tex b/TAP.tex index 2e5e368..92d61cb 100644 --- a/TAP.tex +++ b/TAP.tex @@ -205,9 +205,7 @@ \section{Resources} If a TAP service allows anonymous access, the fixed name resources and VOSI-availability must be used for anonymous access; other resource names may be used for authenticated access. If the entire service requires authentication then the fixed names may be used for -authenticated access. [Note: There is probably no use for authenticated VOSI-availability, -VOSI-capabilities, or DALI-examples resources when anonymous is allowed so those options -are not precent in the table above... should they be for completeness?] +authenticated access. The web resource at the root of the tree must represent the service as a whole. This specification defines no standard representation for this root resource. @@ -341,7 +339,6 @@ \subsection{/capabilities} The use of the VOSI-capabilities resource is described in \citep{std:DALI}. - For example, the returned capabilities document for a service supporting TAP might look as follows: @@ -778,8 +775,8 @@ \subsection{Successful Queries} in the SELECT clause of the query. For VOTable output, the name attribute of FIELD elements must be the same as the column names (or aliases if specified in the query) from the query and the datatype, arraysize, and xtype attributes of -FIELD elements must be set using the mapping specified in section 2.5 . The -xtype attribute in the output must match the datatype for the column in the +FIELD elements must be set using the mapping specified in section~\ref{sec:vot-rdbms}. +The xtype attribute in the output must match the datatype for the column in the TAP\_SCHEMA. VOTable structure follows the rules in section 2.9 and must be returned with an @@ -862,42 +859,30 @@ \subsection{Mapping Table Datatypes} This section describes the bi-directional mapping between VOTable and RDBMS + geometric datatypes and extends the basic rules for serialising such values in VOTable described in \citep{std:DALI}. These rules apply to input tables -supplied via an UPLOAD parameter (see ??) and to result tables after successful +supplied via an UPLOAD parameter (see section~\ref{sec:UPLOAD}) and to result tables after successful query execution. For input tables, the name attribute of the FIELD element is used as the column name. This name must be a legal ADQL column name (i.e., a string following the -regular identifier production of \citep{std:ADQL}). For result tables, the +regular identifier production \citep{std:ADQL}. For result tables, the column name or an alias specified in the query is used to set the name attribute -of the FIELD elements in the output table (the alias oevrrides the normal +of the FIELD elements in the output table (the alias overrides the normal column name). -NOTE: output column names from aliases may not be valid input -column names because users can put what they like in quotes... can we -or ADQL restrict the definition of a valid alias? - -NOTE2: if the select has a -fully-qualified column name (tab.col or alias.col) is that the output FIELD -name? Those are always going to be invalid input names and here users would -have to use aliases to make them valid for later input... is the goal that all -result tables would be valid input tables? Can we achieve that? - -The mapping between VOTable datatype, arraysize, and type attributes and +The mapping between VOTable datatype, arraysize, and xtype attributes and RDBMS datatypes are as follows: \begin{tabular}{l l l l l} \label{tab:vot-rdbms-mapping} datatype & arraysize & xtype & RDBMS datatype & required \\ char & [1] & & CHAR or CHAR(1) & yes \\ -char & * & & VARCHAR & yes \\ +char & * & & VARCHAR(*) or CLOB & no \\ char & n & & CHAR(n) & yes \\ char & n* & & VARCHAR(n) & yes \\ -char & n, *, n* & CLOB & CLOB & yes \\ unsignedByte & [1] & & BINARY(1) & yes \\ -unsignedByte & * & & VARBINARY(*) & yes \\ +unsignedByte & * & & VARBINARY(*) or BLOB & no \\ unsignedByte & n & & BINARY(n) & yes \\ unsignedByte & n* & & VARBINARY(n) & yes \\ -unsignedByte & n, *, n* & BLOB & BLOB & yes \\ short & [1] & & SMALLINT? & yes \\ short & * & & implementation-specific & no \\ short & n & & implementation-specific & no \\ @@ -918,7 +903,7 @@ \subsection{Mapping Table Datatypes} double & * & & implementation-specific & no \\ double & n & & implementation-specific & no \\ double & n* & & implementation-specific & no \\ -char & n or n* & timestamp & timestamp & yes \\ +char & n or n* & timestamp & implementation-specific & yes \\ double & 2 & point & implementation-specific & no \\ double & 3 & circle & implementation-specific & no \\ double & * & polygon & implementation-specific & no \\ @@ -935,8 +920,7 @@ \subsection{Mapping Table Datatypes} The default mapping of data types are shown above (no arraysize or xtype). If the xtype attribute is set, this is the preferred internal datatype. If xtype is not set, then the datatype and arraysize indicate the most suitable internal -datatype. Note that the RDBMS type i -s not normative. +datatype. Note that the RDBMS type is not normative. Implementations SHOULD try to make sure that the actual types chosen are at least signature-compatible with the recommended types (i.e., integers should remain integers, floating-point values floating-point values, etc.), such that @@ -944,24 +928,16 @@ \subsection{Mapping Table Datatypes} In the arraysize column above, [1] means the arraysize is not set or is set to 1, n means arraysize is set to a specific value, * means arraysize=”*”, and n* -means arraysize=”n*” (variable size up to length n). +means arraysize=”n*” (variable size up to length n). Support for arrays of +numeric values is not required but may be implemented and described. However, such +values can only be selected unless the query language or a custom extension or function +is provided. Binary values (unsignedByte in VOTable, BINARY, VARBINARY, or BLOB in ADQL) can be expressed as specified by the VOTable standard. By default, VOTable allows them to be written as an array of decimal numbers, e.g. 12 56 0 255 0 0 255 (one number per byte value). -For columns of type BLOB or CLOB, most database systems support reference to -these columns in the select clause but not in any other part of the query. -Services may use these types to indicate that columns may only be selected. For -example, if service implementors want to make URL(s) available as column values -in the results, but do not actually store the URL(s) in the database, they would -specify a column with xtype=”CLOB” and the column with URL(s) could be -referenced in the SELECT clause of a query, but could not be used in the WHERE -clause. The service could then process the query result and insert the URL(s) -or, more likely, transform a column value (an identifier) into a URL while -writing the results. - TIMESTAMP values are specified as described in \citep{std:DALI}. The xtype=timestamp attribute must be specified in an uploaded VOTable in order for the values to be inserted in a column of type TIMESTAMP; without the @@ -1083,15 +1059,27 @@ \subsection{Columns} The table\_name,column\_name (pair) values must be unique. -Data types and how they map to VOTable datatypes are described in Section -xref{sec:vot-rdbms} above. The arraysize column gives the length of variable -length datatypes, -for example varchar(256); this arraysize does not map exactly to the VOTable -arraysize attribute because -the latter can specify the size and shape of a multi-dimensional array as well +Database data types and how they map to VOTable datatypes are described in Section +xref{sec:vot-rdbms} above. However, the datatype column in the TAP\_SCHEMA.columns +table contains the database type: either an xtype defined in \citep{std:DALI} or a +TAPType defined in \citep{std:VODS11}. [TODO: make this consistent with VOSI-tables] +For columns with a datatype of BLOB or CLOB, most database systems support reference to +these columns in the select clause but not in any other part of the query. +Services may use these types to indicate that columns may only be selected. For +example, if service implementors want to make URL(s) available as column values +in the results, but do not actually store the URL(s) in the database, they would +specify a column with datatype CLOB in the TAP\_SCHEMA and the column with URL(s) could be +referenced in the SELECT clause of a query, but could not be used in the WHERE +clause. The service could then process the query result and insert the URL(s) +or, more likely, transform a column value (an identifier) into a URL while +writing the results. + +The arraysize column gives the length of variable length datatypes, for example +varchar(256); this arraysize does not map exactly to the VOTable arraysize attribute +because the latter can specify the size and shape of a multi-dimensional array as well as the variable size. The "size" column is retained for backwards compatiblity -to TAP-1.0 and must contain the same value as arrayaize. To use the -size column in a query, it must be put in double quotes since it collides with an ADQL reserved +to TAP-1.0 and must contain the same value as arraysize. To use the size column in a +query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the DDL for TAP\_SCHEMA) use lower case exclusively. In the next major version @@ -1111,7 +1099,7 @@ \subsection{Columns} to indicate that a given column is defined by some standard, as opposed to a custom column defined by a particular service. -The column\_index is used to recommended column ordering for clients. Clients +The column\_index is used to recommend column ordering for clients. Clients may order by column\_index (ascending) so lower index columns would appear earlier in a listing. This is useful for keeping related columns together in output or display. @@ -1407,7 +1395,7 @@ \subsubsection{Example: DALI-examples Document} \section{Changes from Previous Versions} -\subsection{WD-TAP-1.1-20160415} +\subsection{WD-TAP-1.1-20160428} Completed the mapping table from VOTable to RDBMS datatypes using DALI-1.1 xtype values. From e3494ab9715a60e7372c3c6f3c8ca16ec40f4af1 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 24 May 2016 09:11:51 +0000 Subject: [PATCH 10/68] TAP: fixing examples endpoint language to discourage use of a for table. --- TAP.tex | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/TAP.tex b/TAP.tex index 92d61cb..86ee594 100644 --- a/TAP.tex +++ b/TAP.tex @@ -450,10 +450,11 @@ \subsection{/examples} MUST return a 404 HTTP status on accessing this resource. If present, the endpoint must be represented in a capability in the TAP -service's registry record. The capability's standardID is defined by +service's registry record. The capability's \xmlel{standardID} is defined by +DALI \citep{std:DALI}. A capability element could hence look like this: -\begin{lstlisting}[language=XML] +\begin{lstlisting}[language=XML,basicstyle=\footnotesize] http://myarchive.net/myTAP/examples @@ -463,21 +464,21 @@ \subsection{/examples} TAP defines two additional properties for the examples vocabulary: -* query -- each example MUST have a unique child element with simple text -content having a property attribute valued query. It contains the query itself, +\begin{itemize} +\item query -- each example MUST have a unique child element with simple text +content having a \xmlel{property} attribute valued query. It contains the query itself, preferably with extra whitespace for easy human consumption and editing. This -will usually be a HTML pre element. +will usually be a HTML \xmlel{pre} element. -* table -- examples MAY also have descendants with property attributes having +\item table -- examples MAY also have descendants with \xmlel{property} attributes having the value table. These must have pure text content and contain fully qualified -table names to which the query is somehow "pertaining". Suitable HTML elements -holding these include span, or a (which would allow linking to further -information on the table). - -When using elements with src or href attributes to carry the property -attributes, note that the element content must be repeated in a content -attribute, as otherwise RDFa clients would interpret the embedded link rather -than the element content as the object in the triple. +table names to which the query is somehow ``pertaining''. +\end{itemize} + +Although it might be tempting, examples authors should not put table +names into HTML \xmlel{a} elements (e.g., to link to the table +descriptions). As discussed in DALI 1.1, sect.~2.3, this would result +in invalid RDF statements. \subsection{Parameters} \label{sec:parameters} From 98953fb03c8c3dd5b95edd785ce2ad81b17d3ccd Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 11 Oct 2016 16:25:45 +0000 Subject: [PATCH 11/68] remove datatype mapping and refer to DALI; clarify column name rules for upload and output tables; clarify VOSI resource usage --- Makefile | 2 +- TAP.tex | 134 +++++++++++++++++-------------------------------------- 2 files changed, 41 insertions(+), 95 deletions(-) diff --git a/Makefile b/Makefile index fc6a830..829ca85 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2016-04-28 +DOCDATE = 2016-10-11 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = WD diff --git a/TAP.tex b/TAP.tex index 86ee594..1017aa4 100644 --- a/TAP.tex +++ b/TAP.tex @@ -186,9 +186,9 @@ \section{Resources} {async} & /async & must & \\ {sync} & service specific & may (alternate authentication method) & \\ {async} & service specific & may (alternate authentication method) & \\ -VOSI-availability & service specific & must & \\ +VOSI-availability & service specific & must (should be anonymous) & \\ VOSI-availability & service specific & may (alternate authentication method) & \\ -VOSI-capabilities & /capabilities & must & \\ +VOSI-capabilities & /capabilities & must (should be anonymous) & \\ VOSI-capabilities & service specific & may (alternate authentication method) & \\ VOSI-tables & /tables & should & \\ VOSI-tables & service specific & may (alternate authentication method) & \\ @@ -202,10 +202,13 @@ \section{Resources} As required by \citep{std:DALI}, all resources except the VOSI-availability must be siblings of the VOSI-capabilities resource. -If a TAP service allows anonymous access, the fixed name resources and VOSI-availability -must be used for anonymous access; other resource names may be used for authenticated access. -If the entire service requires authentication then the fixed names may be used for -authenticated access. +The fixed name resources above (async, sync, tables) should be used for the +primary access mode of the service; this is typically anonymous access and +other resource names may be used for authenticated access. However, if a +service only supports authenticated access to these resources, the fixed names +may be used for authenticated access. The VOSI resources should allow anonymous +access as they can be used by clients to determine if the service is available +and which resources to use with available security (authentication) methods. The web resource at the root of the tree must represent the service as a whole. This specification defines no standard representation for this root resource. @@ -775,10 +778,12 @@ \subsection{Successful Queries} The output table must include the same number and order of columns as specified in the SELECT clause of the query. For VOTable output, the name attribute of FIELD elements must be the same as the column names (or aliases if specified in -the query) from the query and the datatype, arraysize, and xtype attributes of -FIELD elements must be set using the mapping specified in section~\ref{sec:vot-rdbms}. -The xtype attribute in the output must match the datatype for the column in the -TAP\_SCHEMA. +the query) in the query and the datatype, arraysize, and xtype +attributes of FIELD elements must be set using the advice in +section~\ref{sec:vot-rdbms}. In cases where items in the select list do not +have names (e.g. function invocation) the service must generate a name; +generated names must be unique (within the output table) and should be valid +ADQL identifiers. VOTable structure follows the rules in section 2.9 and must be returned with an allowed VOTable MIME type (application/x-votable+xml or text/xml). If the @@ -864,90 +869,20 @@ \subsection{Mapping Table Datatypes} query execution. For input tables, the name attribute of the FIELD element is used as the column -name. This name must be a legal ADQL column name (i.e., a string following the -regular identifier production \citep{std:ADQL}. For result tables, the -column name or an alias specified in the query is used to set the name attribute -of the FIELD elements in the output table (the alias overrides the normal -column name). - -The mapping between VOTable datatype, arraysize, and xtype attributes and -RDBMS datatypes are as follows: - -\begin{tabular}{l l l l l} -\label{tab:vot-rdbms-mapping} -datatype & arraysize & xtype & RDBMS datatype & required \\ -char & [1] & & CHAR or CHAR(1) & yes \\ -char & * & & VARCHAR(*) or CLOB & no \\ -char & n & & CHAR(n) & yes \\ -char & n* & & VARCHAR(n) & yes \\ -unsignedByte & [1] & & BINARY(1) & yes \\ -unsignedByte & * & & VARBINARY(*) or BLOB & no \\ -unsignedByte & n & & BINARY(n) & yes \\ -unsignedByte & n* & & VARBINARY(n) & yes \\ -short & [1] & & SMALLINT? & yes \\ -short & * & & implementation-specific & no \\ -short & n & & implementation-specific & no \\ -short & n* & & implementation-specific & no \\ -int & [1] & & INTEGER & yes \\ -int & * & & implementation-specific & no \\ -int & n & & implementation-specific & no \\ -int & n* & & implementation-specific & no \\ -long & [1] & & BIGINT & yes \\ -long & * & & implementation-specific & no \\ -long & n & & implementation-specific & no \\ -long & n* & & implementation-specific & no \\ -float & [1] & & REAL & yes \\ -float & * & & implementation-specific & no \\ -float & n & & implementation-specific & no \\ -float & n* & & implementation-specific & no \\ -double & [1] & & DOUBLE [PRECISION] & yes \\ -double & * & & implementation-specific & no \\ -double & n & & implementation-specific & no \\ -double & n* & & implementation-specific & no \\ -char & n or n* & timestamp & implementation-specific & yes \\ -double & 2 & point & implementation-specific & no \\ -double & 3 & circle & implementation-specific & no \\ -double & * & polygon & implementation-specific & no \\ -float & 2 & point & implementation-specific & no \\ -float & 3 & circle & implementation-specific & no \\ -float & * & polygon & implementation-specific & no \\ -short & 2 & interval & implementation-specific & no \\ -int & 2 & interval & implementation-specific & no \\ -long & 2 & interval & implementation-specific & no \\ -float & 2 & interval & implementation-specific & no \\ -double & 2 & interval & implementation-specific & no \\ -\end{tabular} - -The default mapping of data types are shown above (no arraysize or xtype). If -the xtype attribute is set, this is the preferred internal datatype. If xtype is -not set, then the datatype and arraysize indicate the most suitable internal -datatype. Note that the RDBMS type is not normative. -Implementations SHOULD try to make sure that the actual types chosen are at -least signature-compatible with the recommended types (i.e., integers should -remain integers, floating-point values floating-point values, etc.), such that -clients can reliably write queries against uploaded tables. - -In the arraysize column above, [1] means the arraysize is not set or is set to -1, n means arraysize is set to a specific value, * means arraysize=”*”, and n* -means arraysize=”n*” (variable size up to length n). Support for arrays of -numeric values is not required but may be implemented and described. However, such -values can only be selected unless the query language or a custom extension or function -is provided. - -Binary values (unsignedByte in VOTable, BINARY, VARBINARY, or BLOB in ADQL) can -be expressed as specified by the VOTable standard. By default, VOTable allows -them to be written as an array of decimal numbers, e.g. 12 56 0 255 0 0 255 (one -number per byte value). - -TIMESTAMP values are specified as described in \citep{std:DALI}. The -xtype=timestamp attribute must be specified in an uploaded VOTable in -order for the values to be inserted in a column of type TIMESTAMP; without the -xtype, the values would be inserted into a CHAR(n) or VARCHAR column. - -POINT, CIRCLE, and POLYGON values are specified as arrays of double values as -described in \citep{std:DALI}. The xtype attribute must be specified in -an uploaded VOTable in order for the array values to be parsed and treated as -geometric values and thus to be used with some of the ADQL features. +name. Services must support delimited identifiers so that +FIELD names that are not valid ADQL column names work correctly +\citep{std:ADQL}. +For result tables, the column name or an alias specified in the query is used +to set the name attribute of the FIELD elements in the output table (the alias +overrides the normal column name). + +The mapping to and from VOTable makes use of the datatype, arraysize, and xtype +attributes. Mapping for primitive types (numbers and strings) is +straightforward; services should insure that input values behave as +expected in query processing and output values should have correct and complete +metadata. Mapping for specially structured values use xtype(s) specified +in \citep{std:DALI}. The behaviour of such structured values in queries depends +on the query language (section~\ref{sec:LANG}) being used. \section{Metadata: TAP\_SCHEMA} \label{sec:tap-schema} @@ -1396,6 +1331,17 @@ \subsubsection{Example: DALI-examples Document} \section{Changes from Previous Versions} +\subsection{WD-TAP-1.1-20161011} + +Removed details of mapping database and VOTable data types and refer to DALI +instead. + +Strongly recommend that VOSI resources allow anonymous access. + +Relax restrictions on column names in uploaded tables; clarify that services +must support quoted identifiers. Advise that services should assign unique +colum names in cases where they generate the name. + \subsection{WD-TAP-1.1-20160428} Completed the mapping table from VOTable to RDBMS datatypes using DALI-1.1 xtype values. From eeba84bc1c06b2f5801bf88c176acbd51bc3ffec Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 4 Jul 2017 21:08:25 +0000 Subject: [PATCH 12/68] update WD-TAP-1.1 to use VOTable datatype,arraysize,xtype in tap_schema and recommend VOTableType over TAPType in VOSI-tables output; other fixes from Kristin also included --- TAP.tex | 226 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 124 insertions(+), 102 deletions(-) diff --git a/TAP.tex b/TAP.tex index 1017aa4..795bd6b 100644 --- a/TAP.tex +++ b/TAP.tex @@ -181,7 +181,7 @@ \section{Resources} \begin{tabular}{l l l l l} \label{tab:resources} -resource type & resource name & required \\ +\textbf{resource type} & \textbf{resource name} & \textbf{required} \\ {sync} & /sync & must & \\ {async} & /async & must & \\ {sync} & service specific & may (alternate authentication method) & \\ @@ -349,11 +349,11 @@ \subsection{/capabilities} @@ -440,7 +440,10 @@ \subsection{/tables} /tables that is a direct child of the root web resource. The /tables resource must be accessible via the http GET method. The content is described by \citep{std:VODS11} and is equivalent to the metadata from the -TAP\_SCHEMA described in section~\ref{sec:tap-schema}. +TAP\_SCHEMA described in section~\ref{sec:tap-schema}. The use of VOTableType +(rather than TAPType) in the VOSI-tables output is recommended because the values +map directly; TAPType may be used when VOTableType does not provide a suitable +alternative. Services which do not implement the /tables resource must respond with an HTTP response code of 404 when this resource is accessed. @@ -509,9 +512,9 @@ \subsection{Parameters} \subsubsection{LANG} \label{sec:LANG} -The LANG parameter specifies the query language. The service must support LANG -and the client must provide a value with REQUEST=doQuery. The only standard -values for the LANG parameter is ADQL (a required language). Support for other +The LANG parameter specifies the query language. The service must support the LANG +parameter and the client must provide a value. The only standard +values for the LANG parameter is ADQL. Support for other languages and the LANG value to use with them is described in the service capabilities. @@ -550,30 +553,20 @@ \subsubsection{QUERY} Within the ADQL query, the service must support the use of timestamp values as described in \citep{std:DALI}. -TAP-1.0 text about ADQL region functions: +Within the ADQL query, the following ADQL functions mus be supported: INTERSECTS, +CONTAINS, POINT, CIRCLE, and POLYGON. POINT (including a point-valued column or +function return value) cannot be used as an argument to INTERSECTS (even if allowed +by older versions of ADQL). +AREA, CENTROID, COORDSYS, COORD1, and COORD2 are optional. REGION is no longer +supported. -If the tables that are queried through a service contain columns with spatial -coordinates and the service supports spatial querying via the ADQL “region” -constructs, the service must support the INTERSECTS function and it must support -the following geometry functions: REGION, POINT, BOX, CIRCLE, COORD1, COORD2, -COORDSYS. Support for the AREA, CONTAINS, and POLYGON functions are optional. If -the service supports the REGION function, it must support region encoding in -STC-S format (see section 6 ); the extent of STC-S support within the REGION -function is left up to the implementation. Coordinate system specification for -POINT, BOX, CIRCLE, and POLYGON must use values from STC-S as described in ???. - -Proposed TAP-1.1 text: - -INTERSECTS and CONTAINS are required. POINT, CIRCLE, and POLYGON are required. -POINT (and point-valued columns) cannot be used as an argument to INTERSECTS. -AREA, CENTROID, COORDSYS, COORD1, and COORD2 are optional. REGION is not -supported (and hopefully gone from ADQL-2.1). - -Note: Although it is allowed by the ADQL syntax, clients should be careful when +Note: Although it is allowed by the ADQL syntax (version 2.0 at least), clients should be careful when mixing constants and column references for coordinate system and coordinate values. For example, POINT('ICRS', t.ra, t.dec) does not cause t.ra and t.dec to be transformed to ICRS; it simply tells the service to treat the values as -being expressed in that coordinate system. +being expressed in that coordinate system. Clients should avoid using the coordinate +system argument to geometric functions should not be used (use null value or use an +alternate function without the coordinate system argument if available). \subsubsection{FORMAT and RESPONSEFORMAT} \label{sec:RESPONSEFORMAT} @@ -626,13 +619,12 @@ \subsubsection{UPLOAD} upload of temporary tables (in \citep{std:VOTable} format) via the standard UPLOAD parameter. The table-name(s) must be legal ADQL table names as defined in -\citep{std:ADQL} but restricted as described below XREF. URIs maybe be simple -URLs -(e.g. with a URI scheme of http) or URIs (e.g. with a URI scheme of vos or -param) that must be resolved to give the location of the table content. See -section XREF for details. +\citep{std:ADQL} but restricted as described in section~\ref{sec:tap-schema}. +URIs maybe be simple URLs (e.g. with a URI scheme of http or https) or +URIs that must be resolved (e.g. with a URI scheme of vos or param) to give +the location of the table content. -If table upload supported, the service must accept tables in VOTable format. +If table upload is supported, the service must accept tables in VOTable format. The client specifies the name of the uploaded table; this name must be a legal ADQL table name with no catalog or schema (i.e., a string following the regular identifier production of \citep{std:ADQL}). Uploaded tables must be @@ -654,7 +646,7 @@ \subsubsection{UPLOAD} The service would retrieve the table from the provided URL and make it visible to the query as TAP\_UPLOAD.mytable. -If the TAP service supports VOSpace (TBD: how to declare this?), one may +If the TAP service supports VOSpace URIs, one may specify an upload table using a URI to a table stored in a VOSpace, for example: \begin{verbatim} HTTP POST http://example.com/tap/async/42 @@ -674,6 +666,11 @@ \subsubsection{UPLOAD} uploaded tables; if the service refuses to accept the entire table it must respond with an error as described in section~\ref{sec:query-error}. +Table upload must support all valid VOTable content even if they do not support +all features and uses of extended data types; clients must be able to upload and then +query a valid table and round-trip all values. Services should store extended types (e.g. +timestamp) in an appropriate database column type in order to facilitate predictable use +in queries. \section{Use of VOTable} \label{sec:votable} @@ -779,8 +776,8 @@ \subsection{Successful Queries} in the SELECT clause of the query. For VOTable output, the name attribute of FIELD elements must be the same as the column names (or aliases if specified in the query) in the query and the datatype, arraysize, and xtype -attributes of FIELD elements must be set using the advice in -section~\ref{sec:vot-rdbms}. In cases where items in the select list do not +attributes of FIELD elements must be set using the values from the TAP\_SCHEMA. +In cases where items in the select list do not have names (e.g. function invocation) the service must generate a name; generated names must be unique (within the output table) and should be valid ADQL identifiers. @@ -824,7 +821,7 @@ \subsection{Errors} cannot be controlled by TAP implementations. There are several cases where a TAP service could return an HTTP error. First, the /async endpoint could return a -404 (not found) error if the client accesses a job within the UWS joblist that +404 (not found) error if the client accesses a job within the UWS job list that does not exist. Second, access to a resource could result in an HTTP 401 (not authorized) error if authentication is required or an HTTP 403 (forbidden) error if the client is not allowed to access the resource. @@ -915,8 +912,13 @@ \section{Metadata: TAP\_SCHEMA} defined in section 2.4. The names must be stated in a form that is acceptable as an operand of a query. -All columns in the TAP\_SCHEMA tables are of type VARCHAR except -for size, principal, indexed, and std (in Columns) which are INTEGER values. +Column datatypes in the TAP\_SCHEMA are specified using the same concepts used in +VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors +must also include the "size" column and populate it where possible. The arraysize values +specified below for describing the TAP\_SCHEMA tables themselves is the most flexible +(* means variable length with no maximum); implementors should use more restrictive values +that describe their implementation of the TAP\_SCHEMA tables (e.g. arraysize 64* to describe +a column with database type varchar(64)). Implementors are permitted to include additional tables in the TAP\_SCHEMA to describe additional aspects of their service not @@ -929,12 +931,12 @@ \subsection{Schemas} The table TAP\_SCHEMA.schemas must contain the following columns: -\begin{tabular}{l l l} +\begin{tabular}{l l l l l} \label{tab:resources} -column name & datatype & not-null \\ -schema\_name & VARCHAR & true \\ -utype & VARCHAR & false \\ -description & VARCHAR & false \\ +\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +schema\_name & char & * & null & true \\ +utype & char & * & null & false \\ +description & char & * & null & false \\ \end{tabular} The schema\_name values must be unique and may be qualified by the @@ -947,15 +949,15 @@ \subsection{Tables} \label{sec:tap-schema-tables} The table TAP\_SCHEMA.tables must contain the following columns: -\begin{tabular}{l l l} +\begin{tabular}{l l l l l} \label{tab:tap-schema-tables} -column name & datatype & not-null \\ -schema\_name & VARCHAR & true \\ -table\_name & VARCHAR & true \\ -table\_type & VARCHAR & true \\ -utype & VARCHAR & false \\ -description & VARCHAR & false \\ -table\_index & INTEGER & false \\ +\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +schema\_name & char & * & null & true \\ +table\_name & char & * & null & true \\ +table\_type & char & * & null & true \\ +utype & char & * & null & false \\ +description & char & * & null & false \\ +table\_index & char & * & null & false \\ \end{tabular} The table\_name values must be unique. The value of the @@ -966,6 +968,8 @@ \subsection{Tables} If the table name is such that the name must be quoted (quoted identifier in \citep{std:ADQL}) then the value must include the quotes. +The table\_type value must be either table or view. + The table\_index is used to recommended table ordering for clients. Clients may order by table\_index (ascending) so lower index tables would appear earlier in a listing. @@ -974,33 +978,50 @@ \subsection{Columns} \label{sec:tap-schema-columns} The table TAP\_SCHEMA.columns must contain the following columns: -\begin{tabular}{l l l} +\begin{tabular}{l l l l l} \label{tab:tap-schema-columns} -column name & datatype & not-null \\ -table\_name & VARCHAR & true \\ -column\_name & VARCHAR & true \\ -datatype & VARCHAR & true \\ -arraysize & INTEGER & false \\ -"size" & INTEGER & false \\ -description & VARCHAR & false \\ -utype & VARCHAR & false \\ -unit & VARCHAR & false \\ -ucd & VARCHAR & false \\ -indexed & BOOLEAN? & true \\ -principal & BOOLEAN? & true \\ -std & BOOLEAN? & true \\ -column\_index & false \\ +\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +table\_name & char & * & null & true \\ +column\_name & char & * & null & true \\ +datatype & char & * & null & true \\ +arraysize & char & * & null & false \\ +xtype & char & * & null & false \\ +"size" & int & 1 & null & false \\ +description & char & * & null & false \\ +utype & char & * & null & false \\ +unit & char & * & null & false \\ +ucd & char & * & null & false \\ +indexed & boolean & 1 & null & true \\ +principal & boolean & 1 & null & true \\ +std & boolean & 1 & null & true \\ +column\_index & int & 1 & null & false \\ \end{tabular} The table\_name,column\_name (pair) values must be unique. -Database data types and how they map to VOTable datatypes are described in Section -xref{sec:vot-rdbms} above. However, the datatype column in the TAP\_SCHEMA.columns -table contains the database type: either an xtype defined in \citep{std:DALI} or a -TAPType defined in \citep{std:VODS11}. [TODO: make this consistent with VOSI-tables] -For columns with a datatype of BLOB or CLOB, most database systems support reference to -these columns in the select clause but not in any other part of the query. +The type of a database column is described in the TAP\_SCHEMA.columns +table using three (3) columns with an additional (deprecated) column from TAP-1.0 +for backwards compatibility. The allowed values for datatype and the syntax for arraysize +are specified in VOTable \citep{std:VOTable}. Values for xtype are not restricted per se but +implementors should use standard values such as those defined in DALI \citep{std:DALI} before +inventing new xtype(s). + +The arraysize column gives the length of variable length datatypes using the VOTable +array shape syntax. For example, a database column of type varchar(256) would be +described with datatype "char" and arraysize "256*". Arrays, including multi-dimensional +arrays, are permitted for all VOTable primitive types. The "size" column is retained for backwards +compatibility to TAP-1.0 and must contain the integer value equivalent to arraysize when +possible and must be null if arraysize represents a multi-dimensional or variable-length value. +To use the size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both +clients and servers MUST always (in particular, in the creation of the +TAP\_SCHEMA) use lower case exclusively). In the next major version +of TAP, the "size" column will be removed. + +For columns with a database type equivalent to BLOB or CLOB, most database systems support +reference to these columns in the select clause but not in any other part of the query. + +\textbf{TODO: add a mechanism for services to say a column can only be selected. ADQL xtypes?} Services may use these types to indicate that columns may only be selected. For example, if service implementors want to make URL(s) available as column values in the results, but do not actually store the URL(s) in the database, they would @@ -1010,17 +1031,6 @@ \subsection{Columns} or, more likely, transform a column value (an identifier) into a URL while writing the results. -The arraysize column gives the length of variable length datatypes, for example -varchar(256); this arraysize does not map exactly to the VOTable arraysize attribute -because the latter can specify the size and shape of a multi-dimensional array as well -as the variable size. The "size" column is retained for backwards compatiblity -to TAP-1.0 and must contain the same value as arraysize. To use the size column in a -query, it must be put in double quotes since it collides with an ADQL reserved -word. Since delimited identifiers are case-sensitive, for the size column both -clients and servers MUST always (in particular, in the DDL for -TAP\_SCHEMA) use lower case exclusively. In the next major version -of TAP, the "size" column will be removed. - The “principal” flag indicates that the column is considered a core part the content; clients can use this hint to make the principal column(s) visible, for example by selecting them by default in generating an ADQL query. In cases where @@ -1045,14 +1055,14 @@ \subsection{Foreign Keys} The table TAP\_SCHEMA.keys must contain the following columns to describe foreign key relations between tables: -\begin{tabular}{l l l} +\begin{tabular}{l l l l l} \label{tab:tap-schema-keys} -column name & datatype & not-null \\ -key\_id & VARCHAR & true \\ -from\_table & VARCHAR & true \\ -target\_table & VARCHAR & true \\ -description & VARCHAR & false \\ -utype & VARCHAR & false \\ +\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +key\_id & char & * & null & true \\ +from\_table & char & * & null & true \\ +target\_table & char & * & null & true \\ +description & char & * & null & false \\ +utype & char & * & null & false \\ \end{tabular} The key\_id values are unique and used only to join with the @@ -1063,12 +1073,12 @@ \subsection{Foreign Keys} The table TAP\_SCHEMA.key\_columns must contain the following columns to describe the columns that make up a foreign key: -\begin{tabular}{l l l} +\begin{tabular}{l l l l l} \label{tab:tap-schema-key-columns} -column name & datatype & not-null \\ -key\_id & VARCHAR & true \\ -from\_column & VARCHAR & true \\ -target\_column & VARCHAR & true \\ +\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +key\_id & char & * & null & true \\ +from\_column & char & * & null & true \\ +target\_column & char & * & null & true \\ \end{tabular} There may be one or more rows with a specific key\_id to @@ -1103,7 +1113,7 @@ \subsubsection{Creating and Executing a Simple Query} QUERY=SELECT * FROM magnitudes AS m WHERE m.r>=10 AND m.r<=16 \end{verbatim} -The service's response to this request is an HTTP redirect with a URL fo the +The service's response to this request is an HTTP redirect with a URL for the query job: \begin{verbatim} @@ -1313,7 +1323,7 @@ \subsubsection{Example: Synchronous Query} Many implementations will implement synchronous query execution using the common POST-redirect-GET pattern. If this is the case, the response from the -initial POST will be a redirect (HTTP reponse code 303) and another URL for the +initial POST will be a redirect (HTTP response code 303) and another URL for the results, e.g.: \begin{verbatim} @@ -1331,6 +1341,18 @@ \subsubsection{Example: DALI-examples Document} \section{Changes from Previous Versions} +\subsection{WD-TAP-1.1-20170704} + +Changed arraysize in TAP\_SCHEMA to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. + +Clarified required and optional ADQL geometric functions. + +Format tables so column headers are bold. + +Added paragraph specifying allowed values for TAP\_SCHEMA.tables.table\_type. + +Fixed URL to schema in VOSI-capabilities example. + \subsection{WD-TAP-1.1-20161011} Removed details of mapping database and VOTable data types and refer to DALI @@ -1340,7 +1362,7 @@ \subsection{WD-TAP-1.1-20161011} Relax restrictions on column names in uploaded tables; clarify that services must support quoted identifiers. Advise that services should assign unique -colum names in cases where they generate the name. +column names in cases where they generate the name. \subsection{WD-TAP-1.1-20160428} @@ -1369,7 +1391,7 @@ \subsection{Changes from TAP-1.0} indicator. Added advice that the size column TAP\_SCHEMA.columns must always be used -as a quoted identifier becayse it is a reserved word in many RDBMS +as a quoted identifier because it is a reserved word in many RDBMS servers. Added arraysize column to TAP\_SCHEMA.columns to replace size and deprecated size (which will be removed in the next major version). @@ -1380,7 +1402,7 @@ \subsection{Changes from TAP-1.0} the scope and tell readers what TAP is supposed to accomplish. Made clarifications: restricted allowed table names for UPLOAD, clarified that -multiple UPLOAD pamaters accumulate, deprecated the size column in +multiple UPLOAD parameters accumulate, deprecated the size column in TAP\_SCHEMA.columns and added advice to quote it as a delimited identifier, made presence of a TABLE element on VOTable output only required for successful queries, added optional DALI-examples endpoint (text TBD). From c81d6ed4ef9553a1319889fd430b639928157867 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 7 Jul 2017 17:15:09 +0000 Subject: [PATCH 13/68] resolved BLOB/CLOB issue by adding text that queries should fail with a suitable error message if a column is used in an inappropriate part of the query but in the case of BLOB, CLOB, and generated columns there is no mechanism to decribe this to users; set WD publication date to 20170707; restored author list from 1.0 doc --- Makefile | 2 +- TAP.tex | 43 +++++++++++++++++++++---------------------- 2 files changed, 22 insertions(+), 23 deletions(-) diff --git a/Makefile b/Makefile index 829ca85..04c3ea0 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2016-10-11 +DOCDATE = 2017-07-07 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = WD diff --git a/TAP.tex b/TAP.tex index 795bd6b..f18b8e8 100644 --- a/TAP.tex +++ b/TAP.tex @@ -10,10 +10,11 @@ \ivoagroup{Data Access Layer Working Group} -\author{Patrick Dowler, ...} +\author{Patrick Dowler, Guy Rixon, Doug Tody} \editor{Patrick Dowler} +\previousversion[http://www.ivoa.net/Documents/TAP/20160428/]{WD-TAP-1.1-20160428} \previousversion[http://www.ivoa.net/Documents/TAP/1.0]{TAP-1.0} @@ -40,8 +41,8 @@ \section*{Acknowledgments} The authors would like to acknowledge all contributors to this and previous versions of this standard, especially: K. Andrews, J. Good, R. Hanisch, G. -Lemson, T. McGlynn, K. Noddle, F. Ochsenbein, I. Ortiz, P. Osuna, R. Plante, G. -Rixon, J. Salgado, A. Stebe, and A. Szalay. +Lemson, T. McGlynn, K. Noddle, F. Ochsenbein, I. Ortiz, P. Osuna, R. Plante, +J. Salgado, A. Stebe, and A. Szalay. \section*{Conformance-related definitions} @@ -826,15 +827,14 @@ \subsection{Errors} authorized) error if authentication is required or an HTTP 403 (forbidden) error if the client is not allowed to access the resource. -Error documents for TAP errors must be VOTable documents; any result-format -specified in the request is ignored. If the error document is being retrieved +Error documents should be in a format that matches the requested +format where possible; see DALI \citep{std:DALI} for details. +If the error document is being retrieved from the /async//error resource (specified by UWS) after an asynchronous query, the HTTP status code should be 200. If the error document is being returned directly after a synchronous query, the service may use an appropriate HTTP status code, including 200 (successfully returning a response to the -request) and various 4xx and 5xx values. The exception condition must be -described to the client using a status code in the VOTable header. Section -2.9 specifies the use of VOTable for error documents in TAP services. +request) and various 4xx and 5xx values. \subsection{Overflows} \label{sec:query-overflow} @@ -1019,17 +1019,13 @@ \subsection{Columns} of TAP, the "size" column will be removed. For columns with a database type equivalent to BLOB or CLOB, most database systems support -reference to these columns in the select clause but not in any other part of the query. - -\textbf{TODO: add a mechanism for services to say a column can only be selected. ADQL xtypes?} -Services may use these types to indicate that columns may only be selected. For -example, if service implementors want to make URL(s) available as column values -in the results, but do not actually store the URL(s) in the database, they would -specify a column with datatype CLOB in the TAP\_SCHEMA and the column with URL(s) could be -referenced in the SELECT clause of a query, but could not be used in the WHERE -clause. The service could then process the query result and insert the URL(s) -or, more likely, transform a column value (an identifier) into a URL while -writing the results. +reference to these columns in the select clause but not in every other part of the query where +character columns may be used. In addition, services may want to define generated columns where the output is dynamically generated but the content is not stored in the +databasase in a form that supports querying. For example, if service implementors want to make +URL(s) available as column values in the results, but do not actually store the URL(s) in the +database, the column with URL(s) could be referenced in the SELECT clause of a query, but could +not sensibly be used in the WHERE clause. In general, if a query references a column in an +inapprpriate part of the query, the job should fail with a suitable error message. The “principal” flag indicates that the column is considered a core part the content; clients can use this hint to make the principal column(s) visible, for @@ -1306,7 +1302,7 @@ \subsubsection{Running a Query} ABORTED and there is no table or results. As with errors, the client should look at the error resource to find out what went wrong. -\subsubsection{Example: Synchronous Query} +\subsection{Example: Synchronous Query} Synchronous queries return the table of results in the HTTP response to the initial request. This is an example of a synchronous ADQL query on r magnitude: @@ -1333,7 +1329,7 @@ \subsubsection{Example: Synchronous Query} As described in \citep{std:DALI}, clients must be prepared to follow such redirects to obtain the result. -\subsubsection{Example: DALI-examples Document} +\subsection{Example: DALI-examples Document} TODO @@ -1341,7 +1337,7 @@ \subsubsection{Example: DALI-examples Document} \section{Changes from Previous Versions} -\subsection{WD-TAP-1.1-20170704} +\subsection{WD-TAP-1.1-20170707} Changed arraysize in TAP\_SCHEMA to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. @@ -1351,6 +1347,9 @@ \subsection{WD-TAP-1.1-20170704} Added paragraph specifying allowed values for TAP\_SCHEMA.tables.table\_type. +Changed the principal, indexed, and std columns in TAP\_SCHEMA.columns to boolean since we +now use the VOTabletype system. + Fixed URL to schema in VOSI-capabilities example. \subsection{WD-TAP-1.1-20161011} From 2fc9aa19307018b2950ccf3cd2ccbd1b81471a90 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 11 Jul 2017 08:45:54 +0000 Subject: [PATCH 14/68] Adding an example for /examples. --- TAP.tex | 16 ++++++++-- examples-sample.html | 72 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+), 3 deletions(-) create mode 100644 examples-sample.html diff --git a/TAP.tex b/TAP.tex index f18b8e8..22707bf 100644 --- a/TAP.tex +++ b/TAP.tex @@ -2,8 +2,9 @@ \input tthdefs \usepackage{listings} -\lstloadlanguages{XML} -\lstset{flexiblecolumns=true,basicstyle=\small,tagstyle=\ttfamily} +\lstloadlanguages{XML,HTML} +\lstset{flexiblecolumns=true,basicstyle=\small,tagstyle=\ttfamily, + showstringspaces=False} \usepackage[utf8]{inputenc} \title{Table Access Protocol} @@ -1331,7 +1332,14 @@ \subsection{Example: Synchronous Query} \subsection{Example: DALI-examples Document} -TODO +The following is a full document a service might serve from its +\verb|/examples| endpoint; note that you can add arbitrary styling or +further HTML material without impacting the document's functionality. + +The document also shows how operators can add links to table +descriptions without breaking RDFa semantics. + +\lstinputlisting[language=HTML,basicstyle=\footnotesize]{examples-sample.html} \appendix @@ -1339,6 +1347,8 @@ \section{Changes from Previous Versions} \subsection{WD-TAP-1.1-20170707} +Added an example for \verb|examples|. + Changed arraysize in TAP\_SCHEMA to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. Clarified required and optional ADQL geometric functions. diff --git a/examples-sample.html b/examples-sample.html new file mode 100644 index 0000000..bef2f23 --- /dev/null +++ b/examples-sample.html @@ -0,0 +1,72 @@ + + + + An Example for /examples + + +

An Example for /examples

+ +

This document illustrates how to write a DALI-compliant examples + document using TAP's special table and query properties. Apart from the + actual examples blocks, you can add arbitrary additional material, for + instance, a table of contents:

+ + + +

Use the W3C RDFa validator to see what semantics your RDFa actually + conveys.

+ +
+

Query for CALIFA object properties

+

This example shows how to combine the + ↗califadr3.objects table + of properties of CALIFA target galaxies with the + ↗califadr3.cubes + table of data cubes to select bright, early-type spirals:

+ 
+SELECT target_name, accref, hubtyp, magg
+FROM califadr3.cubes
+  NATURAL JOIN califadr3.objects
+WHERE hubtyp in ('S d', 'S cd', 'S c')
+  AND magg<13
+
+
+ +
+

Query against coverage

+

When querying against geometric columns, in particular coverage, + use ADQL's contains or intersect functions, like this:

+ 
+SELECT accref, seeing
+  FROM cars.images
+      WHERE 1=INTERSECTS(coverage, circle('ICRS', 34, -4, 2))
+      ORDER BY seeing
+
+

Of course, this concerns all SIAP and SSAP tables + (↗cars.images only + standing as an example here) as well as + ↗ivoa.obscore +

+
+ + + From 63c3837f1ffd64d8ca07bbb532766042a674e383 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 11 Jul 2017 08:55:16 +0000 Subject: [PATCH 15/68] TAP: Adapting changelog for released 070707 version Also, adding VCS metadata in the doc header, and properly declaring TAP.tex's dependency on examples-sample.html in the Makefile. --- Makefile | 2 +- TAP.tex | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 04c3ea0..a895940 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ DOCTYPE = WD # Source files for the TeX document (but the main file must always # be called $(DOCNAME).tex -SOURCES = $(DOCNAME).tex +SOURCES = $(DOCNAME).tex examples-sample.html # List of pixel image files to be included in submitted package FIGURES = archdiag.png diff --git a/TAP.tex b/TAP.tex index 22707bf..c9e67da 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1,6 +1,10 @@ \documentclass[11pt,letter]{ivoa} \input tthdefs +\SVN$Rev$ +\SVN$Date$ +\SVN$URL$ + \usepackage{listings} \lstloadlanguages{XML,HTML} \lstset{flexiblecolumns=true,basicstyle=\small,tagstyle=\ttfamily, @@ -1345,10 +1349,12 @@ \subsection{Example: DALI-examples Document} \section{Changes from Previous Versions} -\subsection{WD-TAP-1.1-20170707} +\subsection{XX-TAP-1.1-XXXXXXXXXX} Added an example for \verb|examples|. +\subsection{WD-TAP-1.1-20170707} + Changed arraysize in TAP\_SCHEMA to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. Clarified required and optional ADQL geometric functions. From e37b4fcaa9c757a6877061d94bc2d428ec370ba3 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 11 Jul 2017 15:40:20 +0000 Subject: [PATCH 16/68] added Demleitner to author list --- TAP.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TAP.tex b/TAP.tex index c9e67da..60e4192 100644 --- a/TAP.tex +++ b/TAP.tex @@ -15,7 +15,7 @@ \ivoagroup{Data Access Layer Working Group} -\author{Patrick Dowler, Guy Rixon, Doug Tody} +\author{Patrick Dowler, Guy Rixon, Doug Tody, Markus Demleitner} \editor{Patrick Dowler} From 1828c1ba01d533c0296b7a74621e28bc92ed0702 Mon Sep 17 00:00:00 2001 From: Mark Taylor Date: Wed, 19 Jul 2017 22:55:21 +0000 Subject: [PATCH 17/68] tap: typos --- TAP.tex | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/TAP.tex b/TAP.tex index 60e4192..3014401 100644 --- a/TAP.tex +++ b/TAP.tex @@ -520,7 +520,7 @@ \subsubsection{LANG} The LANG parameter specifies the query language. The service must support the LANG parameter and the client must provide a value. The only standard -values for the LANG parameter is ADQL. Support for other +value for the LANG parameter is ADQL. Support for other languages and the LANG value to use with them is described in the service capabilities. @@ -559,7 +559,7 @@ \subsubsection{QUERY} Within the ADQL query, the service must support the use of timestamp values as described in \citep{std:DALI}. -Within the ADQL query, the following ADQL functions mus be supported: INTERSECTS, +Within the ADQL query, the following ADQL functions must be supported: INTERSECTS, CONTAINS, POINT, CIRCLE, and POLYGON. POINT (including a point-valued column or function return value) cannot be used as an argument to INTERSECTS (even if allowed by older versions of ADQL). @@ -626,7 +626,7 @@ \subsubsection{UPLOAD} UPLOAD parameter. The table-name(s) must be legal ADQL table names as defined in \citep{std:ADQL} but restricted as described in section~\ref{sec:tap-schema}. -URIs maybe be simple URLs (e.g. with a URI scheme of http or https) or +URIs may be simple URLs (e.g. with a URI scheme of http or https) or URIs that must be resolved (e.g. with a URI scheme of vos or param) to give the location of the table content. @@ -975,7 +975,7 @@ \subsection{Tables} The table\_type value must be either table or view. -The table\_index is used to recommended table ordering for clients. Clients +The table\_index is used to recommend table ordering for clients. Clients may order by table\_index (ascending) so lower index tables would appear earlier in a listing. @@ -1020,7 +1020,7 @@ \subsection{Columns} possible and must be null if arraysize represents a multi-dimensional or variable-length value. To use the size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the creation of the -TAP\_SCHEMA) use lower case exclusively). In the next major version +TAP\_SCHEMA) use lower case exclusively. In the next major version of TAP, the "size" column will be removed. For columns with a database type equivalent to BLOB or CLOB, most database systems support @@ -1030,12 +1030,12 @@ \subsection{Columns} URL(s) available as column values in the results, but do not actually store the URL(s) in the database, the column with URL(s) could be referenced in the SELECT clause of a query, but could not sensibly be used in the WHERE clause. In general, if a query references a column in an -inapprpriate part of the query, the job should fail with a suitable error message. +inappropriate part of the query, the job should fail with a suitable error message. -The “principal” flag indicates that the column is considered a core part the +The “principal” flag indicates that the column is considered a core part of the content; clients can use this hint to make the principal column(s) visible, for example by selecting them by default in generating an ADQL query. In cases where -the services selects the columns to return (such as a query language without an +the service selects the columns to return (such as a query language without an explicit output selection), the principal column indicates those columns that are returned by default. @@ -1198,7 +1198,7 @@ \subsubsection{Modify a Query Job Before Execution} \end{verbatim} or directly from the parameters resource: \begin{verbatim} -HTTP GET http://example.com/tap /async/42/parameters +HTTP GET http://example.com/tap/async/42/parameters \end{verbatim} Individual parameters cannot be accessed as separate web resources. @@ -1319,7 +1319,7 @@ \subsection{Example: Synchronous Query} QUERY=SELECT * FROM magnitudes as m where m.r>=10 and m.r<=16 \end{verbatim} -In this examples, the output format defaults to VOTable; +In this example, the output format defaults to VOTable; the FORMAT parameter could be added to select a different format. Many implementations will implement synchronous query execution using the From 4cc052f9ac3797677ee664eaa2421d0a07d79501 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 30 Aug 2017 17:42:56 +0000 Subject: [PATCH 18/68] updates from DAL-WG discussions and change to PR-TAP-1.1 --- Makefile | 4 +- TAP.tex | 226 ++++++++++++++++++++++--------------------------------- 2 files changed, 93 insertions(+), 137 deletions(-) diff --git a/Makefile b/Makefile index a895940..e5e79f3 100644 --- a/Makefile +++ b/Makefile @@ -7,10 +7,10 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2017-07-07 +DOCDATE = 2017-08-30 # What is it you're writing: NOTE, WD, PR, or REC -DOCTYPE = WD +DOCTYPE = PR # Source files for the TeX document (but the main file must always # be called $(DOCNAME).tex diff --git a/TAP.tex b/TAP.tex index 3014401..a2fc166 100644 --- a/TAP.tex +++ b/TAP.tex @@ -19,6 +19,7 @@ \editor{Patrick Dowler} +\previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{WD-TAP-1.1-20170707} \previousversion[http://www.ivoa.net/Documents/TAP/20160428/]{WD-TAP-1.1-20160428} \previousversion[http://www.ivoa.net/Documents/TAP/1.0]{TAP-1.0} @@ -156,9 +157,9 @@ \subsubsection{ADQL Queries} may include sufficient table metadata to enable queries to be written directly. \subsubsection{Other Query Languages} -A TAP service must be able to support use of other query languages, such +A TAP service implementor must be able to include support for other query languages, such pass-through of native SQL directly to an underlying DBMS or simple key-vale -(parameter-based) constraints. The service interface must allow for +(parameter-based) constraints, without making their service non-compliant with the specification. The service interface must allow for this and the service capabilities must be able to describe it. This mechanism also allows future developments within and outside the IVOA to be used without revising the TAP specification. @@ -204,8 +205,8 @@ \section{Resources} At least one set of {sync} and {async} resources must be named /sync and /async respectively for backwards compatibility with TAP-1.0 (which required -these names. Other {sync} and {async} resources may have service specific names. -As required by \citep{std:DALI}, all resources except the VOSI-availability must +these names). Other {sync} and {async} resources may have service specific names. +As required by \citep{std:DALI11}, all resources except the VOSI-availability must be siblings of the VOSI-capabilities resource. The fixed name resources above (async, sync, tables) should be used for the @@ -228,9 +229,9 @@ \subsection{\{sync\}} A TAP service must provide one or more web resources that represents the results of synchronous query execution. The {sync} resources must conform to the general rules for -DALI-sync \citep{std:DALI} resources. The exact form of the query, and hence the +DALI-sync \citep{std:DALI11} resources. The exact form of the query, and hence the representation of the resource, is defined by the query parameters as listed in -section~\ref{sec:parameters}. Representations of results of queries if defined in +section~\ref{sec:parameters}. Representations of results of queries is defined in section~\ref{sec:RESPONSEFORMAT} and section~\ref{sec:votable}. For query languages that produce a single result (e.g. ADQL) executed using the @@ -249,7 +250,7 @@ \subsection{\{async\}} A TAP service must provide one or more web resource representing controls for asynchronous queries. Specifically, the web resource must conform to the general rules -for DALI-async \citep{std:DALI} resources and thus represent a job-list +for DALI-async \citep{std:DALI11} resources and thus represent a job-list as specified in \citep{std:UWS}. The child web resources of the /async resource are as specified by UWS. These @@ -317,7 +318,7 @@ \subsection{\{async\}} \subsection{availability} \label{sec:vosi-availability} -The use of the VOSI-availability resource is described in \citep{std:DALI}. +The use of the VOSI-availability resource is described in \citep{std:DALI11}. \subsection{/capabilities} \label{sec:vosi-capabilities} @@ -346,7 +347,7 @@ \subsection{/capabilities} deliver the specified feature (e.g. with different authentication methods) in the VOSI-capabilities resource. -The use of the VOSI-capabilities resource is described in \citep{std:DALI}. +The use of the VOSI-capabilities resource is described in \citep{std:DALI11}. For example, the returned capabilities document for a service supporting TAP might look as follows: @@ -437,7 +438,7 @@ \subsection{/capabilities} The service capabilities must be accessible from a web resource with relative URL /capabilities that is a direct child of the root web resource. The /capabilities resource must be accessible via the http GET method. The content -is described by [8]. +is described by \citep{std:VOSI}. \subsection{/tables} \label{sec:vosi-tables} @@ -457,14 +458,14 @@ \subsection{/tables} \subsection{/examples} \label{sec:dali-examples} -A GET from this endpoint MUST yield a document with a MIME type of either +A successful GET from this endpoint MUST yield a document with a MIME type of either application/xhtml+xml or text/html. A service that does not provide examples MUST return a 404 HTTP status on accessing this resource. If present, the endpoint must be represented in a capability in the TAP service's registry record. The capability's \xmlel{standardID} is defined by DALI -\citep{std:DALI}. A capability element could hence look like this: +\citep{std:DALI11}. A capability element could hence look like this: \begin{lstlisting}[language=XML,basicstyle=\footnotesize] @@ -478,12 +479,12 @@ \subsection{/examples} \begin{itemize} \item query -- each example MUST have a unique child element with simple text -content having a \xmlel{property} attribute valued query. It contains the query itself, +content having a \xmlel{property} attribute valued {\em query}. It contains the query itself, preferably with extra whitespace for easy human consumption and editing. This will usually be a HTML \xmlel{pre} element. \item table -- examples MAY also have descendants with \xmlel{property} attributes having -the value table. These must have pure text content and contain fully qualified +the value {\em table}. These must have pure text content and contain fully qualified table names to which the query is somehow ``pertaining''. \end{itemize} @@ -509,8 +510,7 @@ \subsection{Parameters} queries may be created with with no parameters and multiple, subsequent HTTP POST actions may specify the parameters in any order. -Not all combinations of the parameters are meaningful. For example, if a request -carries LANG=ADQL then the SELECT parameter (from PQL) is spurious. If a +Not all combinations of the parameters are meaningful. If a service receives a spurious parameter in an otherwise correct request, then the service must ignore the spurious parameter, must respond to the request normally and must not report errors concerning the spurious parameter. @@ -529,10 +529,10 @@ \subsubsection{LANG} LANG=ADQL QUERY= \end{verbatim} -A PQL query would be performed with +A query with a custom query language would be performed with \begin{verbatim} -LANG=PQL - +LANG=MySecretLang + \end{verbatim} The value of LANG is a string specifying the language and optionally the language version used for the query parameter(s), as defined by the service @@ -545,24 +545,21 @@ \subsubsection{LANG} \subsubsection{QUERY} \label{sec:QUERY} -The QUERY parameter is used to specify the ADQL query. It may also be used to +The QUERY parameter is used to specify queries that are serialised as a single character string, such as an ADQL query (with LANG=ADQL or some version thereof). The interpretation +of the value depends on the value of the LANG parameter. This parameter should also be used to specify the query for other values of LANG (e.g. LANG=) which are not specified in this document but may be described in the -service capabilities. +variant>) when appropriate. -A service must support the QUERY parameter because ADQL is a required language. -The case sensitivity of the query string is defined solely by the query language -specification. In the case of ADQL 2.0, for example, the query is not case -sensitive except for character literals; schema, table, and column names, -function names, and other ADQL keywords are not case sensitive. +A service must support the QUERY parameter because ADQL is a required language. Within the ADQL query, the service must support the use of timestamp values as -described in \citep{std:DALI}. +described in \citep{std:DALI11} if applicable. Timestamp values are usable if there +are columns with timestamp values, including in uploaded tables if table upload +is supported. -Within the ADQL query, the following ADQL functions must be supported: INTERSECTS, -CONTAINS, POINT, CIRCLE, and POLYGON. POINT (including a point-valued column or -function return value) cannot be used as an argument to INTERSECTS (even if allowed -by older versions of ADQL). +If the tables that are queried through a service contain columns with spatial +coordinates, the service should implement ADQL geometric query support by enabling +the following functions in ADQL queries: INTERSECTS, CONTAINS, POINT, CIRCLE, and POLYGON. AREA, CENTROID, COORDSYS, COORD1, and COORD2 are optional. REGION is no longer supported. @@ -571,13 +568,13 @@ \subsubsection{QUERY} values. For example, POINT('ICRS', t.ra, t.dec) does not cause t.ra and t.dec to be transformed to ICRS; it simply tells the service to treat the values as being expressed in that coordinate system. Clients should avoid using the coordinate -system argument to geometric functions should not be used (use null value or use an +system argument to geometric functions (use null value or use an alternate function without the coordinate system argument if available). \subsubsection{FORMAT and RESPONSEFORMAT} \label{sec:RESPONSEFORMAT} -The RESPONSEFORMAT parameter is fully described in \citep{std:DALI}. For +The RESPONSEFORMAT parameter is fully described in \citep{std:DALI11}. For backwards compatibility, TAP-1.1 must also accept the FORMAT parameter as equivalent to RESPONSEFORMAT. @@ -586,7 +583,7 @@ \subsubsection{MAXREC} \label{sec:MAXREC} The MAXREC parameter and its effect on the query result is fully described in -\citep{std:DALI}. If the result set is truncated in this fashion, it must +\citep{std:DALI11}. If the result set is truncated in this fashion, it must include an overflow indicator as specified in section~\ref{sec:query-overflow}. For the special value of MAXREC=0, the service is not required to execute the @@ -615,12 +612,12 @@ \subsubsection{MAXREC} indicator. \subsubsection{RUNID} -The RUNID parameter is fully described in \citep{std:DALI}. +The RUNID parameter is fully described in \citep{std:DALI11}. \subsubsection{UPLOAD} \label{sec:UPLOAD} -The UPLOAD parameter is described in \citep{std:DALI}. Services should support +The UPLOAD parameter is described in \citep{std:DALI11}. Services should support the upload of temporary tables (in \citep{std:VOTable} format) via the standard UPLOAD @@ -641,7 +638,7 @@ \subsubsection{UPLOAD} be used behind the scenes) and are never visible in the TAP\_SCHEMA metadata. -The \citep{std:DALI} UPLOAD parameter supports both external resources and +The \citep{std:DALI11} UPLOAD parameter supports both external resources and in-line content. For external resources, one provides a URI (usually an HTTP URL) the TAP service can use to obtain the table content. For example, @@ -684,39 +681,12 @@ \section{Use of VOTable} The \citep{std:VOTable} format is the standard format for output (query results) and input (table upload) in a TAP service so most of this section deals with how VOTable is used. However, rules about serialising column values -also apply to other formats (e.g. CSV and TSV). +also apply to other formats (e.g. CSV and TSV). \subsection{INFO elements} \label{sec:vot-info} -The RESOURCE element must contain an INFO element with attribute -name="QUERY\_STATUS" indicating the success of the operation. For -RESOURCE elements that contain a TABLE element, this INFO element must appear -lexically before the TABLE. The following values are defined for this INFO -element's value attribute: - -“OK”, meaning that the query executed successfully and a result table is -included in the resource - -"ERROR”, meaning that an error was detected at the level of the TAP -protocol or the query failed to execute - -The content of the INFO element conveying the status should be a message -suitable for display to the user describing the status. - -\begin{verbatim} - -\end{verbatim} - -\begin{verbatim} -Successful query -\end{verbatim} - -\begin{verbatim} - - value out of range in POS=45,91 - -\end{verbatim} +The RESOURCE element must contain INFO element(s) as described in \citep{std:DALI11}. Additional INFO elements may be provided, e.g., to echo the input parameters back to the client in the query response (a useful feature for debugging or to @@ -724,50 +694,15 @@ \subsection{INFO elements} \begin{verbatim} - - unrecognized operation - - - - - - -\end{verbatim} - -If an overflow occurs (result exceeds MAXREC), the service must close the table -and append another INFO element to the RESOURCE (after the TABLE) with -name=”QUERY\_STATUS” and the value=”OVERFLOW”. -\begin{verbatim} - - ... -...
- - -\end{verbatim} - -In the above example, the TABLE should have exactly MAXREC rows. - -If an error occurs while writing the rows of the VOTable, the service must -close the table and append another INFO element to the RESOURCE, after the -TABLE, with name=”QUERY\_STATUS” and the value=”ERROR”. -\begin{verbatim} - - + + select * from stuff.items + ... -...
- \end{verbatim} -The content of these trailing INFO elements is optional and intended for users; -client software should not depend on it. -Thus, one INFO element with name=”QUERY\_STATUS” and value=”OK” or -value=”ERROR” must be included before the TABLE. If the TABLE does not contain -the entire query result, one INFO element with value=”OVERFLOW” or -value=”ERROR” must be included after the table. +Additional INFO elements after the results may also be included as specified in \citep{std:DALI11}. \subsection{Successful Queries} \label{sec:query-ok} @@ -784,7 +719,8 @@ \subsection{Successful Queries} the query) in the query and the datatype, arraysize, and xtype attributes of FIELD elements must be set using the values from the TAP\_SCHEMA. In cases where items in the select list do not -have names (e.g. function invocation) the service must generate a name; +have names (e.g. expression or function invocation without an alias) the service +must generate a name; generated names must be unique (within the output table) and should be valid ADQL identifiers. @@ -833,7 +769,7 @@ \subsection{Errors} error if the client is not allowed to access the resource. Error documents should be in a format that matches the requested -format where possible; see DALI \citep{std:DALI} for details. +format where possible; see DALI \citep{std:DALI11} for details. If the error document is being retrieved from the /async//error resource (specified by UWS) after an asynchronous query, the HTTP status code should be 200. If the error document is being @@ -866,24 +802,21 @@ \subsection{Mapping Table Datatypes} This section describes the bi-directional mapping between VOTable and RDBMS + geometric datatypes and extends the basic rules for serialising such values in -VOTable described in \citep{std:DALI}. These rules apply to input tables +VOTable described in \citep{std:DALI11}. These rules apply to input tables supplied via an UPLOAD parameter (see section~\ref{sec:UPLOAD}) and to result tables after successful query execution. For input tables, the name attribute of the FIELD element is used as the column name. Services must support delimited identifiers so that FIELD names that are not valid ADQL column names work correctly -\citep{std:ADQL}. -For result tables, the column name or an alias specified in the query is used -to set the name attribute of the FIELD elements in the output table (the alias -overrides the normal column name). +\citep{std:ADQL}. The mapping to and from VOTable makes use of the datatype, arraysize, and xtype attributes. Mapping for primitive types (numbers and strings) is straightforward; services should insure that input values behave as expected in query processing and output values should have correct and complete metadata. Mapping for specially structured values use xtype(s) specified -in \citep{std:DALI}. The behaviour of such structured values in queries depends +in \citep{std:DALI11}. The behaviour of such structured values in queries depends on the query language (section~\ref{sec:LANG}) being used. \section{Metadata: TAP\_SCHEMA} @@ -913,17 +846,14 @@ \section{Metadata: TAP\_SCHEMA} metadata is defined by the service. Services must provide these tables and make them accessible by all supported query mechanisms. -The qualified names in the tables of the TAP schema must follow the rules -defined in section 2.4. The names must be stated in a form that is acceptable as -an operand of a query. - Column datatypes in the TAP\_SCHEMA are specified using the same concepts used in VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors must also include the "size" column and populate it where possible. The arraysize values specified below for describing the TAP\_SCHEMA tables themselves is the most flexible (* means variable length with no maximum); implementors should use more restrictive values that describe their implementation of the TAP\_SCHEMA tables (e.g. arraysize 64* to describe -a column with database type varchar(64)). +a column with database type varchar(64)). Implementors may also use alternate character or numeric types (e.g. short or long instead of int or unicodeChar instead of char) as long as +query execution is consistent with the recommended types. Implementors are permitted to include additional tables in the TAP\_SCHEMA to describe additional aspects of their service not @@ -962,7 +892,7 @@ \subsection{Tables} table\_type & char & * & null & true \\ utype & char & * & null & false \\ description & char & * & null & false \\ -table\_index & char & * & null & false \\ +table\_index & int & 1 & null & false \\ \end{tabular} The table\_name values must be unique. The value of the @@ -996,9 +926,9 @@ \subsection{Columns} utype & char & * & null & false \\ unit & char & * & null & false \\ ucd & char & * & null & false \\ -indexed & boolean & 1 & null & true \\ -principal & boolean & 1 & null & true \\ -std & boolean & 1 & null & true \\ +indexed & int & 1 & null & true \\ +principal & int & 1 & null & true \\ +std & int & 1 & null & true \\ column\_index & int & 1 & null & false \\ \end{tabular} @@ -1009,7 +939,7 @@ \subsection{Columns} table using three (3) columns with an additional (deprecated) column from TAP-1.0 for backwards compatibility. The allowed values for datatype and the syntax for arraysize are specified in VOTable \citep{std:VOTable}. Values for xtype are not restricted per se but -implementors should use standard values such as those defined in DALI \citep{std:DALI} before +implementors should use standard values such as those defined in DALI \citep{std:DALI11} before inventing new xtype(s). The arraysize column gives the length of variable length datatypes using the VOTable @@ -1017,7 +947,7 @@ \subsection{Columns} described with datatype "char" and arraysize "256*". Arrays, including multi-dimensional arrays, are permitted for all VOTable primitive types. The "size" column is retained for backwards compatibility to TAP-1.0 and must contain the integer value equivalent to arraysize when -possible and must be null if arraysize represents a multi-dimensional or variable-length value. +possible and must be null if arraysize represents a multi-dimensional. To use the size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the creation of the TAP\_SCHEMA) use lower case exclusively. In the next major version @@ -1093,8 +1023,9 @@ \section{Examples} \label{sec:examples} The UWS pattern is specified in \citep{std:UWS} and its application to TAP in -section -section~\ref{sec:tap-async}. This section gives examples of the exchange of messages between a +section section~\ref{sec:tap-async}. TAP services may implement \citep{std:UWS} or +a later version. +This section gives examples of the exchange of messages between a TAP client and service when using UWS to run an asynchronous query. \subsection{Example: Asynchronous Query} @@ -1138,8 +1069,9 @@ \subsubsection{Creating and Executing a Simple Query} \end{verbatim} The client may have to check the phase multiple times until the job -finishes. Once the returned value is COMPLETED, the results can be obtained -from the results resource: +finishes. If the service implements \citep{std:UWS11} or later, a blocking call +can be used instead of polling. Once the job reaches the COMPLETED phase, +the results can be obtained from the results resource: \begin{verbatim} HTTP GET http://example.com/tap/async/42/results/result @@ -1162,7 +1094,7 @@ \subsubsection{Modify a Query Job Before Execution} While the job is in the PENDING phase, the job parameters may be modified by additional POST(s) to the parameters resource (see -\citep{std:DALI}), for example: +\citep{std:DALI11}), for example: \begin{verbatim} HTTP POST http://example.com/tap/async/42/parameters @@ -1179,7 +1111,7 @@ \subsubsection{Modify a Query Job Before Execution} Parameter-value pairs accumulate when POSTed to the parameters resource, so an additional POST of the UPLOAD parameter in this example would add another parameter-value pair (essentially a multi-valued parameter as described in -\citep{std:DALI}). There is no mechanism to replace or remove a parameter in a +\citep{std:DALI11}). There is no mechanism to replace or remove a parameter in a PENDING job. After each such POST, the service issues an HTTP redirection to the job's URL, @@ -1190,7 +1122,6 @@ \subsubsection{Modify a Query Job Before Execution} Location: http://example.com/tap/async/42 \end{verbatim} - All TAP-specific parameters are stored using the parameter list mechanism of UWS and are included in the XML representation of the job: \begin{verbatim} @@ -1268,10 +1199,20 @@ \subsubsection{Running a Query} \end{verbatim} The phase will now have changed to either QUEUED or EXECUTING, depending on the service implementation. The client tracks the execution by polling the phase -URL: +URL (UWS-1.0): \begin{verbatim} HTTP GET http://example.com/tap/async/42/phase \end{verbatim} +or by performing a blocking GET ofthe jon (UWS-1.1 or later): +\begin{verbatim} +HTTP GET http://example.com/tap/async/42?WAIT=30 +\end{verbatim} +The blocking GET will block until something changes in the job (usually the phase +change) and then return, with a maximum wait time specified by the WAIT parameter. Since +services may impose a limit on the maximum wait time and may return before ten job reaches +a final phase, clients must examine the job state (returned by the GET) and possibly perform +additional requests. + A job in the QUEUED or EXECUTING phase may be aborted by posting to the phase URL: \begin{verbatim} @@ -1331,7 +1272,7 @@ \subsection{Example: Synchronous Query} Location: http://example.com/tap/sync/53/go \end{verbatim} -As described in \citep{std:DALI}, clients must be prepared to follow such +As described in \citep{std:DALI11}, clients must be prepared to follow such redirects to obtain the result. \subsection{Example: DALI-examples Document} @@ -1349,10 +1290,25 @@ \subsection{Example: DALI-examples Document} \section{Changes from Previous Versions} -\subsection{XX-TAP-1.1-XXXXXXXXXX} +\subsection{PR-TAP-1.1-20170830} Added an example for \verb|examples|. +Clarified that the QUERY param is intended for use with other values of LANG and is not +reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. + +Removed remaining uses of PQL; replaced one example with something more clearly non-standard. + +Removed restriction from previous WD that the "size" column must be null for variable length arrays. In fact, "size" can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column. + +Changed language about mandatory ADQL geometry function support back to optional (should in +the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. + +Removed some VOTable content and reference DALI. Explicitly relaxed datatype and +arraysize used in TAP\_SCHEMA tables. Fixed various cross-references and typos. + +Added example use of UWS-1.1 blocking requests. + \subsection{WD-TAP-1.1-20170707} Changed arraysize in TAP\_SCHEMA to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. From 12abc6805f40e4d92ba2b97329d29eec5b28c3d9 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Fri, 8 Sep 2017 09:31:48 +0000 Subject: [PATCH 19/68] Adding text on related standards. also, fixing duplicate tap:tap_resources labels --- TAP.tex | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/TAP.tex b/TAP.tex index a2fc166..dde2bf4 100644 --- a/TAP.tex +++ b/TAP.tex @@ -11,6 +11,8 @@ showstringspaces=False} \usepackage[utf8]{inputenc} +\hyphenation{asyn-chro-n-ous-ly} + \title{Table Access Protocol} \ivoagroup{Data Access Layer Working Group} @@ -112,6 +114,58 @@ \subsection{Role within the VO Architecture} Fig.~section~\ref{fig:archdiag} shows the role this document plays within the IVOA architecture \citep{note:VOARCH}. +TAP depends on the following other IVOA standards: + +\begin{description} + +\item[UWS \citep{2016ivoa.spec.1024H}] TAP services can be queried +asynchronously; the Universal Worker Service UWS defines the +corresponding communication pattern. Note that while TAP 1.1 does not +require the use of any particular minor version of the standards it +depends on, UWS 1.1 can significantly streamline the communication, and +implementors of TAP 1.1 are encouraged to support UWS 1.1 or later. + +\item[ADQL \citep{2008ivoa.spec.1030O}] A standards-compliant TAP +services must support queries written in the Astronomical Data Query +Language. + +\item[VOSI \citep{std:VOSI11}] The VO Support Interfaces standard +defines endpoints for metadata discovery; for TAP, this is the tables, +capabilities, and availability endpoints. + +\item[VOTable \citep{2013ivoa.spec.0920O}] All TAP services must be able +to serve query results in the VOTable format. +\end{description} + + +TAP is related in other ways to the following IVOA standards: + +\begin{description} +\item[DALI \citep{std:DALI11}] The Data Access Layer Interface standard +gives general rules for the construction of DAL standards. TAP has been +written against version 1.1 of DALI. In particular, TAP directly +references DALI 1.1's serialisation rules for geometries and timestamps +and recommends implementing the examples endpoint defined by DALI. + +\item[Obscore \citep{2011ivoa.spec.1028T}] The Obscore data model +facilitates the publication of metadata of observational data products. +TAP is used to access compliant metadata collections. + +\item[RegTAP \citep{2014ivoa.spec.1208D}] The relational model for the +VO Registry provides a data model for publishing service metadata. +TAP is used to access compliant metadata collections. + +\item[TAPRegExt \citep{2012ivoa.spec.0827D}] While there is no formal +requirement to that effect, the response on a TAP service's capabilities +endpoint should contain instances \xmlel{tr:TableAccess}-typed +capabilities in order to allow clients to discover several important +aspects of a TAP service's capabilities (e.g., resource limits, output +formats, user defined functions). + +\end{description} + + + \subsection{Motivating Use Cases} Below are some of the more common use cases that have motivated the development of the TAP specification. While this is not complete, it helps to understand the @@ -867,7 +921,7 @@ \subsection{Schemas} The table TAP\_SCHEMA.schemas must contain the following columns: \begin{tabular}{l l l l l} -\label{tab:resources} +\label{tab:tap_schema} \textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ schema\_name & char & * & null & true \\ utype & char & * & null & false \\ @@ -1383,7 +1437,7 @@ \subsection{Changes from TAP-1.0} fixed paths /async and /sync are still required and are to provide anonymous query access, which should be compatible with existing services. -\bibliography{ivoatex/ivoabib} +\bibliography{ivoatex/ivoabib,ivoatex/docrepo} \end{document} From 4dd1003f87ce48538c0f1d1b85e0ff83380c2426 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Mon, 11 Sep 2017 08:45:22 +0000 Subject: [PATCH 20/68] TAP: Improving table markup. Also, removing labels within tabular environments, as these environments don't support labels (table environments do, though) --- TAP.tex | 64 ++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 45 insertions(+), 19 deletions(-) diff --git a/TAP.tex b/TAP.tex index dde2bf4..ebc241d 100644 --- a/TAP.tex +++ b/TAP.tex @@ -240,22 +240,28 @@ \section{Resources} An implementation of a TAP service provides the following RESTful resources under the base URL. -\begin{tabular}{l l l l l} -\label{tab:resources} +\medskip +\begin{inlinetable} +\begin{tabular}{l l l} +\sptablerule \textbf{resource type} & \textbf{resource name} & \textbf{required} \\ -{sync} & /sync & must & \\ -{async} & /async & must & \\ -{sync} & service specific & may (alternate authentication method) & \\ -{async} & service specific & may (alternate authentication method) & \\ -VOSI-availability & service specific & must (should be anonymous) & \\ -VOSI-availability & service specific & may (alternate authentication method) & \\ -VOSI-capabilities & /capabilities & must (should be anonymous) & \\ -VOSI-capabilities & service specific & may (alternate authentication method) & \\ -VOSI-tables & /tables & should & \\ -VOSI-tables & service specific & may (alternate authentication method) & \\ -DALI-examples & /examples & should & \\ -DALI-examples & service specific & may (alternate authentication method) & \\ +\sptablerule +{sync} & /sync & must \\ +{async} & /async & must \\ +{sync} & service specific & may (alternate authentication method) \\ +{async} & service specific & may (alternate authentication method) \\ +VOSI-availability & service specific & must (should be anonymous) \\ +VOSI-availability & service specific & may (alternate authentication method) \\ +VOSI-capabilities & /capabilities & must (should be anonymous) \\ +VOSI-capabilities & service specific & may (alternate authentication method) \\ +VOSI-tables & /tables & should \\ +VOSI-tables & service specific & may (alternate authentication method) \\ +DALI-examples & /examples & should \\ +DALI-examples & service specific & may (alternate authentication method) \\ +\sptablerule \end{tabular} +\end{inlinetable} +\medskip At least one set of {sync} and {async} resources must be named /sync and /async respectively for backwards compatibility with TAP-1.0 (which required @@ -920,13 +926,17 @@ \subsection{Schemas} The table TAP\_SCHEMA.schemas must contain the following columns: +\begin{inlinetable} \begin{tabular}{l l l l l} -\label{tab:tap_schema} +\sptablerule \textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\sptablerule schema\_name & char & * & null & true \\ utype & char & * & null & false \\ description & char & * & null & false \\ +\sptablerule \end{tabular} +\end{inlinetable} The schema\_name values must be unique and may be qualified by the catalog name or not depending on the implementation requirements. The fully @@ -938,16 +948,20 @@ \subsection{Tables} \label{sec:tap-schema-tables} The table TAP\_SCHEMA.tables must contain the following columns: +\begin{inlinetable} \begin{tabular}{l l l l l} -\label{tab:tap-schema-tables} +\sptablerule \textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\sptablerule schema\_name & char & * & null & true \\ table\_name & char & * & null & true \\ table\_type & char & * & null & true \\ utype & char & * & null & false \\ description & char & * & null & false \\ table\_index & int & 1 & null & false \\ +\sptablerule \end{tabular} +\end{inlinetable} The table\_name values must be unique. The value of the table\_name should be the string that is recommended for use in @@ -967,9 +981,11 @@ \subsection{Columns} \label{sec:tap-schema-columns} The table TAP\_SCHEMA.columns must contain the following columns: +\begin{inlinetable} \begin{tabular}{l l l l l} -\label{tab:tap-schema-columns} +\sptablerule \textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\sptablerule table\_name & char & * & null & true \\ column\_name & char & * & null & true \\ datatype & char & * & null & true \\ @@ -984,7 +1000,9 @@ \subsection{Columns} principal & int & 1 & null & true \\ std & int & 1 & null & true \\ column\_index & int & 1 & null & false \\ +\sptablerule \end{tabular} +\end{inlinetable} The table\_name,column\_name (pair) values must be unique. @@ -1040,15 +1058,19 @@ \subsection{Foreign Keys} The table TAP\_SCHEMA.keys must contain the following columns to describe foreign key relations between tables: +\begin{inlinetable} \begin{tabular}{l l l l l} -\label{tab:tap-schema-keys} +\sptablerule \textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\sptablerule key\_id & char & * & null & true \\ from\_table & char & * & null & true \\ target\_table & char & * & null & true \\ description & char & * & null & false \\ utype & char & * & null & false \\ +\sptablerule \end{tabular} +\end{inlinetable} The key\_id values are unique and used only to join with the TAP\_SCHEMA.key\_columns table below. There may be @@ -1058,13 +1080,17 @@ \subsection{Foreign Keys} The table TAP\_SCHEMA.key\_columns must contain the following columns to describe the columns that make up a foreign key: +\begin{inlinetable} \begin{tabular}{l l l l l} -\label{tab:tap-schema-key-columns} +\sptablerule \textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\sptablerule key\_id & char & * & null & true \\ from\_column & char & * & null & true \\ target\_column & char & * & null & true \\ +\sptablerule \end{tabular} +\end{inlinetable} There may be one or more rows with a specific key\_id to denote single or multi-column keys. From 49aaa3f536e32db531964cdcf6b3aed65cfbdcb9 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Mon, 11 Sep 2017 08:56:48 +0000 Subject: [PATCH 21/68] TAP: Improving listing markup (smaller base font where necessary, line breaks to avoid overfull hboxes) Also removing a spurious xmlns="" and an unnecessary XML declaration. --- TAP.tex | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/TAP.tex b/TAP.tex index ebc241d..8b20f3d 100644 --- a/TAP.tex +++ b/TAP.tex @@ -412,9 +412,7 @@ \subsection{/capabilities} For example, the returned capabilities document for a service supporting TAP might look as follows: -\begin{lstlisting}[language=XML] - - +\begin{lstlisting}[language=XML,basicstyle=\footnotesize] https://example.net/myTAP - + @@ -441,11 +439,13 @@ \subsection{/capabilities} http://example.net/myTAP/auth-async - + https://example.net/myTAP/async - + @@ -455,11 +455,12 @@ \subsection{/capabilities} http://example.net/myTAP/auth-sync - + https://example.net/myTAP/sync - + @@ -484,11 +485,14 @@ \subsection{/capabilities} https://myarchive.net/myTAP/tables - + - http://myarchive.net/myTAP/auth-tables - + http://myarchive.net/myTAP/auth-tables + @@ -530,7 +534,8 @@ \subsection{/examples} \begin{lstlisting}[language=XML,basicstyle=\footnotesize] - http://myarchive.net/myTAP/examples + http://myarchive.net/myTAP/examples \end{lstlisting} @@ -1179,8 +1184,8 @@ \subsubsection{Modify a Query Job Before Execution} \begin{verbatim} HTTP POST http://example.com/tap/async/42/parameters UPLOAD=mytable,http://a.b.c/mytable.xml -QUERY=select * from TAP_UPLOAD.mytable t join magnitudes m on t.target = -m.target +QUERY=select * from TAP_UPLOAD.mytable t join magnitudes + m on t.target = m.target \end{verbatim} Here we have specified with the UPLOAD parameter that the service create a From dbb857dfa79b0aed6f4deea56e43f30afc799131 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Mon, 11 Sep 2017 09:05:47 +0000 Subject: [PATCH 22/68] Externalising capability example so it's easier to validate. capability within vosi:capaiblites is unqualified. Fixing in example. Now using VODataService 1.1 namespace and schema in the sample capability (1.0 has never reached REC). Also, fixing a few (unbound) vod: prefixes to (correct) vs: ones. --- Makefile | 2 +- TAP.tex | 88 +------------------------------------------ sample-capability.xml | 85 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 88 insertions(+), 87 deletions(-) create mode 100644 sample-capability.xml diff --git a/Makefile b/Makefile index e5e79f3..70b249b 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ DOCTYPE = PR # Source files for the TeX document (but the main file must always # be called $(DOCNAME).tex -SOURCES = $(DOCNAME).tex examples-sample.html +SOURCES = $(DOCNAME).tex examples-sample.html sample-capability.xml # List of pixel image files to be included in submitted package FIGURES = archdiag.png diff --git a/TAP.tex b/TAP.tex index 8b20f3d..b3f93db 100644 --- a/TAP.tex +++ b/TAP.tex @@ -412,92 +412,8 @@ \subsection{/capabilities} For example, the returned capabilities document for a service supporting TAP might look as follows: -\begin{lstlisting}[language=XML,basicstyle=\footnotesize] - - - - - http://example.net/myTAP - - - https://example.net/myTAP - - - - - - - - http://example.net/myTAP/async - - - http://example.net/myTAP/auth-async - - - - https://example.net/myTAP/async - - - - - - - http://example.net/myTAP/sync - - - http://example.net/myTAP/auth-sync - - - - https://example.net/myTAP/sync - - - - - - - - http://example.net/myTAP/capabilities - - - - - - - http://example.net/myTAP/availability - - - - - - - http://myarchive.net/myTAP/tables - - - https://myarchive.net/myTAP/tables - - - - http://myarchive.net/myTAP/auth-tables - - - - - -\end{lstlisting} +\begin{lstinputlisting}[language=XML,basicstyle=\footnotesize] + {sample-capability.xml} The service capabilities must be accessible from a web resource with relative URL /capabilities that is a direct child of the root web resource. The diff --git a/sample-capability.xml b/sample-capability.xml new file mode 100644 index 0000000..84aedea --- /dev/null +++ b/sample-capability.xml @@ -0,0 +1,85 @@ + + + + + http://example.net/myTAP + + + https://example.net/myTAP + + + + + + + + http://example.net/myTAP/async + + + http://example.net/myTAP/auth-async + + + + https://example.net/myTAP/async + + + + + + + http://example.net/myTAP/sync + + + http://example.net/myTAP/auth-sync + + + + https://example.net/myTAP/sync + + + + + + + + http://example.net/myTAP/capabilities + + + + + + + http://example.net/myTAP/availability + + + + + + + http://myarchive.net/myTAP/tables + + + https://myarchive.net/myTAP/tables + + + + http://myarchive.net/myTAP/auth-tables + + + + + From 9256fcc2132a11dbe88a77b92676cf2ce04984aa Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 12 Sep 2017 12:55:17 +0000 Subject: [PATCH 23/68] Increasing the use of abbreviations instead of citep to reference other standards. --- TAP.tex | 93 +++++++++++++++++++++++-------------------- sample-capability.xml | 2 +- 2 files changed, 50 insertions(+), 45 deletions(-) diff --git a/TAP.tex b/TAP.tex index b3f93db..fcdc755 100644 --- a/TAP.tex +++ b/TAP.tex @@ -34,7 +34,7 @@ Access is provided for both database and table metadata as well as for actual table data. This version of the protocol includes support for multiple query languages, including queries specified using the Astronomical Data Query -Language \citep{std:ADQL} within an integrated interface. It also includes +Language ADQL within an integrated interface. It also includes support for both synchronous and asynchronous queries. Special support is provided for spatially indexed queries using the spatial extensions in ADQL. A multi-position @@ -74,7 +74,7 @@ \section{Introduction} return the query response as another table, in accord with the relational model. Queries may be submitted using various query languages and may execute synchronously or asynchronously. Support for the Astronomical Data Query -Language \citep{std:ADQL} is mandatory; support for other query languages is +Language ADQL \citep{std:ADQL} is mandatory; support for other query languages is supported but optional. @@ -199,7 +199,7 @@ \subsubsection{Query Standard Data Models} elements are mapped to tables and columns. \subsubsection{ADQL Queries} -The Astronomical Data Query Language \citep{std:ADQL} is the standard +The Astronomical Data Query Language ADQL \citep{std:ADQL} is the standard query language for the IVOA. Support for ADQL queries is mandatory. ADQL can be used to specify queries that access one or more tables provided by the TAP service, including the standard metadata tables. In general, the client must @@ -266,7 +266,7 @@ \section{Resources} At least one set of {sync} and {async} resources must be named /sync and /async respectively for backwards compatibility with TAP-1.0 (which required these names). Other {sync} and {async} resources may have service specific names. -As required by \citep{std:DALI11}, all resources except the VOSI-availability must +As required by DALI \citep{std:DALI11}, all resources except the VOSI-availability must be siblings of the VOSI-capabilities resource. The fixed name resources above (async, sync, tables) should be used for the @@ -289,7 +289,7 @@ \subsection{\{sync\}} A TAP service must provide one or more web resources that represents the results of synchronous query execution. The {sync} resources must conform to the general rules for -DALI-sync \citep{std:DALI11} resources. The exact form of the query, and hence the +DALI-sync resources. The exact form of the query, and hence the representation of the resource, is defined by the query parameters as listed in section~\ref{sec:parameters}. Representations of results of queries is defined in section~\ref{sec:RESPONSEFORMAT} and section~\ref{sec:votable}. @@ -310,8 +310,8 @@ \subsection{\{async\}} A TAP service must provide one or more web resource representing controls for asynchronous queries. Specifically, the web resource must conform to the general rules -for DALI-async \citep{std:DALI11} resources and thus represent a job-list -as specified in \citep{std:UWS}. +for DALI-async resources and thus represent a job-list +as specified in UWS \citep{std:UWS}. The child web resources of the /async resource are as specified by UWS. These are descendants of the /async web-resource, and they include a web resource that @@ -378,7 +378,7 @@ \subsection{\{async\}} \subsection{availability} \label{sec:vosi-availability} -The use of the VOSI-availability resource is described in \citep{std:DALI11}. +The use of the VOSI-availability resource is described in DALI. \subsection{/capabilities} \label{sec:vosi-capabilities} @@ -407,18 +407,18 @@ \subsection{/capabilities} deliver the specified feature (e.g. with different authentication methods) in the VOSI-capabilities resource. -The use of the VOSI-capabilities resource is described in \citep{std:DALI11}. +The use of the VOSI-capabilities resource is described in DALI. For example, the returned capabilities document for a service supporting TAP might look as follows: -\begin{lstinputlisting}[language=XML,basicstyle=\footnotesize] +\lstinputlisting[language=XML,basicstyle=\footnotesize] {sample-capability.xml} The service capabilities must be accessible from a web resource with relative URL /capabilities that is a direct child of the root web resource. The /capabilities resource must be accessible via the http GET method. The content -is described by \citep{std:VOSI}. +is described by VOSI \citep{std:VOSI}. \subsection{/tables} \label{sec:vosi-tables} @@ -426,7 +426,7 @@ \subsection{/tables} The table metadata should be accessible from a web resource with relative URL /tables that is a direct child of the root web resource. The /tables resource must be accessible via the http GET method. The content is described by -\citep{std:VODS11} and is equivalent to the metadata from the +VOSI and is equivalent to the metadata from the TAP\_SCHEMA described in section~\ref{sec:tap-schema}. The use of VOTableType (rather than TAPType) in the VOSI-tables output is recommended because the values map directly; TAPType may be used when VOTableType does not provide a suitable @@ -444,8 +444,7 @@ \subsection{/examples} If present, the endpoint must be represented in a capability in the TAP service's registry record. The capability's \xmlel{standardID} is defined by -DALI -\citep{std:DALI11}. A capability element could hence look like this: +DALI. A capability element could hence look like this: \begin{lstlisting}[language=XML,basicstyle=\footnotesize] @@ -474,6 +473,9 @@ \subsection{/examples} descriptions). As discussed in DALI 1.1, sect.~2.3, this would result in invalid RDF statements. +An example of a response from a TAP service's examples endpoint is given +in section~\ref{sect:example-example}. + \subsection{Parameters} \label{sec:parameters} @@ -502,8 +504,9 @@ \subsubsection{LANG} The LANG parameter specifies the query language. The service must support the LANG parameter and the client must provide a value. The only standard value for the LANG parameter is ADQL. Support for other -languages and the LANG value to use with them is described in the service -capabilities. +languages and the LANG value to use with them can be described in +TAPRegExt service +capabilities \citep{2012ivoa.spec.0827D}. For example, an ADQL query would be performed with \begin{verbatim} @@ -534,7 +537,7 @@ \subsubsection{QUERY} A service must support the QUERY parameter because ADQL is a required language. Within the ADQL query, the service must support the use of timestamp values as -described in \citep{std:DALI11} if applicable. Timestamp values are usable if there +described in DALI if applicable. Timestamp values are usable if there are columns with timestamp values, including in uploaded tables if table upload is supported. @@ -555,7 +558,7 @@ \subsubsection{QUERY} \subsubsection{FORMAT and RESPONSEFORMAT} \label{sec:RESPONSEFORMAT} -The RESPONSEFORMAT parameter is fully described in \citep{std:DALI11}. For +The RESPONSEFORMAT parameter is fully described in DALI. For backwards compatibility, TAP-1.1 must also accept the FORMAT parameter as equivalent to RESPONSEFORMAT. @@ -564,7 +567,7 @@ \subsubsection{MAXREC} \label{sec:MAXREC} The MAXREC parameter and its effect on the query result is fully described in -\citep{std:DALI11}. If the result set is truncated in this fashion, it must +DALI. If the result set is truncated in this fashion, it must include an overflow indicator as specified in section~\ref{sec:query-overflow}. For the special value of MAXREC=0, the service is not required to execute the @@ -593,17 +596,17 @@ \subsubsection{MAXREC} indicator. \subsubsection{RUNID} -The RUNID parameter is fully described in \citep{std:DALI11}. +The RUNID parameter is fully described in DALI. \subsubsection{UPLOAD} \label{sec:UPLOAD} -The UPLOAD parameter is described in \citep{std:DALI11}. Services should support +The UPLOAD parameter is described in DALI. Services should support the -upload of temporary tables (in \citep{std:VOTable} format) via the standard +upload of temporary tables in VOTable \citep{std:VOTable} format via the standard UPLOAD parameter. The table-name(s) must be legal ADQL table names as defined in -\citep{std:ADQL} but restricted as described in section~\ref{sec:tap-schema}. +\citet{std:ADQL} but restricted as described in section~\ref{sec:tap-schema}. URIs may be simple URLs (e.g. with a URI scheme of http or https) or URIs that must be resolved (e.g. with a URI scheme of vos or param) to give the location of the table content. @@ -611,7 +614,7 @@ \subsubsection{UPLOAD} If table upload is supported, the service must accept tables in VOTable format. The client specifies the name of the uploaded table; this name must be a legal ADQL table name with no catalog or schema (i.e., a string following the -regular identifier production of \citep{std:ADQL}). Uploaded tables must be +regular identifier production of ADQL). Uploaded tables must be referred to in queries as TAP\_UPLOAD., where is the specified by the user. Tables in the TAP\_UPLOAD schema are @@ -619,7 +622,7 @@ \subsubsection{UPLOAD} be used behind the scenes) and are never visible in the TAP\_SCHEMA metadata. -The \citep{std:DALI11} UPLOAD parameter supports both external resources and +The DALI UPLOAD parameter supports both external resources and in-line content. For external resources, one provides a URI (usually an HTTP URL) the TAP service can use to obtain the table content. For example, @@ -659,7 +662,7 @@ \subsubsection{UPLOAD} \section{Use of VOTable} \label{sec:votable} -The \citep{std:VOTable} format is the standard format for output (query +VOTable \citep{std:VOTable} is the standard format for output (query results) and input (table upload) in a TAP service so most of this section deals with how VOTable is used. However, rules about serialising column values also apply to other formats (e.g. CSV and TSV). @@ -667,7 +670,7 @@ \section{Use of VOTable} \subsection{INFO elements} \label{sec:vot-info} -The RESOURCE element must contain INFO element(s) as described in \citep{std:DALI11}. +The RESOURCE element must contain INFO element(s) as described in DALI. Additional INFO elements may be provided, e.g., to echo the input parameters back to the client in the query response (a useful feature for debugging or to @@ -683,7 +686,8 @@ \subsection{INFO elements} \end{verbatim} -Additional INFO elements after the results may also be included as specified in \citep{std:DALI11}. +Additional INFO elements after the results may also be included as +specified in DALI. \subsection{Successful Queries} \label{sec:query-ok} @@ -718,12 +722,13 @@ \subsection{Successful Queries} row should give the column name as the data value. CSV data must be returned with a MIME type of text/csv; if the optional header line (with column names) is included, the MIME type must be text/csv;header=present. Full details of CSV -format are defined in \citep{std:CSV}. +format are defined in \citet{std:CSV}. TSV formatted data should represent the output table with one row of text per table row, with the table column values rendered as text and separated by the TAB character. TSV data must be returned with a MIME type of -text/tab-separated-values \citep{std:TSV}. Column values may not contain the +text/tab-separated-values as described in +\citet{std:TSV}. Column values may not contain the TAB character. @@ -750,7 +755,7 @@ \subsection{Errors} error if the client is not allowed to access the resource. Error documents should be in a format that matches the requested -format where possible; see DALI \citep{std:DALI11} for details. +format where possible; see DALI for details. If the error document is being retrieved from the /async//error resource (specified by UWS) after an asynchronous query, the HTTP status code should be 200. If the error document is being @@ -783,21 +788,20 @@ \subsection{Mapping Table Datatypes} This section describes the bi-directional mapping between VOTable and RDBMS + geometric datatypes and extends the basic rules for serialising such values in -VOTable described in \citep{std:DALI11}. These rules apply to input tables +VOTable described in DALI. These rules apply to input tables supplied via an UPLOAD parameter (see section~\ref{sec:UPLOAD}) and to result tables after successful query execution. For input tables, the name attribute of the FIELD element is used as the column name. Services must support delimited identifiers so that -FIELD names that are not valid ADQL column names work correctly -\citep{std:ADQL}. +FIELD names that are not valid ADQL column names work correctly. The mapping to and from VOTable makes use of the datatype, arraysize, and xtype attributes. Mapping for primitive types (numbers and strings) is straightforward; services should insure that input values behave as expected in query processing and output values should have correct and complete metadata. Mapping for specially structured values use xtype(s) specified -in \citep{std:DALI11}. The behaviour of such structured values in queries depends +in DALI. The behaviour of such structured values in queries depends on the query language (section~\ref{sec:LANG}) being used. \section{Metadata: TAP\_SCHEMA} @@ -890,7 +894,7 @@ \subsection{Tables} depending on the implementation requirements. The fully qualified table name is defined by the ADQL language and follows the pattern [[catalog.]schema.]table. If the table name is such that the name must be quoted (quoted identifier in -\citep{std:ADQL}) then the value must include the quotes. +ADQL) then the value must include the quotes. The table\_type value must be either table or view. @@ -932,7 +936,7 @@ \subsection{Columns} table using three (3) columns with an additional (deprecated) column from TAP-1.0 for backwards compatibility. The allowed values for datatype and the syntax for arraysize are specified in VOTable \citep{std:VOTable}. Values for xtype are not restricted per se but -implementors should use standard values such as those defined in DALI \citep{std:DALI11} before +implementors should use standard values such as those defined in DALI before inventing new xtype(s). The arraysize column gives the length of variable length datatypes using the VOTable @@ -1024,8 +1028,8 @@ \section{Examples} \label{sec:examples} The UWS pattern is specified in \citep{std:UWS} and its application to TAP in -section section~\ref{sec:tap-async}. TAP services may implement \citep{std:UWS} or -a later version. +section section~\ref{sec:tap-async}. TAP services may implement UWS 1.0 +or a later version. This section gives examples of the exchange of messages between a TAP client and service when using UWS to run an asynchronous query. @@ -1070,7 +1074,7 @@ \subsubsection{Creating and Executing a Simple Query} \end{verbatim} The client may have to check the phase multiple times until the job -finishes. If the service implements \citep{std:UWS11} or later, a blocking call +finishes. If the service implements UWS 1.1 \citep{std:UWS11} or later, a blocking call can be used instead of polling. Once the job reaches the COMPLETED phase, the results can be obtained from the results resource: @@ -1095,7 +1099,7 @@ \subsubsection{Modify a Query Job Before Execution} While the job is in the PENDING phase, the job parameters may be modified by additional POST(s) to the parameters resource (see -\citep{std:DALI11}), for example: +\citet{std:DALI11}), for example: \begin{verbatim} HTTP POST http://example.com/tap/async/42/parameters @@ -1112,7 +1116,7 @@ \subsubsection{Modify a Query Job Before Execution} Parameter-value pairs accumulate when POSTed to the parameters resource, so an additional POST of the UPLOAD parameter in this example would add another parameter-value pair (essentially a multi-valued parameter as described in -\citep{std:DALI11}). There is no mechanism to replace or remove a parameter in a +DALI). There is no mechanism to replace or remove a parameter in a PENDING job. After each such POST, the service issues an HTTP redirection to the job's URL, @@ -1223,7 +1227,7 @@ \subsubsection{Running a Query} When the query job is complete, the phase changes will normally be one of COMPLETED, ABORTED, or ERROR (although there are other less used phases defined -in \citep{std:UWS}). The client then retrieves the result from the results list: +in UWS). The client then retrieves the result from the results list: \begin{verbatim} HTTP GET http://example.com/tap/async/42/results/result \end{verbatim} @@ -1273,10 +1277,11 @@ \subsection{Example: Synchronous Query} Location: http://example.com/tap/sync/53/go \end{verbatim} -As described in \citep{std:DALI11}, clients must be prepared to follow such +As described in DALI, clients must be prepared to follow such redirects to obtain the result. \subsection{Example: DALI-examples Document} +\label{sect:example-example} The following is a full document a service might serve from its \verb|/examples| endpoint; note that you can add arbitrary styling or diff --git a/sample-capability.xml b/sample-capability.xml index 84aedea..c93b48d 100644 --- a/sample-capability.xml +++ b/sample-capability.xml @@ -1,4 +1,4 @@ - Date: Wed, 13 Sep 2017 19:30:02 +0000 Subject: [PATCH 24/68] tap_schema column type simplification; BasicAA security method in example; double quote issues --- TAP.tex | 117 ++++++++++++++++++++++++------------------ sample-capability.xml | 9 ++-- 2 files changed, 71 insertions(+), 55 deletions(-) diff --git a/TAP.tex b/TAP.tex index fcdc755..8cb4797 100644 --- a/TAP.tex +++ b/TAP.tex @@ -833,12 +833,8 @@ \section{Metadata: TAP\_SCHEMA} Column datatypes in the TAP\_SCHEMA are specified using the same concepts used in VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors -must also include the "size" column and populate it where possible. The arraysize values -specified below for describing the TAP\_SCHEMA tables themselves is the most flexible -(* means variable length with no maximum); implementors should use more restrictive values -that describe their implementation of the TAP\_SCHEMA tables (e.g. arraysize 64* to describe -a column with database type varchar(64)). Implementors may also use alternate character or numeric types (e.g. short or long instead of int or unicodeChar instead of char) as long as -query execution is consistent with the recommended types. +must also include the ``size'' column and populate it where possible. In the descriptions +below we only specify the column types as \em{string} or \em{integer}. Implementors may use alternate character or numeric types (e.g. short or long instead of int or unicodeChar instead of char) as long as query execution is consistent with the recommended types. The ``size'' and arraysize values for (self) describing TAP\_SCHEMA columns is implementation-specific. Implementors are permitted to include additional tables in the TAP\_SCHEMA to describe additional aspects of their service not @@ -854,11 +850,11 @@ \subsection{Schemas} \begin{inlinetable} \begin{tabular}{l l l l l} \sptablerule -\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule -schema\_name & char & * & null & true \\ -utype & char & * & null & false \\ -description & char & * & null & false \\ +schema\_name & string & true \\ +utype & string & false \\ +description & string & false \\ \sptablerule \end{tabular} \end{inlinetable} @@ -876,14 +872,14 @@ \subsection{Tables} \begin{inlinetable} \begin{tabular}{l l l l l} \sptablerule -\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule -schema\_name & char & * & null & true \\ -table\_name & char & * & null & true \\ -table\_type & char & * & null & true \\ -utype & char & * & null & false \\ -description & char & * & null & false \\ -table\_index & int & 1 & null & false \\ +schema\_name & string & true \\ +table\_name & string & true \\ +table\_type & string & true \\ +utype & string & false \\ +description & string & false \\ +table\_index & integer & false \\ \sptablerule \end{tabular} \end{inlinetable} @@ -909,22 +905,22 @@ \subsection{Columns} \begin{inlinetable} \begin{tabular}{l l l l l} \sptablerule -\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule -table\_name & char & * & null & true \\ -column\_name & char & * & null & true \\ -datatype & char & * & null & true \\ -arraysize & char & * & null & false \\ -xtype & char & * & null & false \\ -"size" & int & 1 & null & false \\ -description & char & * & null & false \\ -utype & char & * & null & false \\ -unit & char & * & null & false \\ -ucd & char & * & null & false \\ -indexed & int & 1 & null & true \\ -principal & int & 1 & null & true \\ -std & int & 1 & null & true \\ -column\_index & int & 1 & null & false \\ +table\_name & string & true \\ +column\_name & string & true \\ +datatype & string & true \\ +arraysize & string & false \\ +xtype & string & false \\ +``size'' & integer & false \\ +description & string & false \\ +utype & string & false \\ +unit & string & false \\ +ucd & string & false \\ +indexed & integer & true \\ +principal & integer & true \\ +std & integer & true \\ +column\_index & integer & false \\ \sptablerule \end{tabular} \end{inlinetable} @@ -941,14 +937,14 @@ \subsection{Columns} The arraysize column gives the length of variable length datatypes using the VOTable array shape syntax. For example, a database column of type varchar(256) would be -described with datatype "char" and arraysize "256*". Arrays, including multi-dimensional -arrays, are permitted for all VOTable primitive types. The "size" column is retained for backwards +described with datatype ``char'' and arraysize ``256*''. Arrays, including multi-dimensional +arrays, are permitted for all VOTable primitive types. The ``size'' column is retained for backwards compatibility to TAP-1.0 and must contain the integer value equivalent to arraysize when possible and must be null if arraysize represents a multi-dimensional. To use the size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the creation of the TAP\_SCHEMA) use lower case exclusively. In the next major version -of TAP, the "size" column will be removed. +of TAP, the ``size'' column will be removed. For columns with a database type equivalent to BLOB or CLOB, most database systems support reference to these columns in the select clause but not in every other part of the query where @@ -959,17 +955,20 @@ \subsection{Columns} not sensibly be used in the WHERE clause. In general, if a query references a column in an inappropriate part of the query, the job should fail with a suitable error message. -The “principal” flag indicates that the column is considered a core part of the +The principal, indexed, and std columns are boolean values implemented as integers. As such, +the value must be 0 or 1; no other values are allowed. + +The principal flag indicates that the column is considered a core part of the content; clients can use this hint to make the principal column(s) visible, for example by selecting them by default in generating an ADQL query. In cases where the service selects the columns to return (such as a query language without an explicit output selection), the principal column indicates those columns that are returned by default. -The “indexed” flag indicates that the column is indexed, potentially +The indexed flag indicates that the column is indexed, potentially making queries run much faster if this column is used in a constraint. -The “std” is included for compatibility with the registry, which uses this value +The std flag is included for compatibility with the registry, which uses this value to indicate that a given column is defined by some standard, as opposed to a custom column defined by a particular service. @@ -986,13 +985,13 @@ \subsection{Foreign Keys} \begin{inlinetable} \begin{tabular}{l l l l l} \sptablerule -\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule -key\_id & char & * & null & true \\ -from\_table & char & * & null & true \\ -target\_table & char & * & null & true \\ -description & char & * & null & false \\ -utype & char & * & null & false \\ +key\_id & string & true \\ +from\_table & string & true \\ +target\_table & string & true \\ +description & string & false \\ +utype & string & false \\ \sptablerule \end{tabular} \end{inlinetable} @@ -1008,11 +1007,11 @@ \subsection{Foreign Keys} \begin{inlinetable} \begin{tabular}{l l l l l} \sptablerule -\textbf{column name} & \textbf{datatype} & \textbf{arraysize} & \textbf{xtype} & \textbf{not-null} \\ +\textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule -key\_id & char & * & null & true \\ -from\_column & char & * & null & true \\ -target\_column & char & * & null & true \\ +key\_id & string & true \\ +from\_column & string & true \\ +target\_column & string & true \\ \sptablerule \end{tabular} \end{inlinetable} @@ -1020,6 +1019,18 @@ \subsection{Foreign Keys} There may be one or more rows with a specific key\_id to denote single or multi-column keys. +For the TAP\_SCHEMA itself, servcies are should enforce and list the following foreign keys: + +\begin{verbatim} +TAP_SCHEMA.tables.schema_name -> TAP_SCHEMA.schemas.schema_name +TAP_SCHEMA.columns.table_name -> TAP_SCHEMA.tables.table_name +TAP_SCHEMA.keys.from_table -> TAP_SCHEMA.tables.table_name +TAP_SCHEMA.keys.target_table -> TAP_SCHEMA.tables.table_name +TAP_SCHEMA.key_columns.from_column -> TAP_SCHEMA.columns.column_name +TAP_SCHEMA.key_columns.target_column -> TAP_SCHEMA.colums.column_name +TAP_SCHEMA.key_columns.key_id -> TAP_SCHEMA.keys.key_id +\end{verbatim} + A TAP service must provide the tables listed above and may provide other tables in the TAP\_SCHEMA namespace. @@ -1296,6 +1307,14 @@ \subsection{Example: DALI-examples Document} \section{Changes from Previous Versions} +\subsection{PR-TAP-1.1-??} + +Removed explicit datatype/arraysize/xtype from TAP\_SCHEMA description in favour of string and integer. Specified which integers are actually booleans (0 or 1). Added list of foreign keys for TAP\_SCHEMA relational model. + +Fixed use of double-quotes which misbehaved inside tables. + +Fixed BasicAA security method in capabilities example. + \subsection{PR-TAP-1.1-20170830} Added an example for \verb|examples|. @@ -1305,7 +1324,7 @@ \subsection{PR-TAP-1.1-20170830} Removed remaining uses of PQL; replaced one example with something more clearly non-standard. -Removed restriction from previous WD that the "size" column must be null for variable length arrays. In fact, "size" can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column. +Removed restriction from previous WD that the ``size'' column must be null for variable length arrays. In fact, ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column. Changed language about mandatory ADQL geometry function support back to optional (should in the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. diff --git a/sample-capability.xml b/sample-capability.xml index c93b48d..3769464 100644 --- a/sample-capability.xml +++ b/sample-capability.xml @@ -25,8 +25,7 @@ http://example.net/myTAP/auth-async - + https://example.net/myTAP/async @@ -41,8 +40,7 @@ http://example.net/myTAP/auth-sync - + https://example.net/myTAP/sync @@ -77,8 +75,7 @@ http://myarchive.net/myTAP/auth-tables - + From 20dc5f7fcb948daeaa80d7d86d3465de83e566a3 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 26 Sep 2017 14:18:42 +0000 Subject: [PATCH 25/68] TAP: Minor typographical fixes In particular, TAP_SCHEMA is now generated by a macro \tapschema for a bit less uglyness and more hyphenation points. --- TAP.tex | 84 +++++++++++++++++++++++++++++++-------------------------- 1 file changed, 46 insertions(+), 38 deletions(-) diff --git a/TAP.tex b/TAP.tex index 8cb4797..85a03aa 100644 --- a/TAP.tex +++ b/TAP.tex @@ -24,7 +24,9 @@ \previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{WD-TAP-1.1-20170707} \previousversion[http://www.ivoa.net/Documents/TAP/20160428/]{WD-TAP-1.1-20160428} \previousversion[http://www.ivoa.net/Documents/TAP/1.0]{TAP-1.0} - + + +\newcommand{\tapschema}{TAP\discretionary{-}{}{\kern-2pt\_}SCHEMA{}} \begin{document} @@ -427,7 +429,7 @@ \subsection{/tables} /tables that is a direct child of the root web resource. The /tables resource must be accessible via the http GET method. The content is described by VOSI and is equivalent to the metadata from the -TAP\_SCHEMA described in section~\ref{sec:tap-schema}. The use of VOTableType +\tapschema{} described in section~\ref{sec:tap-schema}. The use of VOTableType (rather than TAPType) in the VOSI-tables output is recommended because the values map directly; TAPType may be used when VOTableType does not provide a suitable alternative. @@ -620,7 +622,7 @@ \subsubsection{UPLOAD} specified by the user. Tables in the TAP\_UPLOAD schema are transient and persist only for the lifetime of the query (although caching might be used behind the scenes) and are never visible in the -TAP\_SCHEMA metadata. +\tapschema{} metadata. The DALI UPLOAD parameter supports both external resources and in-line @@ -702,7 +704,7 @@ \subsection{Successful Queries} in the SELECT clause of the query. For VOTable output, the name attribute of FIELD elements must be the same as the column names (or aliases if specified in the query) in the query and the datatype, arraysize, and xtype -attributes of FIELD elements must be set using the values from the TAP\_SCHEMA. +attributes of FIELD elements must be set using the values from the \tapschema. In cases where items in the select list do not have names (e.g. expression or function invocation without an alias) the service must generate a name; @@ -804,40 +806,44 @@ \subsection{Mapping Table Datatypes} in DALI. The behaviour of such structured values in queries depends on the query language (section~\ref{sec:LANG}) being used. -\section{Metadata: TAP\_SCHEMA} +\section{Metadata: \tapschema} \label{sec:tap-schema} There are several approaches to getting metadata for a given TAP service. All TAP services must support a set of tables in a schema named -TAP\_SCHEMA that describe the tables and columns included in the -service. In addition to the TAP\_SCHEMA, there are two other ways +\tapschema{} that describe the tables and columns included in the +service. In addition to the \tapschema, there are two other ways to get metadata from a TAP service. First, the VOSI tables resource provides metadata on all tables and columns; this resource is described in (section~\ref{sec:vosi-tables}). The -VOSI tables resource provides the same metadata as the TAP\_SCHEMA +VOSI tables resource provides the same metadata as the \tapschema{} but in a rigorously controlled format; the information in the -TAP\_SCHEMA is equivalent to that defined by the VODataService +\tapschema{} is equivalent to that defined by the VODataService \citep{std:VODS11}. Second, the client may specify a query of one or more tables setting the MAXREC parameter to 0 so that only the metadata regarding the requested fields is returned. Use of MAXREC is described in section~\ref{sec:MAXREC}. -The TAP\_SCHEMA provides access to table, column, and join key +The \tapschema{} provides access to table, column, and join key metadata through the TAP query mechanisms themselves. Users can discover tables or columns that meet their specific criteria by querying the tables described -below. The service may enhance the TAP\_SCHEMA with additional +below. The service may enhance the \tapschema{} with additional metadata where that seems appropriate; since it is self-describing, the -TAP\_SCHEMA may be queried to determine if any extended schema +\tapschema{} may be queried to determine if any extended schema metadata is defined by the service. Services must provide these tables and make them accessible by all supported query mechanisms. -Column datatypes in the TAP\_SCHEMA are specified using the same concepts used in +Column datatypes in the \tapschema{} are specified using the same concepts used in VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors -must also include the ``size'' column and populate it where possible. In the descriptions -below we only specify the column types as \em{string} or \em{integer}. Implementors may use alternate character or numeric types (e.g. short or long instead of int or unicodeChar instead of char) as long as query execution is consistent with the recommended types. The ``size'' and arraysize values for (self) describing TAP\_SCHEMA columns is implementation-specific. +must also include the \verb|"size"| column and populate it where possible. The arraysize values +specified below for describing the \tapschema{} tables themselves is the most flexible +(``*'' means variable length with no maximum); implementors should use more restrictive values +that describe their implementation of the \tapschema{} tables (e.g. arraysize 64* to describe +a column with database type varchar(64)). Implementors may also use alternate character or numeric types (e.g. short or long instead of int or unicodeChar instead of char) as long as +query execution is consistent with the recommended types. Implementors are permitted to include additional tables in the -TAP\_SCHEMA to describe additional aspects of their service not +\tapschema{} to describe additional aspects of their service not covered by this specification. Implementors may also include additional columns in the standard tables described below. For example, one could include a column with a timestamp saying when metadata values were was last modified. @@ -845,7 +851,7 @@ \section{Metadata: TAP\_SCHEMA} \subsection{Schemas} \label{sec:tap-schema-schemas} -The table TAP\_SCHEMA.schemas must contain the following columns: +The table \tapschema.schemas must contain the following columns: \begin{inlinetable} \begin{tabular}{l l l l l} @@ -867,7 +873,7 @@ \subsection{Schemas} \subsection{Tables} \label{sec:tap-schema-tables} -The table TAP\_SCHEMA.tables must contain the following columns: +The table \tapschema.tables must contain the following columns: \begin{inlinetable} \begin{tabular}{l l l l l} @@ -889,7 +895,7 @@ \subsection{Tables} querying the table; it may or may not be qualified by schema and catalog name(s) depending on the implementation requirements. The fully qualified table name is defined by the ADQL language and follows the pattern [[catalog.]schema.]table. -If the table name is such that the name must be quoted (quoted identifier in +If the table name is such that the name must be quoted (delimited identifier in ADQL) then the value must include the quotes. The table\_type value must be either table or view. @@ -900,7 +906,7 @@ \subsection{Tables} \subsection{Columns} \label{sec:tap-schema-columns} -The table TAP\_SCHEMA.columns must contain the following columns: +The table \tapschema.columns must contain the following columns: \begin{inlinetable} \begin{tabular}{l l l l l} @@ -928,7 +934,7 @@ \subsection{Columns} The table\_name,column\_name (pair) values must be unique. -The type of a database column is described in the TAP\_SCHEMA.columns +The type of a database column is described in the \tapschema.columns table using three (3) columns with an additional (deprecated) column from TAP-1.0 for backwards compatibility. The allowed values for datatype and the syntax for arraysize are specified in VOTable \citep{std:VOTable}. Values for xtype are not restricted per se but @@ -943,7 +949,7 @@ \subsection{Columns} possible and must be null if arraysize represents a multi-dimensional. To use the size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the creation of the -TAP\_SCHEMA) use lower case exclusively. In the next major version +\tapschema) use lower case exclusively. In the next major version of TAP, the ``size'' column will be removed. For columns with a database type equivalent to BLOB or CLOB, most database systems support @@ -979,7 +985,7 @@ \subsection{Columns} \subsection{Foreign Keys} \label{sec:tap-schema-keys} -The table TAP\_SCHEMA.keys must contain the following columns to +The table \tapschema.keys must contain the following columns to describe foreign key relations between tables: \begin{inlinetable} @@ -997,11 +1003,11 @@ \subsection{Foreign Keys} \end{inlinetable} The key\_id values are unique and used only to join with the -TAP\_SCHEMA.key\_columns table below. There may be +\tapschema.key\_columns table below. There may be one or more rows with different key\_id values and a pair of tables to denote one or more ways to join the tables. -The table TAP\_SCHEMA.key\_columns must contain the +The table \tapschema.key\_columns must contain the following columns to describe the columns that make up a foreign key: \begin{inlinetable} @@ -1019,7 +1025,7 @@ \subsection{Foreign Keys} There may be one or more rows with a specific key\_id to denote single or multi-column keys. -For the TAP\_SCHEMA itself, servcies are should enforce and list the following foreign keys: +For the \tapschema{} itself, servcies are should enforce and list the following foreign keys: \begin{verbatim} TAP_SCHEMA.tables.schema_name -> TAP_SCHEMA.schemas.schema_name @@ -1032,7 +1038,7 @@ \subsection{Foreign Keys} \end{verbatim} A TAP service must provide the tables listed above and may provide other tables -in the TAP\_SCHEMA namespace. +in the \tapschema{} namespace. \section{Examples} @@ -1309,7 +1315,10 @@ \section{Changes from Previous Versions} \subsection{PR-TAP-1.1-??} -Removed explicit datatype/arraysize/xtype from TAP\_SCHEMA description in favour of string and integer. Specified which integers are actually booleans (0 or 1). Added list of foreign keys for TAP\_SCHEMA relational model. +Removed explicit datatype/arraysize/xtype from \tapschema{} description +in favour of string and integer. Specified which integers are actually +booleans (0 or 1). Added list of foreign keys for \tapschema{} +relational model. Fixed use of double-quotes which misbehaved inside tables. @@ -1329,22 +1338,21 @@ \subsection{PR-TAP-1.1-20170830} Changed language about mandatory ADQL geometry function support back to optional (should in the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. -Removed some VOTable content and reference DALI. Explicitly relaxed datatype and -arraysize used in TAP\_SCHEMA tables. Fixed various cross-references and typos. +Removed some VOTable content and reference DALI. Explicitly relaxed datatype and arraysize used in \tapschema{} tables. Fixed various cross-references and typos. Added example use of UWS-1.1 blocking requests. \subsection{WD-TAP-1.1-20170707} -Changed arraysize in TAP\_SCHEMA to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. +Changed arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. Clarified required and optional ADQL geometric functions. Format tables so column headers are bold. -Added paragraph specifying allowed values for TAP\_SCHEMA.tables.table\_type. +Added paragraph specifying allowed values for \tapschema.tables.table\_type. -Changed the principal, indexed, and std columns in TAP\_SCHEMA.columns to boolean since we +Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we now use the VOTabletype system. Fixed URL to schema in VOSI-capabilities example. @@ -1374,21 +1382,21 @@ \subsection{WD-TAP-1.1-20150930} TOP in an ADQL query). Clarified that services are not required to support queries that reference tables -in different schema. This is primarily to allow the TAP\_SCHEMA to be implemented +in different schema. This is primarily to allow the \tapschema{} to be implemented in a different server from the content. Completed the references section. \subsection{Changes from TAP-1.0} -Added table\_index and column\_index to TAP\_SCHEMA. +Added table\_index and column\_index to \tapschema. Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow indicator. -Added advice that the size column TAP\_SCHEMA.columns must always be used +Added advice that the size column \tapschema.columns must always be used as a quoted identifier because it is a reserved word in many RDBMS -servers. Added arraysize column to TAP\_SCHEMA.columns to replace size and +servers. Added arraysize column to \tapschema.columns to replace size and deprecated size (which will be removed in the next major version). Removed REQUEST and VERSION parameters from interface. @@ -1399,7 +1407,7 @@ \subsection{Changes from TAP-1.0} Made clarifications: restricted allowed table names for UPLOAD, clarified that multiple UPLOAD parameters accumulate, deprecated the size column in -TAP\_SCHEMA.columns and added advice to quote it as a delimited +\tapschema.columns and added advice to quote it as a delimited identifier, made presence of a TABLE element on VOTable output only required for successful queries, added optional DALI-examples endpoint (text TBD). From f13ecada0ab54c9168151911fa9c2bb843079c31 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 26 Sep 2017 14:29:40 +0000 Subject: [PATCH 26/68] TAP: still a bit improved appearance to TAP_SCHEMA, and the same for TAP_UPLOAD. --- TAP.tex | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/TAP.tex b/TAP.tex index 85a03aa..f48b009 100644 --- a/TAP.tex +++ b/TAP.tex @@ -6,6 +6,7 @@ \SVN$URL$ \usepackage{listings} +\usepackage{relsize} \lstloadlanguages{XML,HTML} \lstset{flexiblecolumns=true,basicstyle=\small,tagstyle=\ttfamily, showstringspaces=False} @@ -26,7 +27,15 @@ \previousversion[http://www.ivoa.net/Documents/TAP/1.0]{TAP-1.0} -\newcommand{\tapschema}{TAP\discretionary{-}{}{\kern-2pt\_}SCHEMA{}} +\iftth +\newcommand{\tapschema}{TAP\_SCHEMA} +\newcommand{\tapupload}{TAP\_UPLOAD} +\else +\newcommand{\tapschema}{{% + \relsize{-0.5}TAP\discretionary{-}{}{\kern-2pt\_}SCHEMA}} +\newcommand{\tapupload}{% + {\relsize{-0.5}TAP\discretionary{-}{}{\kern-2pt\_}UPLOAD}} +\fi \begin{document} @@ -618,8 +627,8 @@ \subsubsection{UPLOAD} ADQL table name with no catalog or schema (i.e., a string following the regular identifier production of ADQL). Uploaded tables must be referred -to in queries as TAP\_UPLOAD., where is the -specified by the user. Tables in the TAP\_UPLOAD schema are +to in queries as \tapupload., where is the +specified by the user. Tables in the \tapupload{} schema are transient and persist only for the lifetime of the query (although caching might be used behind the scenes) and are never visible in the \tapschema{} metadata. @@ -633,7 +642,7 @@ \subsubsection{UPLOAD} UPLOAD=mytable,http://otherplace.com/path/votable.xml \end{verbatim} The service would retrieve the table from the provided URL and -make it visible to the query as TAP\_UPLOAD.mytable. +make it visible to the query as \tapupload.mytable. If the TAP service supports VOSpace URIs, one may specify an upload table using a URI to a table stored in a VOSpace, for example: @@ -642,10 +651,10 @@ \subsubsection{UPLOAD} UPLOAD=mytable,vos://space/path/votable.xml \end{verbatim} The service would resolve the URI, contact the VOSpace, retrieve the table, and -make it visible to the query as TAP\_UPLOAD.mytable. +make it visible to the query as \tapupload.mytable. UPLOADs are accumulating, i.e., each UPLOAD parameter given will create one or -more tables in TAP\_UPLOAD. When the table names from two or more +more tables in \tapupload. When the table names from two or more upload items agree after case folding, the service behaviour is unspecified. Clients thus cannot reliably overwrite uploaded tables; to correct errors, they have to tear down the existing job and create a new one. In principle, any @@ -806,7 +815,7 @@ \subsection{Mapping Table Datatypes} in DALI. The behaviour of such structured values in queries depends on the query language (section~\ref{sec:LANG}) being used. -\section{Metadata: \tapschema} +\section{Metadata: TAP\kern-3pt\_SCHEMA} \label{sec:tap-schema} There are several approaches to getting metadata for a given TAP service. All @@ -1128,7 +1137,7 @@ \subsubsection{Modify a Query Job Before Execution} Here we have specified with the UPLOAD parameter that the service create a temporary table named mytable with content from the VOTable at the specified URL. The QUERY parameter can then reference the uploaded table with the -specified name (but in the TAP\_UPLOAD schema). +specified name (but in the \tapupload{} schema). Parameter-value pairs accumulate when POSTed to the parameters resource, so an additional POST of the UPLOAD parameter in this example would add another From 4d22d1dbf137fd9deda70787e73e7f83005f8a5c Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Wed, 27 Sep 2017 14:55:28 +0000 Subject: [PATCH 27/68] TAP: fixing minor typos --- TAP.tex | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/TAP.tex b/TAP.tex index f48b009..2ec6f04 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1034,7 +1034,7 @@ \subsection{Foreign Keys} There may be one or more rows with a specific key\_id to denote single or multi-column keys. -For the \tapschema{} itself, servcies are should enforce and list the following foreign keys: +For the \tapschema{} itself, services should enforce and list the following foreign keys: \begin{verbatim} TAP_SCHEMA.tables.schema_name -> TAP_SCHEMA.schemas.schema_name @@ -1053,8 +1053,8 @@ \subsection{Foreign Keys} \section{Examples} \label{sec:examples} -The UWS pattern is specified in \citep{std:UWS} and its application to TAP in -section section~\ref{sec:tap-async}. TAP services may implement UWS 1.0 +The UWS pattern is specified in the UWS specification \citep{std:UWS} and its application to TAP in +section~\ref{sec:tap-async}. TAP services may implement UWS 1.0 or a later version. This section gives examples of the exchange of messages between a TAP client and service when using UWS to run an asynchronous query. @@ -1234,13 +1234,13 @@ \subsubsection{Running a Query} \begin{verbatim} HTTP GET http://example.com/tap/async/42/phase \end{verbatim} -or by performing a blocking GET ofthe jon (UWS-1.1 or later): +or by performing a blocking GET of the job url (UWS-1.1 or later): \begin{verbatim} HTTP GET http://example.com/tap/async/42?WAIT=30 \end{verbatim} The blocking GET will block until something changes in the job (usually the phase change) and then return, with a maximum wait time specified by the WAIT parameter. Since -services may impose a limit on the maximum wait time and may return before ten job reaches +services may impose a limit on the maximum wait time and may return before the job reaches a final phase, clients must examine the job state (returned by the GET) and possibly perform additional requests. From 1326b000efd0908ad35717f3f7c8a32b1d6952da Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 23 Nov 2017 21:03:49 +0000 Subject: [PATCH 28/68] resolved all comments collected from mailing list; reworked VOSI-capabilities to use a single TAP standardID and use prototype UWSRegExt interface types to support combinations of sync-async-securityMethod-accessURL. --- Makefile | 2 +- TAP.tex | 165 +++++++++++++++++++++++++----------------- sample-capability.xml | 81 ++++++++++----------- 3 files changed, 139 insertions(+), 109 deletions(-) diff --git a/Makefile b/Makefile index 70b249b..6a1e981 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2017-08-30 +DOCDATE = 2017-11-24 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = PR diff --git a/TAP.tex b/TAP.tex index 2ec6f04..6b97c59 100644 --- a/TAP.tex +++ b/TAP.tex @@ -22,6 +22,7 @@ \editor{Patrick Dowler} +\previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{PR-TAP-1.1-20170830} \previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{WD-TAP-1.1-20170707} \previousversion[http://www.ivoa.net/Documents/TAP/20160428/]{WD-TAP-1.1-20160428} \previousversion[http://www.ivoa.net/Documents/TAP/1.0]{TAP-1.0} @@ -132,8 +133,8 @@ \subsection{Role within the VO Architecture} \item[UWS \citep{2016ivoa.spec.1024H}] TAP services can be queried asynchronously; the Universal Worker Service UWS defines the corresponding communication pattern. Note that while TAP 1.1 does not -require the use of any particular minor version of the standards it -depends on, UWS 1.1 can significantly streamline the communication, and +require the use of any particular minor version of the UWS standard, +UWS 1.1 can significantly streamline the communication, and implementors of TAP 1.1 are encouraged to support UWS 1.1 or later. \item[ADQL \citep{2008ivoa.spec.1030O}] A standards-compliant TAP @@ -142,10 +143,17 @@ \subsection{Role within the VO Architecture} \item[VOSI \citep{std:VOSI11}] The VO Support Interfaces standard defines endpoints for metadata discovery; for TAP, this is the tables, -capabilities, and availability endpoints. +capabilities, and availability endpoints. Note that while TAP 1.1 does not +require the use of any particular minor version of the VOSI standard, +the VOSI-tables resource in VOSI 1.1 provides important usability features, and +implementors of TAP 1.1 are encouraged to support VOSI 1.1 or later. \item[VOTable \citep{2013ivoa.spec.0920O}] All TAP services must be able -to serve query results in the VOTable format. +to serve query results in the VOTable format. Note that while TAP 1.1 does not +require the use of any particular minor version of the VOtable standard, older +versions are missing features that are required and may be ususable in practice. +For example, the overflow reporting and xtype attribute were introduced in +VOTable 1.2 so that is the minimum viable version taht must be used. \end{description} @@ -173,6 +181,12 @@ \subsection{Role within the VO Architecture} aspects of a TAP service's capabilities (e.g., resource limits, output formats, user defined functions). +\item[UWSRegExt (prototype)] While there is no formal +requirement to that effect, the response on a TAP service's capabilities +endpoint should contain instances \xmlel{uws:Async}-typed and +\xmlel{uws:Sync}-typed interfaces in order to allow clients to discover +interfaces that support different authentication mechanisms via alternate +resources within the service. \end{description} @@ -345,7 +359,7 @@ \subsection{\{async\}} where 42 is an example job identifier. A client making an asynchronous request must use the UWS facilities to monitor or control the job. In addition to the job list -and job resource above, UWS specifies the name and semantics of the a small set +and job resource above, UWS specifies the name and semantics of a small set of child resources used to view and control the job, e.g.: \begin{verbatim} http://example.com/tap/async/42/phase @@ -399,45 +413,50 @@ \subsection{/capabilities} ivo://ivoa.net/std/TAP \end{verbatim} -For TAP-1.1 we define new standard identifiers for each of the -features. Asynchronous query resources (section~\ref{sec:tap-async}) are described by standardID: +For TAP-1.1 we define new (versioned) standard identifier for then query feature: \begin{verbatim} -ivo://ivoa.net/std/TAP#async-1.1 +ivo://ivoa.net/std/TAP#query-1.1 \end{verbatim} -Synchronous query resources (section~\ref{sec:tap-sync}) are described by standardID: - -\begin{verbatim} -ivo://ivoa.net/std/TAP#sync-1.1 -\end{verbatim} - -In TAP-1.0 the base URL was described with a single standard identifier; in -TAP-1.1 and beyond, individual resources are described with their own -standardID. This allows service providers to describe multiple resources that -deliver the specified feature (e.g. with different authentication methods) in +In TAP, the base URL is described with a single standard identifier and the mandatory +chilsd resources have specific names (section~\ref{sec:resources}). One or more DALI-async +and DALI-sync interfaces to the query capability may be described using the prototype UWS +registry extension (UWSRegExt). This allows service +providers to describe multiple resources that +deliver the query features (e.g. with different authentication methods) in the VOSI-capabilities resource. The use of the VOSI-capabilities resource is described in DALI. -For example, the returned capabilities document for a service supporting TAP +For example, the returned capabilities document for a service supporting TAP might look as follows: \lstinputlisting[language=XML,basicstyle=\footnotesize] {sample-capability.xml} +The first interface with type vs:ParamHTTP gives the base URL; this is expected to be +included in registry records and support finding TAP services in a simple and backwards +compatible manner. The subsequent interface elements describe combinations of access URL +and security method(s) that can be used by clients to make authenticated calls. They also +use the type of the interface to specify that the particular access URL uses an async or sync +invocation pattern. Note that in this example the anonymous async and sync endpoints are +described explicitly but could also be inferred from the base service URL using the standard +names. Service implementors must include the base interface for backwards compatibility in +registry queries and should include all relevant UWS-typed interfaces for direct client use. + The service capabilities must be accessible from a web resource with relative URL /capabilities that is a direct child of the root web resource. The /capabilities resource must be accessible via the http GET method. The content -is described by VOSI \citep{std:VOSI}. +is described by VOSI \citep{std:VOSI11}. \subsection{/tables} \label{sec:vosi-tables} The table metadata should be accessible from a web resource with relative URL /tables that is a direct child of the root web resource. The /tables resource -must be accessible via the http GET method. The content is described by -VOSI and is equivalent to the metadata from the +implements the VOSI-tables capability and output described in VOSI. +The content is equivalent to the metadata from the \tapschema{} described in section~\ref{sec:tap-schema}. The use of VOTableType (rather than TAPType) in the VOSI-tables output is recommended because the values map directly; TAPType may be used when VOTableType does not provide a suitable @@ -547,16 +566,19 @@ \subsubsection{QUERY} A service must support the QUERY parameter because ADQL is a required language. -Within the ADQL query, the service must support the use of timestamp values as -described in DALI if applicable. Timestamp values are usable if there -are columns with timestamp values, including in uploaded tables if table upload -is supported. +If timestamp comparisons are supported within ADQL queries, they must use the syntax +defined in DALI. Timestamp values are usable if there are columns with timestamp values, +including in uploaded tables if table upload is supported. + +If the service supports the use of spatial coordinates in ADQL queries, the output of +geometry values should use the syntax defined in DALI. Services may output geometry values +using the STC-S convention described in the previous version of this standard, but we +strongly recommend switching to the DALI syntax. -If the tables that are queried through a service contain columns with spatial -coordinates, the service should implement ADQL geometric query support by enabling -the following functions in ADQL queries: INTERSECTS, CONTAINS, POINT, CIRCLE, and POLYGON. -AREA, CENTROID, COORDSYS, COORD1, and COORD2 are optional. REGION is no longer -supported. +If table upload is supported, values using the DALI syntax must be supported and values using +the previous STC-S convention may be supported for backwards compatibility. Input and output of +all values must be supported (e.g. selecting all columns from an uploaded table) for all types +even if comparisons are not supported. Note: Although it is allowed by the ADQL syntax (version 2.0 at least), clients should be careful when mixing constants and column references for coordinate system and coordinate @@ -627,12 +649,16 @@ \subsubsection{UPLOAD} ADQL table name with no catalog or schema (i.e., a string following the regular identifier production of ADQL). Uploaded tables must be referred -to in queries as \tapupload., where is the +to in queries as \tapupload., where is the name specified by the user. Tables in the \tapupload{} schema are transient and persist only for the lifetime of the query (although caching might be used behind the scenes) and are never visible in the \tapschema{} metadata. +For uploaded tables, the name attribute of the FIELD element is used as the column +name. Services must support delimited identifiers so that +FIELD names that are not valid ADQL column names work correctly. + The DALI UPLOAD parameter supports both external resources and in-line content. For external resources, one provides a URI (usually an HTTP URL) the @@ -676,7 +702,10 @@ \section{Use of VOTable} VOTable \citep{std:VOTable} is the standard format for output (query results) and input (table upload) in a TAP service so most of this section deals with how VOTable is used. However, rules about serialising column values -also apply to other formats (e.g. CSV and TSV). +also apply to other formats (e.g. CSV and TSV). + +The use of VOTable in TAP services is described in DALI, with additional clarifications +or advice below. \subsection{INFO elements} \label{sec:vot-info} @@ -697,9 +726,6 @@ \subsection{INFO elements} \end{verbatim} -Additional INFO elements after the results may also be included as -specified in DALI. - \subsection{Successful Queries} \label{sec:query-ok} @@ -711,8 +737,8 @@ \subsection{Successful Queries} The output table must include the same number and order of columns as specified in the SELECT clause of the query. For VOTable output, the name attribute of -FIELD elements must be the same as the column names (or aliases if specified in -the query) in the query and the datatype, arraysize, and xtype +FIELD elements must be the same as the column names (or aliases if specified) +in the query and the datatype, arraysize, and xtype attributes of FIELD elements must be set using the values from the \tapschema. In cases where items in the select list do not have names (e.g. expression or function invocation without an alias) the service @@ -720,17 +746,11 @@ \subsection{Successful Queries} generated names must be unique (within the output table) and should be valid ADQL identifiers. -VOTable structure follows the rules in section 2.9 and must be returned with an -allowed VOTable MIME type (application/x-votable+xml or text/xml). If the -RESPONSEFORMAT parameter (section~\ref{sec:RESPONSEFORMAT}) of the request -specified a specific VOTable MIME type, the requested MIME type must be used -in the HTTP response. - CSV formatted data should represent the output table with one row of text per -table row, with the table column values rendered as text and separated by -commas. If a column value contains a comma the entire column value should be +table row, with the table column values rendered as text. +If a column value contains a comma, the entire column value should be enclosed in double quotes. Text lines may be arbitrarily long. The first data -row should give the column name as the data value. CSV data must be returned +row should give the column name(s) as the data value. CSV data must be returned with a MIME type of text/csv; if the optional header line (with column names) is included, the MIME type must be text/csv;header=present. Full details of CSV format are defined in \citet{std:CSV}. @@ -790,9 +810,7 @@ \subsection{Overflows} MIME type of the output must be the same as for any successful query and the HTTP status-code must be as for a successful, complete query. -If the output format is VOTable, section 2.9.1 describes the method by which -the overflow is reported. No method of reporting an overflow is defined for -formats other than VOTable. +Reporting of overflow depends on the output format and is described in DALI. \subsection{Mapping Table Datatypes} \label{sec:vot-rdbms} @@ -803,10 +821,6 @@ \subsection{Mapping Table Datatypes} supplied via an UPLOAD parameter (see section~\ref{sec:UPLOAD}) and to result tables after successful query execution. -For input tables, the name attribute of the FIELD element is used as the column -name. Services must support delimited identifiers so that -FIELD names that are not valid ADQL column names work correctly. - The mapping to and from VOTable makes use of the datatype, arraysize, and xtype attributes. Mapping for primitive types (numbers and strings) is straightforward; services should insure that input values behave as @@ -863,13 +877,14 @@ \subsection{Schemas} The table \tapschema.schemas must contain the following columns: \begin{inlinetable} -\begin{tabular}{l l l l l} +\begin{tabular}{l l l} \sptablerule \textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule schema\_name & string & true \\ utype & string & false \\ description & string & false \\ +schema\_index & integer & false \\ \sptablerule \end{tabular} \end{inlinetable} @@ -885,7 +900,7 @@ \subsection{Tables} The table \tapschema.tables must contain the following columns: \begin{inlinetable} -\begin{tabular}{l l l l l} +\begin{tabular}{l l l} \sptablerule \textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule @@ -918,7 +933,7 @@ \subsection{Columns} The table \tapschema.columns must contain the following columns: \begin{inlinetable} -\begin{tabular}{l l l l l} +\begin{tabular}{l l l} \sptablerule \textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule @@ -940,8 +955,8 @@ \subsection{Columns} \end{tabular} \end{inlinetable} -The table\_name,column\_name (pair) values must be -unique. +The table\_name,column\_name (pair) values must be unique. If the column name is such that +the name must be quoted (quoted identifier in ADQL) then the value must include the quotes. The type of a database column is described in the \tapschema.columns table using three (3) columns with an additional (deprecated) column from TAP-1.0 @@ -955,7 +970,7 @@ \subsection{Columns} described with datatype ``char'' and arraysize ``256*''. Arrays, including multi-dimensional arrays, are permitted for all VOTable primitive types. The ``size'' column is retained for backwards compatibility to TAP-1.0 and must contain the integer value equivalent to arraysize when -possible and must be null if arraysize represents a multi-dimensional. +possible and must be null if arraysize represents a multi-dimensional array. To use the size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both clients and servers MUST always (in particular, in the creation of the \tapschema) use lower case exclusively. In the next major version @@ -998,7 +1013,7 @@ \subsection{Foreign Keys} describe foreign key relations between tables: \begin{inlinetable} -\begin{tabular}{l l l l l} +\begin{tabular}{l l l} \sptablerule \textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule @@ -1020,7 +1035,7 @@ \subsection{Foreign Keys} following columns to describe the columns that make up a foreign key: \begin{inlinetable} -\begin{tabular}{l l l l l} +\begin{tabular}{l l l} \sptablerule \textbf{column name} & \textbf{type} & \textbf{not-null} \\ \sptablerule @@ -1176,7 +1191,7 @@ \subsubsection{Modify a Query Job Before Execution} \end{verbatim} The quote resource specifies the predicted completion time for the job (query), assuming it is started immediately. In practice, it is very hard to estimate the -time a query will take; for TAP services it is recommended that this be set to +time a query will take; for TAP services it is recommended that this is set to the current time plus the maximum amount of time the query will be allowed to run. The executionduration resource specifies the amount of time (in seconds) the job (query) will be allowed to run before being aborted by the service. The @@ -1286,7 +1301,6 @@ \subsection{Example: Synchronous Query} \begin{verbatim} HTTP POST http://example.com/tap/sync -REQUEST=doQuery LANG=ADQL QUERY=SELECT * FROM magnitudes as m where m.r>=10 and m.r<=16 \end{verbatim} @@ -1322,16 +1336,33 @@ \subsection{Example: DALI-examples Document} \section{Changes from Previous Versions} -\subsection{PR-TAP-1.1-??} +\subsection{PR-TAP-1.1-20171124} + +Removed language that somehow defined or restricted usage of ADQL constructs in +favour of just referring to the AQDL spec. Clarified use of serialisation +rules for extended types defined in DALI. Removed explicit datatype/arraysize/xtype from \tapschema{} description in favour of string and integer. Specified which integers are actually booleans (0 or 1). Added list of foreign keys for \tapschema{} -relational model. +relational model. Clarified use of quoted identifiers for column names in +\tapschema. Added schema\_index column. Fixed use of double-quotes which misbehaved inside tables. -Fixed BasicAA security method in capabilities example. +Fixed BasicAA security method in capabilities example. Included use of prototype +UWSRegExt interface tags in capabilities example and removed use of separate +standardID values for async and sync. + +Fixed numerous typos and gramnmatical errors. + +Removed obsolete REQUEST=doQuery from examples. + +Added explicit reference to VOSI-tables. Updates capabilitioes example to describe a +tables-1.1 capability. + +Clarified dependency on minor versions of related standards with some recommendations on +using newer versions. \subsection{PR-TAP-1.1-20170830} diff --git a/sample-capability.xml b/sample-capability.xml index 3769464..851d5ec 100644 --- a/sample-capability.xml +++ b/sample-capability.xml @@ -8,73 +8,72 @@ http://www.ivoa.net/xml/VODataService/v1.1 http://www.ivoa.net/xml/VODataService/v1.1"> - - + + http://example.net/myTAP - - https://example.net/myTAP - - - - - - - + + http://example.net/myTAP/async - - http://example.net/myTAP/auth-async + + https://example.net/myTAP/auth-async - - https://example.net/myTAP/async + + https://example.net/myTAP/cert-async - - - - - http://example.net/myTAP/sync + + + https://example.net/myTAP/sync - - http://example.net/myTAP/auth-sync + + https://example.net/myTAP/auth-sync - - https://example.net/myTAP/sync + + https://example.net/myTAP/cert-sync + - - - http://example.net/myTAP/capabilities + + http://example.net/myTAP/capabilities - - - http://example.net/myTAP/availability - + + http://example.net/myTAP/availability - - - http://myarchive.net/myTAP/tables + + + http://myarchive.net/myTAP/tables - - https://myarchive.net/myTAP/tables - + + https://myarchive.net/myTAP/cert-tables + - - http://myarchive.net/myTAP/auth-tables + + http://myarchive.net/myTAP/auth-tables From 7770b07899f6eda7478e182150e7017c987fc052 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Fri, 24 Nov 2017 08:46:18 +0000 Subject: [PATCH 29/68] Minor typo. --- TAP.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TAP.tex b/TAP.tex index 6b97c59..13f87b2 100644 --- a/TAP.tex +++ b/TAP.tex @@ -153,7 +153,7 @@ \subsection{Role within the VO Architecture} require the use of any particular minor version of the VOtable standard, older versions are missing features that are required and may be ususable in practice. For example, the overflow reporting and xtype attribute were introduced in -VOTable 1.2 so that is the minimum viable version taht must be used. +VOTable 1.2 so that is the minimum viable version that must be used. \end{description} From 6a7ad8e6393ee009609958a254941b2774e2a335 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 24 Nov 2017 22:49:20 +0000 Subject: [PATCH 30/68] reverted to TAP-1.0 standardID, tweaked the sample-capability doc after validating with prototype UWSRegExt xsd; clarified that arraysize and "size" are null for scalars; clarified relation between arraysize and "size" --- TAP.tex | 36 +++++++++++++++++++----------------- sample-capability.xml | 10 +++++----- 2 files changed, 24 insertions(+), 22 deletions(-) diff --git a/TAP.tex b/TAP.tex index 13f87b2..dd6e4a4 100644 --- a/TAP.tex +++ b/TAP.tex @@ -413,18 +413,15 @@ \subsection{/capabilities} ivo://ivoa.net/std/TAP \end{verbatim} -For TAP-1.1 we define new (versioned) standard identifier for then query feature: - -\begin{verbatim} -ivo://ivoa.net/std/TAP#query-1.1 -\end{verbatim} +For TAP-1.1 we use the same standardID but the version attribute of the capability should +use the minor version (e.g. version=``1.1''). In TAP, the base URL is described with a single standard identifier and the mandatory chilsd resources have specific names (section~\ref{sec:resources}). One or more DALI-async and DALI-sync interfaces to the query capability may be described using the prototype UWS registry extension (UWSRegExt). This allows service -providers to describe multiple resources that -deliver the query features (e.g. with different authentication methods) in +providers to describe multiple resources (interfaces) that +deliver the query features (e.g. with different protocols or authentication methods) in the VOSI-capabilities resource. The use of the VOSI-capabilities resource is described in DALI. @@ -858,10 +855,9 @@ \section{Metadata: TAP\kern-3pt\_SCHEMA} Column datatypes in the \tapschema{} are specified using the same concepts used in VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors -must also include the \verb|"size"| column and populate it where possible. The arraysize values -specified below for describing the \tapschema{} tables themselves is the most flexible -(``*'' means variable length with no maximum); implementors should use more restrictive values -that describe their implementation of the \tapschema{} tables (e.g. arraysize 64* to describe +must also include the \verb|"size"| column and populate it where possible. +Implementors should use arraysize values +that best describe their implementation of the \tapschema{} tables (e.g. arraysize 64* to describe a column with database type varchar(64)). Implementors may also use alternate character or numeric types (e.g. short or long instead of int or unicodeChar instead of char) as long as query execution is consistent with the recommended types. @@ -965,16 +961,20 @@ \subsection{Columns} implementors should use standard values such as those defined in DALI before inventing new xtype(s). -The arraysize column gives the length of variable length datatypes using the VOTable +The arraysize column gives the length of fixed and variable length datatypes using the VOTable array shape syntax. For example, a database column of type varchar(256) would be described with datatype ``char'' and arraysize ``256*''. Arrays, including multi-dimensional -arrays, are permitted for all VOTable primitive types. The ``size'' column is retained for backwards +arrays, are permitted for all VOTable primitive types. The \verb|"size"| column is retained for backwards compatibility to TAP-1.0 and must contain the integer value equivalent to arraysize when -possible and must be null if arraysize represents a multi-dimensional array. -To use the size column in a query, it must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the size column both +possible and must be null if arraysize is null or represents a multi-dimensional array. Both arraysize +and \verb|"size"| must be null for scalar numeric columns. + +To use the \verb|"size"| column in a query, the column name must be put in double quotes since +it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the +\verb|"size"| column both clients and servers MUST always (in particular, in the creation of the \tapschema) use lower case exclusively. In the next major version -of TAP, the ``size'' column will be removed. +of TAP, the \verb|"size"| column will be removed. For columns with a database type equivalent to BLOB or CLOB, most database systems support reference to these columns in the select clause but not in every other part of the query where @@ -1346,7 +1346,9 @@ \subsection{PR-TAP-1.1-20171124} in favour of string and integer. Specified which integers are actually booleans (0 or 1). Added list of foreign keys for \tapschema{} relational model. Clarified use of quoted identifiers for column names in -\tapschema. Added schema\_index column. +\tapschema. Added schema\_index column. Clarified when the \verb|"size"| column +in \tapschema can contain a value. Clarified that both arraysize and \verb|"size"| +must be null for scalar numeric columns. Fixed use of double-quotes which misbehaved inside tables. diff --git a/sample-capability.xml b/sample-capability.xml index 851d5ec..beebd67 100644 --- a/sample-capability.xml +++ b/sample-capability.xml @@ -8,7 +8,7 @@ http://www.ivoa.net/xml/VODataService/v1.1 http://www.ivoa.net/xml/VODataService/v1.1"> - + http://example.net/myTAP @@ -35,7 +35,7 @@ - https://example.net/myTAP/sync + http://example.net/myTAP/sync - http://myarchive.net/myTAP/tables + http://example.net/myTAP/tables - https://myarchive.net/myTAP/cert-tables + https://example.net/myTAP/cert-tables - http://myarchive.net/myTAP/auth-tables + https://example.net/myTAP/auth-tables From 9d5502eee27220665d92b31ac3484db0b98eb316 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Wed, 7 Mar 2018 09:04:39 +0000 Subject: [PATCH 31/68] TAP: Restoring text on VOTable being the default output format. See discussion at http://mail.ivoa.net/pipermail/dal/2018-March/007986.html --- TAP.tex | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/TAP.tex b/TAP.tex index dd6e4a4..cbdfeab 100644 --- a/TAP.tex +++ b/TAP.tex @@ -591,7 +591,13 @@ \subsubsection{FORMAT and RESPONSEFORMAT} The RESPONSEFORMAT parameter is fully described in DALI. For backwards compatibility, TAP-1.1 must also accept the FORMAT parameter as equivalent to -RESPONSEFORMAT. +RESPONSEFORMAT. +Specifying both FORMAT and RESPONSEFORMAT is undefined. + +If both the FORMAT and RESPONSEFORMAT parameters are omitted, the +default format is VOTable. A TAP service must support VOTable as an +output format, should support CSV and TSV output, and may support other +formats. \subsubsection{MAXREC} \label{sec:MAXREC} From 56a6b11315ce56c4122a72fdfd66833d881b720b Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 17 Apr 2018 15:38:54 +0000 Subject: [PATCH 32/68] added role diagram using ivoatex toolkit; updated PR timestamp --- Makefile | 4 +-- TAP.tex | 15 +++++--- role_diagram.xml | 92 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 105 insertions(+), 6 deletions(-) create mode 100644 role_diagram.xml diff --git a/Makefile b/Makefile index 6a1e981..193d305 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2017-11-24 +DOCDATE = 2018-04-16 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = PR @@ -17,7 +17,7 @@ DOCTYPE = PR SOURCES = $(DOCNAME).tex examples-sample.html sample-capability.xml # List of pixel image files to be included in submitted package -FIGURES = archdiag.png +FIGURES = role_diagram.pdf # List of PDF figures (for vector graphics) VECTORFIGURES = diff --git a/TAP.tex b/TAP.tex index cbdfeab..a424cc1 100644 --- a/TAP.tex +++ b/TAP.tex @@ -118,7 +118,7 @@ \subsection{Role within the VO Architecture} % Oh -- Notes don't need this; you'd have to remove archdiag.png % from FIGURES in the Makefile, too. -\includegraphics[width=0.9\textwidth]{archdiag.png} +\includegraphics[width=0.9\textwidth]{role_diagram.pdf} \caption{Architecture diagram for this document} \label{fig:archdiag} \end{figure} @@ -187,9 +187,14 @@ \subsection{Role within the VO Architecture} \xmlel{uws:Sync}-typed interfaces in order to allow clients to discover interfaces that support different authentication mechanisms via alternate resources within the service. -\end{description} - +\item[CDP \citep{std:CDP}] TAP services that support authenticated requests may require +delegation of user credentials in order for some features to work; such services +will have an associated credential service and could use delegated credentials for +remote calls that require authentication. For example, a URL specified in the UPLOAD +parameter may require authentication and the service would use delegated credentials +to perform the retrieval. +\end{description} \subsection{Motivating Use Cases} Below are some of the more common use cases that have motivated the development @@ -1342,7 +1347,9 @@ \subsection{Example: DALI-examples Document} \section{Changes from Previous Versions} -\subsection{PR-TAP-1.1-20171124} +\subsection{PR-TAP-1.1-20180416} + +Added updated IVOA architecture diagram showing role of TAP. Removed language that somehow defined or restricted usage of ADQL constructs in favour of just referring to the AQDL spec. Clarified use of serialisation diff --git a/role_diagram.xml b/role_diagram.xml new file mode 100644 index 0000000..bd792a4 --- /dev/null +++ b/role_diagram.xml @@ -0,0 +1,92 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 5bafdfce50248fe9bef3e88530093f04a521d9bc Mon Sep 17 00:00:00 2001 From: James Dempsey Date: Sat, 26 May 2018 11:28:27 +0000 Subject: [PATCH 33/68] Minor fixes to typos, ADQL ref and hyphenation of TAP_SCHEMA --- TAP.tex | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/TAP.tex b/TAP.tex index a424cc1..8559b44 100644 --- a/TAP.tex +++ b/TAP.tex @@ -30,9 +30,11 @@ \iftth \newcommand{\tapschema}{TAP\_SCHEMA} +\hyphenation{TAP\_SCHEMA} +\hyphenation{\tapschema} \newcommand{\tapupload}{TAP\_UPLOAD} \else -\newcommand{\tapschema}{{% +\newcommand{\tapschema}{\mbox{% \relsize{-0.5}TAP\discretionary{-}{}{\kern-2pt\_}SCHEMA}} \newcommand{\tapupload}{% {\relsize{-0.5}TAP\discretionary{-}{}{\kern-2pt\_}UPLOAD}} @@ -151,7 +153,7 @@ \subsection{Role within the VO Architecture} \item[VOTable \citep{2013ivoa.spec.0920O}] All TAP services must be able to serve query results in the VOTable format. Note that while TAP 1.1 does not require the use of any particular minor version of the VOtable standard, older -versions are missing features that are required and may be ususable in practice. +versions are missing features that are required and may be unusable in practice. For example, the overflow reporting and xtype attribute were introduced in VOTable 1.2 so that is the minimum viable version that must be used. \end{description} @@ -422,7 +424,7 @@ \subsection{/capabilities} use the minor version (e.g. version=``1.1''). In TAP, the base URL is described with a single standard identifier and the mandatory -chilsd resources have specific names (section~\ref{sec:resources}). One or more DALI-async +child resources have specific names (section~\ref{sec:resources}). One or more DALI-async and DALI-sync interfaces to the query capability may be described using the prototype UWS registry extension (UWSRegExt). This allows service providers to describe multiple resources (interfaces) that @@ -646,8 +648,8 @@ \subsubsection{UPLOAD} the upload of temporary tables in VOTable \citep{std:VOTable} format via the standard UPLOAD -parameter. The table-name(s) must be legal ADQL table names as defined in -\citet{std:ADQL} but restricted as described in section~\ref{sec:tap-schema}. +parameter. The table-name(s) must be legal table names as defined in +ADQL \citep{std:ADQL} but restricted as described in section~\ref{sec:tap-schema}. URIs may be simple URLs (e.g. with a URI scheme of http or https) or URIs that must be resolved (e.g. with a URI scheme of vos or param) to give the location of the table content. @@ -842,7 +844,7 @@ \section{Metadata: TAP\kern-3pt\_SCHEMA} There are several approaches to getting metadata for a given TAP service. All TAP services must support a set of tables in a schema named -\tapschema{} that describe the tables and columns included in the +\tapschema\ that describe the tables and columns included in the service. In addition to the \tapschema, there are two other ways to get metadata from a TAP service. First, the VOSI tables resource provides metadata on all tables and columns; this resource is described in From a8ecd0f427d68d36fcade942889166777c12e35d Mon Sep 17 00:00:00 2001 From: Mark Taylor Date: Tue, 12 Jun 2018 12:26:18 +0000 Subject: [PATCH 34/68] TAP typo fixes --- TAP.tex | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/TAP.tex b/TAP.tex index 8559b44..3d61b9f 100644 --- a/TAP.tex +++ b/TAP.tex @@ -140,7 +140,7 @@ \subsection{Role within the VO Architecture} implementors of TAP 1.1 are encouraged to support UWS 1.1 or later. \item[ADQL \citep{2008ivoa.spec.1030O}] A standards-compliant TAP -services must support queries written in the Astronomical Data Query +service must support queries written in the Astronomical Data Query Language. \item[VOSI \citep{std:VOSI11}] The VO Support Interfaces standard @@ -152,7 +152,7 @@ \subsection{Role within the VO Architecture} \item[VOTable \citep{2013ivoa.spec.0920O}] All TAP services must be able to serve query results in the VOTable format. Note that while TAP 1.1 does not -require the use of any particular minor version of the VOtable standard, older +require the use of any particular minor version of the VOTable standard, older versions are missing features that are required and may be unusable in practice. For example, the overflow reporting and xtype attribute were introduced in VOTable 1.2 so that is the minimum viable version that must be used. @@ -178,14 +178,14 @@ \subsection{Role within the VO Architecture} \item[TAPRegExt \citep{2012ivoa.spec.0827D}] While there is no formal requirement to that effect, the response on a TAP service's capabilities -endpoint should contain instances \xmlel{tr:TableAccess}-typed +endpoint should contain instances of \xmlel{tr:TableAccess}-typed capabilities in order to allow clients to discover several important aspects of a TAP service's capabilities (e.g., resource limits, output formats, user defined functions). \item[UWSRegExt (prototype)] While there is no formal requirement to that effect, the response on a TAP service's capabilities -endpoint should contain instances \xmlel{uws:Async}-typed and +endpoint should contain instances of \xmlel{uws:Async}-typed and \xmlel{uws:Sync}-typed interfaces in order to allow clients to discover interfaces that support different authentication mechanisms via alternate resources within the service. @@ -243,8 +243,8 @@ \subsubsection{ADQL Queries} may include sufficient table metadata to enable queries to be written directly. \subsubsection{Other Query Languages} -A TAP service implementor must be able to include support for other query languages, such -pass-through of native SQL directly to an underlying DBMS or simple key-vale +A TAP service implementor must be able to include support for other query languages, such as +pass-through of native SQL directly to an underlying DBMS or simple key-value (parameter-based) constraints, without making their service non-compliant with the specification. The service interface must allow for this and the service capabilities must be able to describe it. This mechanism also allows future developments within and outside the IVOA to be used without @@ -319,7 +319,7 @@ \section{Resources} \subsection{\{sync\}} \label{sec:tap-sync} -A TAP service must provide one or more web resources that represents the results +A TAP service must provide one or more web resources that represent the results of synchronous query execution. The {sync} resources must conform to the general rules for DALI-sync resources. The exact form of the query, and hence the representation of the resource, is defined by the query parameters as listed in @@ -1070,7 +1070,7 @@ \subsection{Foreign Keys} TAP_SCHEMA.keys.from_table -> TAP_SCHEMA.tables.table_name TAP_SCHEMA.keys.target_table -> TAP_SCHEMA.tables.table_name TAP_SCHEMA.key_columns.from_column -> TAP_SCHEMA.columns.column_name -TAP_SCHEMA.key_columns.target_column -> TAP_SCHEMA.colums.column_name +TAP_SCHEMA.key_columns.target_column -> TAP_SCHEMA.columns.column_name TAP_SCHEMA.key_columns.key_id -> TAP_SCHEMA.keys.key_id \end{verbatim} From 1fdd29f4b1b1d4f1ca0dabffd296f5e5c4dd119b Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 29 Aug 2018 16:18:14 +0000 Subject: [PATCH 35/68] Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities --- Makefile | 2 +- TAP.tex | 43 ++++++++++++++++++++++--------------------- sample-capability.xml | 42 ++++++++++++++++++------------------------ 3 files changed, 41 insertions(+), 46 deletions(-) diff --git a/Makefile b/Makefile index 193d305..cf977b1 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2018-04-16 +DOCDATE = 2018-08-30 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = PR diff --git a/TAP.tex b/TAP.tex index 3d61b9f..ad62d7e 100644 --- a/TAP.tex +++ b/TAP.tex @@ -22,6 +22,7 @@ \editor{Patrick Dowler} +\previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{PR-TAP-1.1-20180416} \previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{PR-TAP-1.1-20170830} \previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{WD-TAP-1.1-20170707} \previousversion[http://www.ivoa.net/Documents/TAP/20160428/]{WD-TAP-1.1-20160428} @@ -183,19 +184,16 @@ \subsection{Role within the VO Architecture} aspects of a TAP service's capabilities (e.g., resource limits, output formats, user defined functions). -\item[UWSRegExt (prototype)] While there is no formal -requirement to that effect, the response on a TAP service's capabilities -endpoint should contain instances of \xmlel{uws:Async}-typed and -\xmlel{uws:Sync}-typed interfaces in order to allow clients to discover -interfaces that support different authentication mechanisms via alternate -resources within the service. - \item[CDP \citep{std:CDP}] TAP services that support authenticated requests may require delegation of user credentials in order for some features to work; such services will have an associated credential service and could use delegated credentials for remote calls that require authentication. For example, a URL specified in the UPLOAD parameter may require authentication and the service would use delegated credentials to perform the retrieval. + +\item[UWSRegExt \citep{note:UWSRegExt}] TAP services that support authenticated access may provide additional endpoints (under the base URL) that process authenticated requests. This allows clients to discover the appropriate endpoint (one that is usable with current credentials). VOSI-capabilities +does not provide a way to completely describe this; UWSRegExt describes a usable mechanism that +can be used until a standard is developed. \end{description} \subsection{Motivating Use Cases} @@ -423,23 +421,22 @@ \subsection{/capabilities} For TAP-1.1 we use the same standardID but the version attribute of the capability should use the minor version (e.g. version=``1.1''). -In TAP, the base URL is described with a single standard identifier and the mandatory -child resources have specific names (section~\ref{sec:resources}). One or more DALI-async -and DALI-sync interfaces to the query capability may be described using the prototype UWS -registry extension (UWSRegExt). This allows service -providers to describe multiple resources (interfaces) that -deliver the query features (e.g. with different protocols or authentication methods) in -the VOSI-capabilities resource. +A TAP service consists of a related set of resource types, as listed above (section~\ref{sec:resources} : TAP-sync, TAP-async, VOSI-capabilities, VOSI-availability, and optionally VOSI-tables and DALI-examples. In some cases a client needs to identify a related "bundle" of endpoints providing one each of some or all of these resources in order to orchestrate its interaction with the TAP service. In TAP 1.0, this identification was straightforward, since only one instance of each resource type existed, and these were present at fixed locations relative to the TAP service base URL. In TAP 1.1, the capabilities document may declare multiple variants for some or all of these resource types, for instance to support different authentication contexts, and identifying the related bundle of endpoints that should be used given particular authentication requirements is therefore no longer trivial. -The use of the VOSI-capabilities resource is described in DALI. - -For example, the returned capabilities document for a service supporting TAP -might look as follows: +For example, the returned capabilities document for a service supporting TAP and using the prototype UWSRegExt \citep{note:UWSRegExt} extension might look as follows: \lstinputlisting[language=XML,basicstyle=\footnotesize] {sample-capability.xml} -The first interface with type vs:ParamHTTP gives the base URL; this is expected to be +Clients are free to combine the declared interfaces in any way they see fit, but the recommended way to interpret a TAP capabilities document as a list of TAP endpoint bundles is as follows: +\begin{itemize} +\item There is one default bundle, corresponding to the TAP 1.0 endpoints. If the service allows unauthenticated access at all, it should usually be provided by this default bundle. +\item There may also be one or more authenticated bundles. Each distinct security method declared on an interface in the capabilities document (value of an interface/securityMethod/@standardId XPath) defines one authenticated bundle. Each endpoint sharing the same security method is in the same bundle; if no endpoint is declared with that security method, the corresponding default endpoint is used. +\end{itemize} + +The example above therefore defines the default bundle and two authenticated bundles, defined by the security methods \verb|ivo://ivoa.net/sso#BasicAA| and \verb|ivo://ivoa.net/sso#tls-with-certificate| respectively. Each of these authenticated bundles explicitly declares its TAP-sync, TAP-async and VOSI-tables endpoints, and implicitly uses the default endpoints for VOSI-capabilities and VOSI-availability. + +The base URL is given by the interface with type vs:ParamHTTP; this is expected to be included in registry records and support finding TAP services in a simple and backwards compatible manner. The subsequent interface elements describe combinations of access URL and security method(s) that can be used by clients to make authenticated calls. They also @@ -584,7 +581,7 @@ \subsubsection{QUERY} all values must be supported (e.g. selecting all columns from an uploaded table) for all types even if comparisons are not supported. -Note: Although it is allowed by the ADQL syntax (version 2.0 at least), clients should be careful when +Note: Although it is allowed by the ADQL-2.0 syntax, clients should be careful when mixing constants and column references for coordinate system and coordinate values. For example, POINT('ICRS', t.ra, t.dec) does not cause t.ra and t.dec to be transformed to ICRS; it simply tells the service to treat the values as @@ -623,7 +620,7 @@ \subsubsection{MAXREC} FORMAT=votable). Note: in this version of TAP, this is the only mechanism to learn some of the detailed metadata, such as coordinate systems used. -The output truncation caused by the MAXREC parameter occurs after any +The output truncation caused by non-zero values the MAXREC parameter occurs after any limitations imposed by the query and the overflow indicator is only added if the query result is actually truncated. For example: @@ -1349,6 +1346,10 @@ \subsection{Example: DALI-examples Document} \section{Changes from Previous Versions} +\subsection{PR-TAP-1.1-20180830} + +Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. + \subsection{PR-TAP-1.1-20180416} Added updated IVOA architecture diagram showing role of TAP. diff --git a/sample-capability.xml b/sample-capability.xml index beebd67..1a62c90 100644 --- a/sample-capability.xml +++ b/sample-capability.xml @@ -2,6 +2,7 @@ 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" xsi:schemaLocation= "http://www.ivoa.net/xml/VOSICapabilities/v1.0 http://www.ivoa.net/xml/VOSICapabilities/v1.0 @@ -9,43 +10,36 @@ http://www.ivoa.net/xml/VODataService/v1.1"> + http://example.net/myTAP - + + http://example.net/myTAP/async - + + http://example.net/myTAP/sync + + + + https://example.net/myTAP/auth-async - + + https://example.net/myTAP/auth-sync + + + + + https://example.net/myTAP/cert-async - - - http://example.net/myTAP/sync - - - https://example.net/myTAP/auth-sync - - - + https://example.net/myTAP/cert-sync From 759af2f7e31f3da940c5ada1972b6a6abbb92f34 Mon Sep 17 00:00:00 2001 From: Marco Molinaro Date: Fri, 31 Aug 2018 06:49:14 +0000 Subject: [PATCH 36/68] TAP-1.1: drafting 1.0 to 1.1 summary of changes --- TAP.tex | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 113 insertions(+), 1 deletion(-) diff --git a/TAP.tex b/TAP.tex index ad62d7e..a96b1bf 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1474,7 +1474,119 @@ \subsection{Changes from TAP-1.0} fixed paths /async and /sync are still required and are to provide anonymous query access, which should be compatible with existing services. -\bibliography{ivoatex/ivoabib,ivoatex/docrepo} +\section{Condensed TAP-1.1 from TAP-1.0 changes} + +\subsection{General Improvements and Clarifications} + +Added updated IVOA architecture diagram showing role of TAP. + +Clarified dependency on minor versions of related standards with some recommendations on +using newer versions. + +Format tables so column headers are bold. Fixed numerous typos and gramnmatical errors. Fixed use of double-quotes which misbehaved inside tables. + +Restructured the document and removed text that duplicates material from DALI. + +Rewrite the overly long introduction with some basic use cases to help define +the scope and tell readers what TAP is supposed to accomplish. + +Made presence of a TABLE element on VOTable output only required for +successful queries. + +Fixed URL to schema in VOSI-capabilities example. + +Completed the references section. + +\subsection{New Features (including changes from related specifications} + +Added example use of UWS-1.1 blocking requests. + +Added an example for \verb|examples|. + +\subsection{Removed specifications} + +Removed remaining uses of PQL; replaced one example with something more clearly non-standard. + +Removed REQUEST and VERSION parameters from interface. + +Removed obsolete REQUEST=doQuery from examples. + +\subsection{ADQL Clarifications} + +Clarified that the QUERY param is intended for use with other values of LANG and is not +reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. + +Clarified required and optional ADQL geometric functions. +Changed language about mandatory ADQL geometry function support back to optional (should in +the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. + +Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow +indicator and that MAXREC always overrides limitations in the query (e.g. +TOP in an ADQL query). + +Removed language that somehow defined or restricted usage of ADQL constructs in +favour of just referring to the AQDL spec. Clarified use of serialisation +rules for extended types defined in DALI. + +\subsection{TAP\_SCHEMA Changes} + +Added table\_index and column\_index to \tapschema. +Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we +now use the VOTabletype system. + +Added paragraph specifying allowed values for \tapschema.tables.table\_type. + +Removed explicit datatype/arraysize/xtype from \tapschema{} description +in favour of string and integer. Specified which integers are actually +booleans (0 or 1). Added list of foreign keys for \tapschema{} +relational model. Clarified use of quoted identifiers for column names in +\tapschema. Added schema\_index column. +Clarified ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column. + +Added advice that the size column \tapschema.columns must always be used +as a quoted identifier because it is a reserved word in many RDBMS +servers. Added arraysize column to \tapschema.columns to replace size and +deprecated size (which will be removed in the next major version). + +Improved guidance for allowed table names for UPLOAD, clarified that +multiple UPLOAD parameters accumulate. Clarified that services +must support quoted identifiers. Advise that services should assign unique +column names in cases where they generate the name. + +Clarified that services are not required to support queries that reference tables +in different schema. This is primarily to allow the \tapschema{} to be implemented +in a different server from the content. + +\subsection{VOSI/UWS related changes} + +Defined standardID values for the async and sync resource types and explicitly +allow for multiple of each resource (typically to support authentication). The +fixed paths /async and /sync are still required and are to provide anonymous +query access, which should be compatible with existing services. +Added details and VOSI-capabilities example for providing multiple resources with different +authentication requirements. Clarified that VOSI-availability is no longer restricted to a +specific name or location. + +Strongly recommend that VOSI resources allow anonymous access. + +Fixed BasicAA security method in capabilities example. Included use of prototype +UWSRegExt interface tags in capabilities example and removed use of separate +standardID values for async and sync. + +Added explicit reference to VOSI-tables. Updates capabilities example to describe a +tables-1.1 capability. + +Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. + +\subsection{Datatype mapping} + +Completed the mapping table from VOTable to RDBMS datatypes using DALI-1.1 xtype values. + +Changed arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. + +Explicitly relaxed datatype and arraysize used in \tapschema{} tables. Fixed various cross-references and typos. + +\bibliography{ivoatex/ivoabib,ivoatex/docrepo} \end{document} From 1e4a61c2afde21003de941600201dc139d116ab3 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 4 Sep 2018 15:13:22 +0000 Subject: [PATCH 37/68] swapped order of appendices and clarified some noted changes --- TAP.tex | 206 +++++++++++++++++++++++++------------------------------- 1 file changed, 93 insertions(+), 113 deletions(-) diff --git a/TAP.tex b/TAP.tex index a96b1bf..c39e94b 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1344,7 +1344,99 @@ \subsection{Example: DALI-examples Document} \appendix -\section{Changes from Previous Versions} +\section{Changes from TAP-1.0 to TAP-1.1} + +\subsection{General Improvements and Clarifications} + +Added updated IVOA architecture diagram showing role of TAP. + +Clarified dependency on minor versions of related standards with some recommendations on +using newer versions. + +Removed text that duplicates material from DALI. + +Rewrite the introduction with some basic use cases to help define +the scope and tell readers what TAP is supposed to accomplish. + +Made presence of a TABLE element on VOTable output only required for +successful queries. + +\subsection{New Features (including changes from related specifications} + +Added example use of UWS-1.1 blocking requests. + +Added an example for \verb|examples|. + +\subsection{Removed specifications} + +Removed remaining uses and examples of PQL; replaced one example with something more clearly non-standard. + +Removed REQUEST and VERSION parameters from interface. Removed obsolete REQUEST=doQuery from examples. + +\subsection{ADQL Clarifications} + +Clarified that the QUERY param is intended for use with other values of LANG and is not +reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. + +Clarified required and optional ADQL geometric functions. +Changed language about mandatory ADQL geometry function support back to optional (should in +the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. + +Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow +indicator and that MAXREC always overrides limitations in the query (e.g. +TOP in an ADQL query). + +Removed language that somehow defined or restricted usage of ADQL constructs in +favour of just referring to the AQDL spec. Clarified use of serialisation +rules for extended types defined in DALI. + +\subsection{Datatype mapping} + +Added arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. + +\subsection{TAP\_SCHEMA Changes} + +Added schema\_index, table\_index and column\_index to \tapschema. + +Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we +now use the VOTabletype system. + +Added paragraph specifying allowed values for \tapschema.tables.table\_type. + +Removed explicit datatype/arraysize/xtype from \tapschema{} description +in favour of string and integer. Specified which integers are actually +booleans (0 or 1). Added list of foreign keys for \tapschema{} +relational model. Clarified use of quoted identifiers for column names in +\tapschema. Added schema\_index column. +Clarified ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column). + +Added advice that the ``size'' column \tapschema.columns must always be used +as a quoted identifier because it is a reserved word in many RDBMS +servers. Note: ``size'' is now deprecated (will be removed in the next major version). + +Improved guidance for allowed table names for UPLOAD, clarified that +multiple UPLOAD parameters accumulate. Clarified that services +must support quoted identifiers. Advise that services should assign unique +column names in cases where they generate the name. + +Clarified that services are not required to support queries that reference tables +in different schema. This is primarily to allow the \tapschema{} to be implemented +in a different server from the content. + +\subsection{VOSI/UWS related changes} + +Made use of prototype UWSREgExt to tag interfaces values for the async and sync resources. This allows +services to provide alternate resources for authenticated queries (using differnet securityMethod(s) within +each interface). Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. + +Added details and VOSI-capabilities example for providing multiple resources with different +authentication requirements. Clarified that VOSI-availability is no longer restricted to a +specific name or location. + +Added explicit reference to VOSI-tables. Updates capabilities example to describe a +tables-1.1 capability. + +\section{Detailed Changes from Previous Versions} \subsection{PR-TAP-1.1-20180830} @@ -1474,118 +1566,6 @@ \subsection{Changes from TAP-1.0} fixed paths /async and /sync are still required and are to provide anonymous query access, which should be compatible with existing services. -\section{Condensed TAP-1.1 from TAP-1.0 changes} - -\subsection{General Improvements and Clarifications} - -Added updated IVOA architecture diagram showing role of TAP. - -Clarified dependency on minor versions of related standards with some recommendations on -using newer versions. - -Format tables so column headers are bold. Fixed numerous typos and gramnmatical errors. Fixed use of double-quotes which misbehaved inside tables. - -Restructured the document and removed text that duplicates material from DALI. - -Rewrite the overly long introduction with some basic use cases to help define -the scope and tell readers what TAP is supposed to accomplish. - -Made presence of a TABLE element on VOTable output only required for -successful queries. - -Fixed URL to schema in VOSI-capabilities example. - -Completed the references section. - -\subsection{New Features (including changes from related specifications} - -Added example use of UWS-1.1 blocking requests. - -Added an example for \verb|examples|. - -\subsection{Removed specifications} - -Removed remaining uses of PQL; replaced one example with something more clearly non-standard. - -Removed REQUEST and VERSION parameters from interface. - -Removed obsolete REQUEST=doQuery from examples. - -\subsection{ADQL Clarifications} - -Clarified that the QUERY param is intended for use with other values of LANG and is not -reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. - -Clarified required and optional ADQL geometric functions. -Changed language about mandatory ADQL geometry function support back to optional (should in -the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. - -Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow -indicator and that MAXREC always overrides limitations in the query (e.g. -TOP in an ADQL query). - -Removed language that somehow defined or restricted usage of ADQL constructs in -favour of just referring to the AQDL spec. Clarified use of serialisation -rules for extended types defined in DALI. - -\subsection{TAP\_SCHEMA Changes} - -Added table\_index and column\_index to \tapschema. - -Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we -now use the VOTabletype system. - -Added paragraph specifying allowed values for \tapschema.tables.table\_type. - -Removed explicit datatype/arraysize/xtype from \tapschema{} description -in favour of string and integer. Specified which integers are actually -booleans (0 or 1). Added list of foreign keys for \tapschema{} -relational model. Clarified use of quoted identifiers for column names in -\tapschema. Added schema\_index column. -Clarified ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column. - -Added advice that the size column \tapschema.columns must always be used -as a quoted identifier because it is a reserved word in many RDBMS -servers. Added arraysize column to \tapschema.columns to replace size and -deprecated size (which will be removed in the next major version). - -Improved guidance for allowed table names for UPLOAD, clarified that -multiple UPLOAD parameters accumulate. Clarified that services -must support quoted identifiers. Advise that services should assign unique -column names in cases where they generate the name. - -Clarified that services are not required to support queries that reference tables -in different schema. This is primarily to allow the \tapschema{} to be implemented -in a different server from the content. - -\subsection{VOSI/UWS related changes} - -Defined standardID values for the async and sync resource types and explicitly -allow for multiple of each resource (typically to support authentication). The -fixed paths /async and /sync are still required and are to provide anonymous -query access, which should be compatible with existing services. -Added details and VOSI-capabilities example for providing multiple resources with different -authentication requirements. Clarified that VOSI-availability is no longer restricted to a -specific name or location. - -Strongly recommend that VOSI resources allow anonymous access. - -Fixed BasicAA security method in capabilities example. Included use of prototype -UWSRegExt interface tags in capabilities example and removed use of separate -standardID values for async and sync. - -Added explicit reference to VOSI-tables. Updates capabilities example to describe a -tables-1.1 capability. - -Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. - -\subsection{Datatype mapping} - -Completed the mapping table from VOTable to RDBMS datatypes using DALI-1.1 xtype values. - -Changed arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. - -Explicitly relaxed datatype and arraysize used in \tapschema{} tables. Fixed various cross-references and typos. \bibliography{ivoatex/ivoabib,ivoatex/docrepo} From d56a49d73a3651335ba2463993572ea5fbc6022b Mon Sep 17 00:00:00 2001 From: James Dempsey Date: Thu, 6 Sep 2018 07:31:14 +0000 Subject: [PATCH 38/68] Add references to updated sections in changelog, add extra section headings in intro,comment out changelog for changes which no longer appear --- TAP.tex | 69 +++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 27 deletions(-) diff --git a/TAP.tex b/TAP.tex index c39e94b..15d0b8f 100644 --- a/TAP.tex +++ b/TAP.tex @@ -83,6 +83,8 @@ \section*{Conformance-related definitions} \section{Introduction} +\label{sec:Introduction} + The Table Access Protocol (TAP) is a web-service protocol that gives access to collections of tabular data referred to collectively as a tableset. TAP services accept queries posed against the tableset available via the service and @@ -108,6 +110,7 @@ \section{Introduction} services. \subsection{Role within the VO Architecture} +\label{sec:Role} NOTE: not in TAP-1.0 @@ -228,6 +231,8 @@ \subsubsection{Query Standard Data Models} be able to declare their support for data models as well as the way that model elements are mapped to tables and columns. +\subsection{Query Languages} + \subsubsection{ADQL Queries} The Astronomical Data Query Language ADQL \citep{std:ADQL} is the standard query language for the IVOA. Support for ADQL queries is mandatory. ADQL can be @@ -248,6 +253,8 @@ \subsubsection{Other Query Languages} also allows future developments within and outside the IVOA to be used without revising the TAP specification. +\subsection{Query Execution} + \subsubsection{Asynchronous Queries} Asynchronous queries allow for long running queries to complete without the client maintaining a connection to the service. Results are stored by @@ -505,7 +512,7 @@ \subsection{/examples} in invalid RDF statements. An example of a response from a TAP service's examples endpoint is given -in section~\ref{sect:example-example}. +in section~\ref{sec:example-example}. \subsection{Parameters} \label{sec:parameters} @@ -1236,6 +1243,7 @@ \subsubsection{Modify a Query Job Before Execution} check and possibly negotiate the UWS job control parameters. \subsubsection{Running a Query} +\label{sec:example-RunningQuery} The phase URL shows the progress of the job. When the job is created by the service it will normally be set to PENDING, but might be set to ERROR if the service has rejected the job. If the phase is ERROR, then the error URL should @@ -1331,7 +1339,7 @@ \subsection{Example: Synchronous Query} redirects to obtain the result. \subsection{Example: DALI-examples Document} -\label{sect:example-example} +\label{sec:example-example} The following is a full document a service might serve from its \verb|/examples| endpoint; note that you can add arbitrary styling or @@ -1348,43 +1356,43 @@ \section{Changes from TAP-1.0 to TAP-1.1} \subsection{General Improvements and Clarifications} -Added updated IVOA architecture diagram showing role of TAP. +Added updated IVOA architecture diagram showing role of TAP (\ref{sec:Role}). Clarified dependency on minor versions of related standards with some recommendations on -using newer versions. +using newer versions (\ref{sec:Role}). Removed text that duplicates material from DALI. Rewrite the introduction with some basic use cases to help define -the scope and tell readers what TAP is supposed to accomplish. +the scope and tell readers what TAP is supposed to accomplish (\ref{sec:Introduction}). -Made presence of a TABLE element on VOTable output only required for -successful queries. +% Made presence of a TABLE element on VOTable output only required for +% successful queries. \subsection{New Features (including changes from related specifications} -Added example use of UWS-1.1 blocking requests. +Added example use of UWS-1.1 blocking requests (\ref{sec:example-RunningQuery}). -Added an example for \verb|examples|. +Added an example for \verb|examples| (\ref{sec:example-example}). \subsection{Removed specifications} Removed remaining uses and examples of PQL; replaced one example with something more clearly non-standard. -Removed REQUEST and VERSION parameters from interface. Removed obsolete REQUEST=doQuery from examples. +Removed REQUEST and VERSION parameters from interface. Removed obsolete REQUEST=doQuery from examples (\ref{sec:parameters}). \subsection{ADQL Clarifications} Clarified that the QUERY param is intended for use with other values of LANG and is not -reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. +reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. (\ref{sec:QUERY}) Clarified required and optional ADQL geometric functions. Changed language about mandatory ADQL geometry function support back to optional (should in -the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. +the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. (\ref{sec:QUERY}) Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow indicator and that MAXREC always overrides limitations in the query (e.g. -TOP in an ADQL query). +TOP in an ADQL query). (\ref{sec:MAXREC}) Removed language that somehow defined or restricted usage of ADQL constructs in favour of just referring to the AQDL spec. Clarified use of serialisation @@ -1392,49 +1400,56 @@ \subsection{ADQL Clarifications} \subsection{Datatype mapping} -Added arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. +Added arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype (\ref{sec:tap-schema-columns}). +Recommend use of VOTableType in VOSI-tables output (\ref{sec:vosi-tables}). \subsection{TAP\_SCHEMA Changes} -Added schema\_index, table\_index and column\_index to \tapschema. +Added schema\_index, table\_index and column\_index to \tapschema (\ref{sec:tap-schema}). -Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we -now use the VOTabletype system. +% Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we +% now use the VOTabletype system. -Added paragraph specifying allowed values for \tapschema.tables.table\_type. +Added paragraph specifying allowed values for \tapschema.tables.table\_type\ (\ref{sec:tap-schema-tables}). Removed explicit datatype/arraysize/xtype from \tapschema{} description in favour of string and integer. Specified which integers are actually booleans (0 or 1). Added list of foreign keys for \tapschema{} relational model. Clarified use of quoted identifiers for column names in -\tapschema. Added schema\_index column. +\tapschema. +% Added schema\_index column. Clarified ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column). +(\ref{sec:tap-schema-columns}) Added advice that the ``size'' column \tapschema.columns must always be used as a quoted identifier because it is a reserved word in many RDBMS servers. Note: ``size'' is now deprecated (will be removed in the next major version). +(\ref{sec:tap-schema-columns}) Improved guidance for allowed table names for UPLOAD, clarified that multiple UPLOAD parameters accumulate. Clarified that services must support quoted identifiers. Advise that services should assign unique column names in cases where they generate the name. +(\ref{sec:UPLOAD}) -Clarified that services are not required to support queries that reference tables -in different schema. This is primarily to allow the \tapschema{} to be implemented -in a different server from the content. +% Clarified that services are not required to support queries that reference tables +% in different schema. This is primarily to allow the \tapschema{} to be implemented +% in a different server from the content. \subsection{VOSI/UWS related changes} -Made use of prototype UWSREgExt to tag interfaces values for the async and sync resources. This allows +Made use of prototype UWSRegExt to tag interfaces values for the async and sync resources. This allows services to provide alternate resources for authenticated queries (using differnet securityMethod(s) within -each interface). Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. +each interface). (\ref{sec:vosi-capabilities}) +Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. (\ref{sec:Role}) Added details and VOSI-capabilities example for providing multiple resources with different -authentication requirements. Clarified that VOSI-availability is no longer restricted to a -specific name or location. +authentication requirements (\ref{sec:vosi-capabilities}). +Clarified that VOSI-availability is no longer restricted to a +specific name or location (\ref{sec:resources}). Added explicit reference to VOSI-tables. Updates capabilities example to describe a -tables-1.1 capability. +tables-1.1 capability (\ref{sec:resources}). \section{Detailed Changes from Previous Versions} From 8c550eac0f72bfe822c3fb6e2254baba213ebafb Mon Sep 17 00:00:00 2001 From: James Dempsey Date: Thu, 6 Sep 2018 08:31:23 +0000 Subject: [PATCH 39/68] Hide working comment --- TAP.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TAP.tex b/TAP.tex index 15d0b8f..d7dffa2 100644 --- a/TAP.tex +++ b/TAP.tex @@ -112,7 +112,7 @@ \section{Introduction} \subsection{Role within the VO Architecture} \label{sec:Role} -NOTE: not in TAP-1.0 +% NOTE: not in TAP-1.0 \begin{figure} \centering From fe11cdfa63d93bc5f3e77c51b9fc750ce690772e Mon Sep 17 00:00:00 2001 From: Mark Taylor Date: Wed, 12 Sep 2018 10:03:54 +0000 Subject: [PATCH 40/68] TAP-1.1: fix some typos --- TAP.tex | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/TAP.tex b/TAP.tex index d7dffa2..843fc45 100644 --- a/TAP.tex +++ b/TAP.tex @@ -527,7 +527,7 @@ \subsection{Parameters} enforced only when the TAP request is executed (not when individual HTTP requests are handled). Thus, for asynchronous TAP queries, the parameter requirements must be satisfied (and errors returned if not) only when the query -is run in (in the sense of UWS job execution). Specifically, asynchronous +is run (in the sense of UWS job execution). Specifically, asynchronous queries may be created with with no parameters and multiple, subsequent HTTP POST actions may specify the parameters in any order. @@ -627,7 +627,7 @@ \subsubsection{MAXREC} FORMAT=votable). Note: in this version of TAP, this is the only mechanism to learn some of the detailed metadata, such as coordinate systems used. -The output truncation caused by non-zero values the MAXREC parameter occurs after any +The output truncation caused by non-zero values of the MAXREC parameter occurs after any limitations imposed by the query and the overflow indicator is only added if the query result is actually truncated. For example: @@ -731,7 +731,7 @@ \subsection{INFO elements} self-document the query response), but clients should not depend on these. \begin{verbatim} - + ... select * from stuff.items @@ -882,7 +882,7 @@ \section{Metadata: TAP\kern-3pt\_SCHEMA} \tapschema{} to describe additional aspects of their service not covered by this specification. Implementors may also include additional columns in the standard tables described below. For example, one could include a column -with a timestamp saying when metadata values were was last modified. +with a timestamp saying when metadata values were last modified. \subsection{Schemas} \label{sec:tap-schema-schemas} @@ -1439,7 +1439,7 @@ \subsection{TAP\_SCHEMA Changes} \subsection{VOSI/UWS related changes} Made use of prototype UWSRegExt to tag interfaces values for the async and sync resources. This allows -services to provide alternate resources for authenticated queries (using differnet securityMethod(s) within +services to provide alternate resources for authenticated queries (using different securityMethod(s) within each interface). (\ref{sec:vosi-capabilities}) Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. (\ref{sec:Role}) @@ -1483,7 +1483,7 @@ \subsection{PR-TAP-1.1-20180416} Removed obsolete REQUEST=doQuery from examples. -Added explicit reference to VOSI-tables. Updates capabilitioes example to describe a +Added explicit reference to VOSI-tables. Updated capabilities example to describe a tables-1.1 capability. Clarified dependency on minor versions of related standards with some recommendations on @@ -1498,7 +1498,7 @@ \subsection{PR-TAP-1.1-20170830} Removed remaining uses of PQL; replaced one example with something more clearly non-standard. -Removed restriction from previous WD that the ``size'' column must be null for variable length arrays. In fact, ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column. +Removed restriction from previous WD that the ``size'' column must be null for variable length arrays. In fact, ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column). Changed language about mandatory ADQL geometry function support back to optional (should in the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. From b9a79ae2452b92f3ad896852a3f01a8da460e487 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Wed, 12 Sep 2018 12:44:43 +0000 Subject: [PATCH 41/68] TAP: Minor typographic and (hopefully) non-contenious fixes. Also, updated IVOA REC references to their latest versions. --- TAP.tex | 145 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 83 insertions(+), 62 deletions(-) diff --git a/TAP.tex b/TAP.tex index 843fc45..67d64d2 100644 --- a/TAP.tex +++ b/TAP.tex @@ -30,7 +30,7 @@ \iftth -\newcommand{\tapschema}{TAP\_SCHEMA} +\newcommand{\tapschema}{TAP\_SCHE\-MA} \hyphenation{TAP\_SCHEMA} \hyphenation{\tapschema} \newcommand{\tapupload}{TAP\_UPLOAD} @@ -91,7 +91,7 @@ \section{Introduction} return the query response as another table, in accord with the relational model. Queries may be submitted using various query languages and may execute synchronously or asynchronously. Support for the Astronomical Data Query -Language ADQL \citep{std:ADQL} is mandatory; support for other query languages is +Language ADQL \citep{2008ivoa.spec.1030O} is mandatory; support for other query languages is supported but optional. @@ -147,7 +147,7 @@ \subsection{Role within the VO Architecture} service must support queries written in the Astronomical Data Query Language. -\item[VOSI \citep{std:VOSI11}] The VO Support Interfaces standard +\item[VOSI \citep{2017ivoa.spec.0524G}] The VO Support Interfaces standard defines endpoints for metadata discovery; for TAP, this is the tables, capabilities, and availability endpoints. Note that while TAP 1.1 does not require the use of any particular minor version of the VOSI standard, @@ -166,7 +166,7 @@ \subsection{Role within the VO Architecture} TAP is related in other ways to the following IVOA standards: \begin{description} -\item[DALI \citep{std:DALI11}] The Data Access Layer Interface standard +\item[DALI \citep{2017ivoa.spec.0517D}] The Data Access Layer Interface standard gives general rules for the construction of DAL standards. TAP has been written against version 1.1 of DALI. In particular, TAP directly references DALI 1.1's serialisation rules for geometries and timestamps @@ -187,7 +187,7 @@ \subsection{Role within the VO Architecture} aspects of a TAP service's capabilities (e.g., resource limits, output formats, user defined functions). -\item[CDP \citep{std:CDP}] TAP services that support authenticated requests may require +\item[CDP \citep{2010ivoa.spec.0218P}] TAP services that support authenticated requests may require delegation of user credentials in order for some features to work; such services will have an associated credential service and could use delegated credentials for remote calls that require authentication. For example, a URL specified in the UPLOAD @@ -234,7 +234,7 @@ \subsubsection{Query Standard Data Models} \subsection{Query Languages} \subsubsection{ADQL Queries} -The Astronomical Data Query Language ADQL \citep{std:ADQL} is the standard +The Astronomical Data Query Language ADQL \citep{2008ivoa.spec.1030O} is the standard query language for the IVOA. Support for ADQL queries is mandatory. ADQL can be used to specify queries that access one or more tables provided by the TAP service, including the standard metadata tables. In general, the client must @@ -303,7 +303,7 @@ \section{Resources} At least one set of {sync} and {async} resources must be named /sync and /async respectively for backwards compatibility with TAP-1.0 (which required these names). Other {sync} and {async} resources may have service specific names. -As required by DALI \citep{std:DALI11}, all resources except the VOSI-availability must +As required by DALI \citep{2017ivoa.spec.0517D}, all resources except the VOSI-availability must be siblings of the VOSI-capabilities resource. The fixed name resources above (async, sync, tables) should be used for the @@ -348,7 +348,7 @@ \subsection{\{async\}} A TAP service must provide one or more web resource representing controls for asynchronous queries. Specifically, the web resource must conform to the general rules for DALI-async resources and thus represent a job-list -as specified in UWS \citep{std:UWS}. +as specified in UWS \citep{2016ivoa.spec.1024H}. The child web resources of the /async resource are as specified by UWS. These are descendants of the /async web-resource, and they include a web resource that @@ -426,9 +426,9 @@ \subsection{/capabilities} \end{verbatim} For TAP-1.1 we use the same standardID but the version attribute of the capability should -use the minor version (e.g. version=``1.1''). +use the minor version (e.g. \verb|version="1.1"|). -A TAP service consists of a related set of resource types, as listed above (section~\ref{sec:resources} : TAP-sync, TAP-async, VOSI-capabilities, VOSI-availability, and optionally VOSI-tables and DALI-examples. In some cases a client needs to identify a related "bundle" of endpoints providing one each of some or all of these resources in order to orchestrate its interaction with the TAP service. In TAP 1.0, this identification was straightforward, since only one instance of each resource type existed, and these were present at fixed locations relative to the TAP service base URL. In TAP 1.1, the capabilities document may declare multiple variants for some or all of these resource types, for instance to support different authentication contexts, and identifying the related bundle of endpoints that should be used given particular authentication requirements is therefore no longer trivial. +A TAP service consists of a related set of resource types, as listed above (section~\ref{sec:resources} : TAP-sync, TAP-async, VOSI-capabilities, VOSI-availability, and optionally VOSI-tables and DALI-examples. In some cases a client needs to identify a related ``bundle'' of endpoints providing one each of some or all of these resources in order to orchestrate its interaction with the TAP service. In TAP 1.0, this identification was straightforward, since only one instance of each resource type existed, and these were present at fixed locations relative to the TAP service base URL. In TAP 1.1, the capabilities document may declare multiple variants for some or all of these resource types, for instance to support different authentication contexts, and identifying the related bundle of endpoints that should be used given particular authentication requirements is therefore no longer trivial. For example, the returned capabilities document for a service supporting TAP and using the prototype UWSRegExt \citep{note:UWSRegExt} extension might look as follows: @@ -456,7 +456,7 @@ \subsection{/capabilities} The service capabilities must be accessible from a web resource with relative URL /capabilities that is a direct child of the root web resource. The /capabilities resource must be accessible via the http GET method. The content -is described by VOSI \citep{std:VOSI11}. +is described by VOSI \citep{2017ivoa.spec.0524G}. \subsection{/tables} \label{sec:vosi-tables} @@ -624,7 +624,7 @@ \subsubsection{MAXREC} try to execute the query, in which case a MAXREC=0 request can fail. A query with MAXREC=0 can be used with a simple query (e.g. SELECT * FROM some\_table) to extract and examine the VOTable metadata (assuming -FORMAT=votable). Note: in this version of TAP, this is the only mechanism to +RESPONSEFORMAT=votable). Note: in this version of TAP, this is the only mechanism to learn some of the detailed metadata, such as coordinate systems used. The output truncation caused by non-zero values of the MAXREC parameter occurs after any @@ -650,10 +650,10 @@ \subsubsection{UPLOAD} The UPLOAD parameter is described in DALI. Services should support the -upload of temporary tables in VOTable \citep{std:VOTable} format via the standard +upload of temporary tables in VOTable \citep{2013ivoa.spec.0920O} format via the standard UPLOAD parameter. The table-name(s) must be legal table names as defined in -ADQL \citep{std:ADQL} but restricted as described in section~\ref{sec:tap-schema}. +ADQL \citep{2008ivoa.spec.1030O} but restricted as described in section~\ref{sec:tap-schema}. URIs may be simple URLs (e.g. with a URI scheme of http or https) or URIs that must be resolved (e.g. with a URI scheme of vos or param) to give the location of the table content. @@ -713,7 +713,7 @@ \subsubsection{UPLOAD} \section{Use of VOTable} \label{sec:votable} -VOTable \citep{std:VOTable} is the standard format for output (query +VOTable \citep{2013ivoa.spec.0920O} is the standard format for output (query results) and input (table upload) in a TAP service so most of this section deals with how VOTable is used. However, rules about serialising column values also apply to other formats (e.g. CSV and TSV). @@ -745,7 +745,7 @@ \subsection{Successful Queries} The result of a query depends on the query language used and may be one or more tables in one or more resources. Unsupportable combinations of query result and -FORMAT (e.g. queries that produce multiple tables and an inherently +RESPONSEFORMAT (e.g. queries that produce multiple tables and an inherently single-table format like CSV) will cause the request to fail. Currently, an ADQL query result must be a single table (in a single file). @@ -784,10 +784,13 @@ \subsection{Errors} document with an appropriate HTTP-status code. TAP distinguishes three classes of exceptions. -Errors in the use of the HTTP protocol. +\begin{itemize} +\item Errors in the use of the HTTP protocol. + +\item TAP-level errors: Invalid TAP requests -Errors in the use of the TAP protocol, including both invalid requests and -failure of the service to complete valid requests. +\item TAP-level errors: Failure of the service to complete a valid request. +\end{itemize} Error documents for HTTP-level errors are not specified in the TAP protocol. Responses to these errors are typically generated by service containers and @@ -814,7 +817,7 @@ \subsection{Overflows} If a query is executed by a TAP service, the number of rows in the table of results may exceed a limit requested by the user (using the MAXREC parameter) or a limit set by the service implementation (the default or maximum value of -MAXREC). In these cases, the query is said to have 'overflowed'. Typically, a +MAXREC). In these cases, the query is said to have ``overflowed''. Typically, a TAP service will not detect an overflow until some part of the table of results has been sent to the client. @@ -829,15 +832,16 @@ \subsection{Overflows} \subsection{Mapping Table Datatypes} \label{sec:vot-rdbms} -This section describes the bi-directional mapping between VOTable and RDBMS + -geometric datatypes and extends the basic rules for serialising such values in +This section describes the bi-directional mapping between VOTable on the +one and the RDBMS (including its +geometric datatypes) on the other side. It extends the basic rules for serialising such values in VOTable described in DALI. These rules apply to input tables supplied via an UPLOAD parameter (see section~\ref{sec:UPLOAD}) and to result tables after successful query execution. The mapping to and from VOTable makes use of the datatype, arraysize, and xtype attributes. Mapping for primitive types (numbers and strings) is -straightforward; services should insure that input values behave as +straightforward; services should ensure that input values behave as expected in query processing and output values should have correct and complete metadata. Mapping for specially structured values use xtype(s) specified in DALI. The behaviour of such structured values in queries depends @@ -852,11 +856,11 @@ \section{Metadata: TAP\kern-3pt\_SCHEMA} service. In addition to the \tapschema, there are two other ways to get metadata from a TAP service. First, the VOSI tables resource provides metadata on all tables and columns; this resource is described in -(section~\ref{sec:vosi-tables}). The +section~\ref{sec:vosi-tables}. The VOSI tables resource provides the same metadata as the \tapschema{} but in a rigorously controlled format; the information in the -\tapschema{} is equivalent to that defined by the VODataService -\citep{std:VODS11}. Second, the client may specify a query of one or more +\tapschema{} is equivalent to that defined by VODataService +\citep{2010ivoa.spec.1202P}. Second, the client may specify a query of one or more tables setting the MAXREC parameter to 0 so that only the metadata regarding the requested fields is returned. Use of MAXREC is described in section~\ref{sec:MAXREC}. @@ -874,11 +878,11 @@ \section{Metadata: TAP\kern-3pt\_SCHEMA} VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors must also include the \verb|"size"| column and populate it where possible. Implementors should use arraysize values -that best describe their implementation of the \tapschema{} tables (e.g. arraysize 64* to describe -a column with database type varchar(64)). Implementors may also use alternate character or numeric types (e.g. short or long instead of int or unicodeChar instead of char) as long as +that best describe their implementation of the \tapschema{} tables (e.g., arraysize 64* to describe, +a column with database type varchar(64)). Implementors may also use alternate character or numeric types (e.g., short or long instead of int or unicodeChar instead of char) as long as query execution is consistent with the recommended types. -Implementors are permitted to include additional tables in the +Implementors may include additional tables in the \tapschema{} to describe additional aspects of their service not covered by this specification. Implementors may also include additional columns in the standard tables described below. For example, one could include a column @@ -972,9 +976,9 @@ \subsection{Columns} the name must be quoted (quoted identifier in ADQL) then the value must include the quotes. The type of a database column is described in the \tapschema.columns -table using three (3) columns with an additional (deprecated) column from TAP-1.0 +table using three columns with an additional (deprecated) column from TAP-1.0 for backwards compatibility. The allowed values for datatype and the syntax for arraysize -are specified in VOTable \citep{std:VOTable}. Values for xtype are not restricted per se but +are specified in VOTable \citep{2013ivoa.spec.0920O}. Values for xtype are not restricted per se but implementors should use standard values such as those defined in DALI before inventing new xtype(s). @@ -1044,12 +1048,12 @@ \subsection{Foreign Keys} \end{inlinetable} The key\_id values are unique and used only to join with the -\tapschema.key\_columns table below. There may be +key\_columns table below. There may be one or more rows with different key\_id values and a pair of tables to denote one or more ways to join the tables. The table \tapschema.key\_columns must contain the -following columns to describe the columns that make up a foreign key: +following columns to describe the col\-umns that make up a foreign key: \begin{inlinetable} \begin{tabular}{l l l} @@ -1085,7 +1089,7 @@ \subsection{Foreign Keys} \section{Examples} \label{sec:examples} -The UWS pattern is specified in the UWS specification \citep{std:UWS} and its application to TAP in +The UWS pattern is specified in the UWS specification \citep{2016ivoa.spec.1024H} and its application to TAP in section~\ref{sec:tap-async}. TAP services may implement UWS 1.0 or a later version. This section gives examples of the exchange of messages between a @@ -1094,8 +1098,8 @@ \section{Examples} \subsection{Example: Asynchronous Query} Consider a TAP service at http://example.com/tap. TAP mandates that the asynchronous requests be directed to http://example.com/tap/async (e.g. for -anonymous queries). This URL points to the list of 'jobs'; i.e. the list of -queries currently or recently executed. +anonymous queries). This URL points to the list of ``jobs'', i.e., the list of +queries currently executing or recently executed. \subsubsection{Creating and Executing a Simple Query} @@ -1132,7 +1136,7 @@ \subsubsection{Creating and Executing a Simple Query} \end{verbatim} The client may have to check the phase multiple times until the job -finishes. If the service implements UWS 1.1 \citep{std:UWS11} or later, a blocking call +finishes. If the service implements UWS 1.1 \citep{2016ivoa.spec.1024H} or later, a blocking call can be used instead of polling. Once the job reaches the COMPLETED phase, the results can be obtained from the results resource: @@ -1157,7 +1161,7 @@ \subsubsection{Modify a Query Job Before Execution} While the job is in the PENDING phase, the job parameters may be modified by additional POST(s) to the parameters resource (see -\citet{std:DALI11}), for example: +\citet{2017ivoa.spec.0517D}), for example: \begin{verbatim} HTTP POST http://example.com/tap/async/42/parameters @@ -1324,7 +1328,7 @@ \subsection{Example: Synchronous Query} \end{verbatim} In this example, the output format defaults to VOTable; -the FORMAT parameter could be added to select a different format. +the RESPONSEFORMAT parameter could be added to select a different format. Many implementations will implement synchronous query execution using the common POST-redirect-GET pattern. If this is the case, the response from the @@ -1356,77 +1360,91 @@ \section{Changes from TAP-1.0 to TAP-1.1} \subsection{General Improvements and Clarifications} -Added updated IVOA architecture diagram showing role of TAP (\ref{sec:Role}). +\begin{itemize} -Clarified dependency on minor versions of related standards with some recommendations on +\item Added updated IVOA architecture diagram showing role of TAP (\ref{sec:Role}). + +\item Clarified dependency on minor versions of related standards with some recommendations on using newer versions (\ref{sec:Role}). -Removed text that duplicates material from DALI. +\item Removed text that duplicates material from DALI. -Rewrite the introduction with some basic use cases to help define +\item Rewrote the introduction with some basic use cases to help define the scope and tell readers what TAP is supposed to accomplish (\ref{sec:Introduction}). % Made presence of a TABLE element on VOTable output only required for % successful queries. +\end{itemize} \subsection{New Features (including changes from related specifications} -Added example use of UWS-1.1 blocking requests (\ref{sec:example-RunningQuery}). +\begin{itemize} +\item Added example use of UWS-1.1 blocking requests (\ref{sec:example-RunningQuery}). -Added an example for \verb|examples| (\ref{sec:example-example}). +\item Added an example for \verb|examples| (\ref{sec:example-example}). +\end{itemize} \subsection{Removed specifications} -Removed remaining uses and examples of PQL; replaced one example with something more clearly non-standard. +\begin{itemize} +\item Removed remaining uses and examples of PQL; replaced one example with something more clearly non-standard. -Removed REQUEST and VERSION parameters from interface. Removed obsolete REQUEST=doQuery from examples (\ref{sec:parameters}). +\item Removed REQUEST and VERSION parameters from interface. Removed obsolete REQUEST=doQuery from examples (\ref{sec:parameters}). +\end{itemize} \subsection{ADQL Clarifications} -Clarified that the QUERY param is intended for use with other values of LANG and is not +\begin{itemize} +\item Clarified that the QUERY param is intended for use with other values of LANG and is not reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. (\ref{sec:QUERY}) -Clarified required and optional ADQL geometric functions. +\item Clarified required and optional ADQL geometric functions. Changed language about mandatory ADQL geometry function support back to optional (should in the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. (\ref{sec:QUERY}) -Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow +\item Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow indicator and that MAXREC always overrides limitations in the query (e.g. TOP in an ADQL query). (\ref{sec:MAXREC}) -Removed language that somehow defined or restricted usage of ADQL constructs in +\item Removed language that somehow defined or restricted usage of ADQL constructs in favour of just referring to the AQDL spec. Clarified use of serialisation rules for extended types defined in DALI. +\end{itemize} \subsection{Datatype mapping} -Added arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype (\ref{sec:tap-schema-columns}). -Recommend use of VOTableType in VOSI-tables output (\ref{sec:vosi-tables}). +\begin{itemize} +\item Added arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype (\ref{sec:tap-schema-columns}). + +\item Recommend use of VOTableType in VOSI-tables output (\ref{sec:vosi-tables}). +\end{itemize} \subsection{TAP\_SCHEMA Changes} -Added schema\_index, table\_index and column\_index to \tapschema (\ref{sec:tap-schema}). +\begin{itemize} +\item Added schema\_index, table\_index and column\_index to \tapschema (\ref{sec:tap-schema}). % Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we % now use the VOTabletype system. -Added paragraph specifying allowed values for \tapschema.tables.table\_type\ (\ref{sec:tap-schema-tables}). +\item Added paragraph specifying allowed values for \tapschema.tables.table\_type\ (\ref{sec:tap-schema-tables}). -Removed explicit datatype/arraysize/xtype from \tapschema{} description +\item Removed explicit datatype/arraysize/xtype from \tapschema{} description in favour of string and integer. Specified which integers are actually booleans (0 or 1). Added list of foreign keys for \tapschema{} relational model. Clarified use of quoted identifiers for column names in \tapschema. % Added schema\_index column. -Clarified ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column). + +\item Clarified ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column). (\ref{sec:tap-schema-columns}) -Added advice that the ``size'' column \tapschema.columns must always be used +\item Added advice that the ``size'' column \tapschema.columns must always be used as a quoted identifier because it is a reserved word in many RDBMS servers. Note: ``size'' is now deprecated (will be removed in the next major version). (\ref{sec:tap-schema-columns}) -Improved guidance for allowed table names for UPLOAD, clarified that +\item Improved guidance for allowed table names for UPLOAD, clarified that multiple UPLOAD parameters accumulate. Clarified that services must support quoted identifiers. Advise that services should assign unique column names in cases where they generate the name. @@ -1435,21 +1453,24 @@ \subsection{TAP\_SCHEMA Changes} % Clarified that services are not required to support queries that reference tables % in different schema. This is primarily to allow the \tapschema{} to be implemented % in a different server from the content. +\end{itemize} \subsection{VOSI/UWS related changes} -Made use of prototype UWSRegExt to tag interfaces values for the async and sync resources. This allows +\begin{itemize} +\item Made use of prototype UWSRegExt to tag interfaces values for the async and sync resources. This allows services to provide alternate resources for authenticated queries (using different securityMethod(s) within each interface). (\ref{sec:vosi-capabilities}) Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. (\ref{sec:Role}) -Added details and VOSI-capabilities example for providing multiple resources with different +\item Added details and VOSI-capabilities example for providing multiple resources with different authentication requirements (\ref{sec:vosi-capabilities}). Clarified that VOSI-availability is no longer restricted to a specific name or location (\ref{sec:resources}). -Added explicit reference to VOSI-tables. Updates capabilities example to describe a +\item Added explicit reference to VOSI-tables. Updates capabilities example to describe a tables-1.1 capability (\ref{sec:resources}). +\end{itemize} \section{Detailed Changes from Previous Versions} From 80aed8e24d8d94a604bb06f878b01742d2082700 Mon Sep 17 00:00:00 2001 From: Mark Taylor Date: Wed, 12 Sep 2018 12:51:21 +0000 Subject: [PATCH 42/68] TAP-1.1: fix some more typos --- TAP.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/TAP.tex b/TAP.tex index 67d64d2..57e2673 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1376,7 +1376,7 @@ \subsection{General Improvements and Clarifications} % successful queries. \end{itemize} -\subsection{New Features (including changes from related specifications} +\subsection{New Features (including changes from related specifications)} \begin{itemize} \item Added example use of UWS-1.1 blocking requests (\ref{sec:example-RunningQuery}). @@ -1491,7 +1491,7 @@ \subsection{PR-TAP-1.1-20180416} booleans (0 or 1). Added list of foreign keys for \tapschema{} relational model. Clarified use of quoted identifiers for column names in \tapschema. Added schema\_index column. Clarified when the \verb|"size"| column -in \tapschema can contain a value. Clarified that both arraysize and \verb|"size"| +in \tapschema\ can contain a value. Clarified that both arraysize and \verb|"size"| must be null for scalar numeric columns. Fixed use of double-quotes which misbehaved inside tables. From 59b51b91dc62d58e9b919991c70bc74bbce5d4e7 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 18 Sep 2018 17:55:04 +0000 Subject: [PATCH 43/68] removed alternate capabilities resource; changed resource types to usse DALI-style; fixed coord sys use in examples; fixed text to specify using version a ttr on interface instead of capability; fixed cross-ref to allowed table name syntax; clarified changelog summary wrt. ADQL; clarified that example use of UWSRegExt is non-normative; clarified where ParamHTTP and uws-typed interfaces are to be included --- TAP.tex | 59 +++++++++++++++++++++++++------------------- examples-sample.html | 2 +- 2 files changed, 35 insertions(+), 26 deletions(-) diff --git a/TAP.tex b/TAP.tex index 57e2673..1153f48 100644 --- a/TAP.tex +++ b/TAP.tex @@ -283,14 +283,13 @@ \section{Resources} \sptablerule \textbf{resource type} & \textbf{resource name} & \textbf{required} \\ \sptablerule -{sync} & /sync & must \\ -{async} & /async & must \\ -{sync} & service specific & may (alternate authentication method) \\ -{async} & service specific & may (alternate authentication method) \\ +TAP-sync & /sync & must \\ +TAP-async & /async & must \\ +TAP-sync & service specific & may (alternate authentication method) \\ +TAP-async & service specific & may (alternate authentication method) \\ VOSI-availability & service specific & must (should be anonymous) \\ VOSI-availability & service specific & may (alternate authentication method) \\ -VOSI-capabilities & /capabilities & must (should be anonymous) \\ -VOSI-capabilities & service specific & may (alternate authentication method) \\ +VOSI-capabilities & /capabilities & must (must be anonymous) \\ VOSI-tables & /tables & should \\ VOSI-tables & service specific & may (alternate authentication method) \\ DALI-examples & /examples & should \\ @@ -321,7 +320,7 @@ \section{Resources} an HTML page describing the scientific usage and content of the service. TAP clients must not depend on a specific representation of the root web-resource. -\subsection{\{sync\}} +\subsection{TAP-sync} \label{sec:tap-sync} A TAP service must provide one or more web resources that represent the results @@ -342,7 +341,7 @@ \subsection{\{sync\}} which require an up-to-date representation of volatile data or metadata must use HTTP POST. -\subsection{\{async\}} +\subsection{TAP-async} \label{sec:tap-async} A TAP service must provide one or more web resource representing controls for @@ -412,12 +411,12 @@ \subsection{\{async\}} data rows. Details on interacting with these resources are specified in the UWS standard; for examples specific to TAP see section~\ref{sec:examples} below. -\subsection{availability} +\subsection{VOSI-availability} \label{sec:vosi-availability} The use of the VOSI-availability resource is described in DALI. -\subsection{/capabilities} +\subsection{VOSI-capabilities} \label{sec:vosi-capabilities} The TAP-1.0 standard is identified using @@ -425,12 +424,12 @@ \subsection{/capabilities} ivo://ivoa.net/std/TAP \end{verbatim} -For TAP-1.1 we use the same standardID but the version attribute of the capability should +For TAP-1.1 we use the same standardID but the version attribute of the interfaces should use the minor version (e.g. \verb|version="1.1"|). A TAP service consists of a related set of resource types, as listed above (section~\ref{sec:resources} : TAP-sync, TAP-async, VOSI-capabilities, VOSI-availability, and optionally VOSI-tables and DALI-examples. In some cases a client needs to identify a related ``bundle'' of endpoints providing one each of some or all of these resources in order to orchestrate its interaction with the TAP service. In TAP 1.0, this identification was straightforward, since only one instance of each resource type existed, and these were present at fixed locations relative to the TAP service base URL. In TAP 1.1, the capabilities document may declare multiple variants for some or all of these resource types, for instance to support different authentication contexts, and identifying the related bundle of endpoints that should be used given particular authentication requirements is therefore no longer trivial. -For example, the returned capabilities document for a service supporting TAP and using the prototype UWSRegExt \citep{note:UWSRegExt} extension might look as follows: +For example, the returned capabilities document for a service supporting TAP and using the prototype UWSRegExt \citep{note:UWSRegExt} extension might look as follows. Note: this use of the extended interface types is non-normative in that the namespace and values shown here may not be the same as those recommended by a future standard; this is simply a prototype extension schema that can be used to describe alternate interfaces. \lstinputlisting[language=XML,basicstyle=\footnotesize] {sample-capability.xml} @@ -443,22 +442,23 @@ \subsection{/capabilities} The example above therefore defines the default bundle and two authenticated bundles, defined by the security methods \verb|ivo://ivoa.net/sso#BasicAA| and \verb|ivo://ivoa.net/sso#tls-with-certificate| respectively. Each of these authenticated bundles explicitly declares its TAP-sync, TAP-async and VOSI-tables endpoints, and implicitly uses the default endpoints for VOSI-capabilities and VOSI-availability. -The base URL is given by the interface with type vs:ParamHTTP; this is expected to be -included in registry records and support finding TAP services in a simple and backwards +The base URL is given by the interface with type vs:ParamHTTP; this interface supports +finding and using TAP services in a simple and backwards compatible manner. The subsequent interface elements describe combinations of access URL and security method(s) that can be used by clients to make authenticated calls. They also use the type of the interface to specify that the particular access URL uses an async or sync invocation pattern. Note that in this example the anonymous async and sync endpoints are described explicitly but could also be inferred from the base service URL using the standard -names. Service implementors must include the base interface for backwards compatibility in -registry queries and should include all relevant UWS-typed interfaces for direct client use. +names. Service implementors must include the base interface in registry records and VOSI-capabilities documents +for backwards compatibility in registry queries and must include relevant UWS-typed interfaces in the +VOSI-capabilities document for direct client use. The service capabilities must be accessible from a web resource with relative URL /capabilities that is a direct child of the root web resource. The /capabilities resource must be accessible via the http GET method. The content is described by VOSI \citep{2017ivoa.spec.0524G}. -\subsection{/tables} +\subsection{VOSI-tables} \label{sec:vosi-tables} The table metadata should be accessible from a web resource with relative URL @@ -473,7 +473,7 @@ \subsection{/tables} Services which do not implement the /tables resource must respond with an HTTP response code of 404 when this resource is accessed. -\subsection{/examples} +\subsection{DALI-examples} \label{sec:dali-examples} A successful GET from this endpoint MUST yield a document with a MIME type of either @@ -653,7 +653,7 @@ \subsubsection{UPLOAD} upload of temporary tables in VOTable \citep{2013ivoa.spec.0920O} format via the standard UPLOAD parameter. The table-name(s) must be legal table names as defined in -ADQL \citep{2008ivoa.spec.1030O} but restricted as described in section~\ref{sec:tap-schema}. +ADQL \citep{2008ivoa.spec.1030O} but restricted as described in section~\ref{sec:tap-schema-tables}. URIs may be simple URLs (e.g. with a URI scheme of http or https) or URIs that must be resolved (e.g. with a URI scheme of vos or param) to give the location of the table content. @@ -1070,18 +1070,27 @@ \subsection{Foreign Keys} There may be one or more rows with a specific key\_id to denote single or multi-column keys. -For the \tapschema{} itself, services should enforce and list the following foreign keys: +For the \tapschema{} itself, services should enforce and describe the following foreign keys: \begin{verbatim} TAP_SCHEMA.tables.schema_name -> TAP_SCHEMA.schemas.schema_name TAP_SCHEMA.columns.table_name -> TAP_SCHEMA.tables.table_name TAP_SCHEMA.keys.from_table -> TAP_SCHEMA.tables.table_name TAP_SCHEMA.keys.target_table -> TAP_SCHEMA.tables.table_name +TAP_SCHEMA.key_columns.key_id -> TAP_SCHEMA.keys.key_id +\end{verbatim} + +In addition, the following constraints are expected to be satisfied by the \tapschema{} model, but +RDBMS systems may not allow the creation of foreign key constraints because the target column(s) +are not unique: + +\begin{verbatim} TAP_SCHEMA.key_columns.from_column -> TAP_SCHEMA.columns.column_name TAP_SCHEMA.key_columns.target_column -> TAP_SCHEMA.columns.column_name -TAP_SCHEMA.key_columns.key_id -> TAP_SCHEMA.keys.key_id \end{verbatim} +These relations can be described in the \tapschema{} and should be enforced in the table content. + A TAP service must provide the tables listed above and may provide other tables in the \tapschema{} namespace. @@ -1398,9 +1407,9 @@ \subsection{ADQL Clarifications} \item Clarified that the QUERY param is intended for use with other values of LANG and is not reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. (\ref{sec:QUERY}) -\item Clarified required and optional ADQL geometric functions. -Changed language about mandatory ADQL geometry function support back to optional (should in -the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. (\ref{sec:QUERY}) +\item Defer to other standards concerning required and optional ADQL geometric functions (ADQL specifies, +TAPRegExt describes). +Clarified that DALI timestamp format support is required only in services where it can be used in queries. (\ref{sec:QUERY}) \item Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow indicator and that MAXREC always overrides limitations in the query (e.g. @@ -1414,7 +1423,7 @@ \subsection{ADQL Clarifications} \subsection{Datatype mapping} \begin{itemize} -\item Added arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype (\ref{sec:tap-schema-columns}). +\item Added arraysize and xtype to \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype (\ref{sec:tap-schema-columns}). \item Recommend use of VOTableType in VOSI-tables output (\ref{sec:vosi-tables}). \end{itemize} diff --git a/examples-sample.html b/examples-sample.html index bef2f23..1a9fd68 100644 --- a/examples-sample.html +++ b/examples-sample.html @@ -56,7 +56,7 @@

Query against coverage

 SELECT accref, seeing
   FROM cars.images
-      WHERE 1=INTERSECTS(coverage, circle('ICRS', 34, -4, 2))
+      WHERE 1=INTERSECTS(coverage, circle(NULL, 34, -4, 2))
       ORDER BY seeing

Of course, this concerns all SIAP and SSAP tables From 5fc3ccf82e01313d0c1652c31193d9741b17f1e7 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 21 Sep 2018 22:17:25 +0000 Subject: [PATCH 44/68] fixed example to use empty-string instead of NULL for coordsys clarified version attribute usage in VOSI-capabilities clarified meaning of string and integer in tap_schema impl --- TAP.tex | 24 ++++++++++++++---------- examples-sample.html | 2 +- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/TAP.tex b/TAP.tex index 1153f48..558b8c1 100644 --- a/TAP.tex +++ b/TAP.tex @@ -424,8 +424,10 @@ \subsection{VOSI-capabilities} ivo://ivoa.net/std/TAP \end{verbatim} -For TAP-1.1 we use the same standardID but the version attribute of the interfaces should -use the minor version (e.g. \verb|version="1.1"|). +For TAP-1.1 we use the same standardID for the capability but the version attribute of the interfaces must +use the minor version (e.g. \verb|version="1.1"|). Services are permitted to include interfaces with other +values of the version attribute to describe additional alternate interfaces; omitting the version attribute +is equivalent to \verb|version="1.0"|. A TAP service consists of a related set of resource types, as listed above (section~\ref{sec:resources} : TAP-sync, TAP-async, VOSI-capabilities, VOSI-availability, and optionally VOSI-tables and DALI-examples. In some cases a client needs to identify a related ``bundle'' of endpoints providing one each of some or all of these resources in order to orchestrate its interaction with the TAP service. In TAP 1.0, this identification was straightforward, since only one instance of each resource type existed, and these were present at fixed locations relative to the TAP service base URL. In TAP 1.1, the capabilities document may declare multiple variants for some or all of these resource types, for instance to support different authentication contexts, and identifying the related bundle of endpoints that should be used given particular authentication requirements is therefore no longer trivial. @@ -436,7 +438,7 @@ \subsection{VOSI-capabilities} Clients are free to combine the declared interfaces in any way they see fit, but the recommended way to interpret a TAP capabilities document as a list of TAP endpoint bundles is as follows: \begin{itemize} -\item There is one default bundle, corresponding to the TAP 1.0 endpoints. If the service allows unauthenticated access at all, it should usually be provided by this default bundle. +\item There is one default bundle, corresponding to the TAP 1.0 endpoints. If the service allows unauthenticated access at all, it should be provided by this default bundle. \item There may also be one or more authenticated bundles. Each distinct security method declared on an interface in the capabilities document (value of an interface/securityMethod/@standardId XPath) defines one authenticated bundle. Each endpoint sharing the same security method is in the same bundle; if no endpoint is declared with that security method, the corresponding default endpoint is used. \end{itemize} @@ -446,8 +448,8 @@ \subsection{VOSI-capabilities} finding and using TAP services in a simple and backwards compatible manner. The subsequent interface elements describe combinations of access URL and security method(s) that can be used by clients to make authenticated calls. They also -use the type of the interface to specify that the particular access URL uses an async or sync -invocation pattern. Note that in this example the anonymous async and sync endpoints are +use the type of the interface to specify that the particular access URL is a TAP-async or TAP-sync +resource. Note that in this example the anonymous async and sync endpoints are described explicitly but could also be inferred from the base service URL using the standard names. Service implementors must include the base interface in registry records and VOSI-capabilities documents for backwards compatibility in registry queries and must include relevant UWS-typed interfaces in the @@ -876,11 +878,13 @@ \section{Metadata: TAP\kern-3pt\_SCHEMA} Column datatypes in the \tapschema{} are specified using the same concepts used in VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors -must also include the \verb|"size"| column and populate it where possible. -Implementors should use arraysize values -that best describe their implementation of the \tapschema{} tables (e.g., arraysize 64* to describe, -a column with database type varchar(64)). Implementors may also use alternate character or numeric types (e.g., short or long instead of int or unicodeChar instead of char) as long as -query execution is consistent with the recommended types. +must also include the \verb|"size"| column and populate it where possible. In the details +below, \tapschema{} column types are either string or integer; implementers may chose an +appropriate data type that behaves the same way in queries and output (e.g. varchar(16) or +varchar(64) for string and smallint, int, or bigint for integer. +Implementors should use datatype and arraysize values +that best describe their implementation of the \tapschema{} tables (e.g., datatype char +and arraysize 64* to describe a column with database type varchar(64)). Implementors may include additional tables in the \tapschema{} to describe additional aspects of their service not diff --git a/examples-sample.html b/examples-sample.html index 1a9fd68..4a19304 100644 --- a/examples-sample.html +++ b/examples-sample.html @@ -56,7 +56,7 @@

Query against coverage

 SELECT accref, seeing
   FROM cars.images
-      WHERE 1=INTERSECTS(coverage, circle(NULL, 34, -4, 2))
+      WHERE 1=INTERSECTS(coverage, circle('', 34, -4, 2))
       ORDER BY seeing

Of course, this concerns all SIAP and SSAP tables From 31282211b845c1b752852bc0ff6f86262cc1a304 Mon Sep 17 00:00:00 2001 From: Mark Taylor Date: Mon, 24 Sep 2018 15:23:51 +0000 Subject: [PATCH 45/68] fix TAP text to recommend empty string not NULL for coordsys, plus one typo --This lie, and those below, will be ignored-- M TAP.tex --- TAP.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/TAP.tex b/TAP.tex index 558b8c1..5d1dda1 100644 --- a/TAP.tex +++ b/TAP.tex @@ -595,7 +595,7 @@ \subsubsection{QUERY} values. For example, POINT('ICRS', t.ra, t.dec) does not cause t.ra and t.dec to be transformed to ICRS; it simply tells the service to treat the values as being expressed in that coordinate system. Clients should avoid using the coordinate -system argument to geometric functions (use null value or use an +system argument to geometric functions (supply the empty string, or use an alternate function without the coordinate system argument if available). \subsubsection{FORMAT and RESPONSEFORMAT} @@ -879,7 +879,7 @@ \section{Metadata: TAP\kern-3pt\_SCHEMA} Column datatypes in the \tapschema{} are specified using the same concepts used in VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors must also include the \verb|"size"| column and populate it where possible. In the details -below, \tapschema{} column types are either string or integer; implementers may chose an +below, \tapschema{} column types are either string or integer; implementers may choose an appropriate data type that behaves the same way in queries and output (e.g. varchar(16) or varchar(64) for string and smallint, int, or bigint for integer. Implementors should use datatype and arraysize values From c0d83a4e2a6e4fb45903697745f26a1d1136a9d3 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Thu, 4 Oct 2018 15:17:58 +0000 Subject: [PATCH 46/68] TAP 1.1: Replacing "quoted" by "delimited" where necessary... ...to correctly name these beasts. --- TAP.tex | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/TAP.tex b/TAP.tex index 5d1dda1..5bcf641 100644 --- a/TAP.tex +++ b/TAP.tex @@ -977,7 +977,7 @@ \subsection{Columns} \end{inlinetable} The table\_name,column\_name (pair) values must be unique. If the column name is such that -the name must be quoted (quoted identifier in ADQL) then the value must include the quotes. +the name must be quoted (delimited identifier in ADQL) then the value must include the quotes. The type of a database column is described in the \tapschema.columns table using three columns with an additional (deprecated) column from TAP-1.0 @@ -1445,7 +1445,7 @@ \subsection{TAP\_SCHEMA Changes} \item Removed explicit datatype/arraysize/xtype from \tapschema{} description in favour of string and integer. Specified which integers are actually booleans (0 or 1). Added list of foreign keys for \tapschema{} -relational model. Clarified use of quoted identifiers for column names in +relational model. Clarified use of delimited identifiers for column names in \tapschema. % Added schema\_index column. @@ -1453,13 +1453,13 @@ \subsection{TAP\_SCHEMA Changes} (\ref{sec:tap-schema-columns}) \item Added advice that the ``size'' column \tapschema.columns must always be used -as a quoted identifier because it is a reserved word in many RDBMS +as a delimited identifier because it is a reserved word in many RDBMS servers. Note: ``size'' is now deprecated (will be removed in the next major version). (\ref{sec:tap-schema-columns}) \item Improved guidance for allowed table names for UPLOAD, clarified that multiple UPLOAD parameters accumulate. Clarified that services -must support quoted identifiers. Advise that services should assign unique +must support delimited identifiers. Advise that services should assign unique column names in cases where they generate the name. (\ref{sec:UPLOAD}) @@ -1502,7 +1502,7 @@ \subsection{PR-TAP-1.1-20180416} Removed explicit datatype/arraysize/xtype from \tapschema{} description in favour of string and integer. Specified which integers are actually booleans (0 or 1). Added list of foreign keys for \tapschema{} -relational model. Clarified use of quoted identifiers for column names in +relational model. Clarified use of delimited identifiers for column names in \tapschema. Added schema\_index column. Clarified when the \verb|"size"| column in \tapschema\ can contain a value. Clarified that both arraysize and \verb|"size"| must be null for scalar numeric columns. @@ -1564,7 +1564,7 @@ \subsection{WD-TAP-1.1-20161011} Strongly recommend that VOSI resources allow anonymous access. Relax restrictions on column names in uploaded tables; clarify that services -must support quoted identifiers. Advise that services should assign unique +must support delimited identifiers. Advise that services should assign unique column names in cases where they generate the name. \subsection{WD-TAP-1.1-20160428} @@ -1594,7 +1594,7 @@ \subsection{Changes from TAP-1.0} indicator. Added advice that the size column \tapschema.columns must always be used -as a quoted identifier because it is a reserved word in many RDBMS +as a delimited identifier because it is a reserved word in many RDBMS servers. Added arraysize column to \tapschema.columns to replace size and deprecated size (which will be removed in the next major version). From ad67fb9f43e0c8df7cb6acfcf34e33a1d711b6e9 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 10 Oct 2018 22:49:36 +0000 Subject: [PATCH 47/68] clarify equivalence of arraysize and size in tap_schema --- TAP.tex | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/TAP.tex b/TAP.tex index 5bcf641..031c41f 100644 --- a/TAP.tex +++ b/TAP.tex @@ -991,8 +991,9 @@ \subsection{Columns} described with datatype ``char'' and arraysize ``256*''. Arrays, including multi-dimensional arrays, are permitted for all VOTable primitive types. The \verb|"size"| column is retained for backwards compatibility to TAP-1.0 and must contain the integer value equivalent to arraysize when -possible and must be null if arraysize is null or represents a multi-dimensional array. Both arraysize -and \verb|"size"| must be null for scalar numeric columns. +possible (ignoring the variable-size indicator in arraysize) and must be null if arraysize is null or +represents a multi-dimensional array. For example, a column description with arraysize=``256*'' must also have +\verb|"size"|=``256''. Both arraysize and \verb|"size"| must be null for scalar numeric columns. To use the \verb|"size"| column in a query, the column name must be put in double quotes since it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the From 3ba960ba4bc769207e655e69a2a2e304e1e64414 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 24 Oct 2018 22:11:35 +0000 Subject: [PATCH 48/68] removed bogus foreign keys between tap_schema.ley_columns and tap_schema.columns in favour of text explaining the actual contraints --- Makefile | 2 +- TAP.tex | 23 ++++++++--------------- 2 files changed, 9 insertions(+), 16 deletions(-) diff --git a/Makefile b/Makefile index cf977b1..00d1a16 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2018-08-30 +DOCDATE = 2018-10-24 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = PR diff --git a/TAP.tex b/TAP.tex index 031c41f..0735c26 100644 --- a/TAP.tex +++ b/TAP.tex @@ -22,8 +22,9 @@ \editor{Patrick Dowler} -\previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{PR-TAP-1.1-20180416} -\previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{PR-TAP-1.1-20170830} +\previousversion[http://www.ivoa.net/Documents/TAP/20180830/]{PR-TAP-1.1-20180830} +\previousversion[http://www.ivoa.net/Documents/TAP/20180416/]{PR-TAP-1.1-20180416} +\previousversion[http://www.ivoa.net/Documents/TAP/20170830/]{PR-TAP-1.1-20170830} \previousversion[http://www.ivoa.net/Documents/TAP/20170707/]{WD-TAP-1.1-20170707} \previousversion[http://www.ivoa.net/Documents/TAP/20160428/]{WD-TAP-1.1-20160428} \previousversion[http://www.ivoa.net/Documents/TAP/1.0]{TAP-1.0} @@ -1058,7 +1059,7 @@ \subsection{Foreign Keys} of tables to denote one or more ways to join the tables. The table \tapschema.key\_columns must contain the -following columns to describe the col\-umns that make up a foreign key: +following columns to describe the columns that make up a foreign key: \begin{inlinetable} \begin{tabular}{l l l} @@ -1072,8 +1073,7 @@ \subsection{Foreign Keys} \end{tabular} \end{inlinetable} -There may be one or more rows with a specific key\_id to -denote single or multi-column keys. +There may be one or more rows with a specific key\_id to denote single or multi-column keys. For the \tapschema{} itself, services should enforce and describe the following foreign keys: @@ -1085,16 +1085,9 @@ \subsection{Foreign Keys} TAP_SCHEMA.key_columns.key_id -> TAP_SCHEMA.keys.key_id \end{verbatim} -In addition, the following constraints are expected to be satisfied by the \tapschema{} model, but -RDBMS systems may not allow the creation of foreign key constraints because the target column(s) -are not unique: - -\begin{verbatim} -TAP_SCHEMA.key_columns.from_column -> TAP_SCHEMA.columns.column_name -TAP_SCHEMA.key_columns.target_column -> TAP_SCHEMA.columns.column_name -\end{verbatim} - -These relations can be described in the \tapschema{} and should be enforced in the table content. +In addition to the above constraints, the from\_table and from\_column (in \tapschema.keys and +\tapschema.key\_columns respectively) must refer to column in the \tapschema.columns table. Likewise, +the target\_table and target\_column must also refer to a column in \tapschema.columns. A TAP service must provide the tables listed above and may provide other tables in the \tapschema{} namespace. From 1fd62aae9acfca620752b3821e0e12cc821d8909 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 25 Oct 2018 14:43:57 +0000 Subject: [PATCH 49/68] tweak to langauge describing tap_schema key_columns expectations --- TAP.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/TAP.tex b/TAP.tex index 0735c26..a29ed50 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1086,8 +1086,8 @@ \subsection{Foreign Keys} \end{verbatim} In addition to the above constraints, the from\_table and from\_column (in \tapschema.keys and -\tapschema.key\_columns respectively) must refer to column in the \tapschema.columns table. Likewise, -the target\_table and target\_column must also refer to a column in \tapschema.columns. +\tapschema.key\_columns respectively) must refer to an entry in the \tapschema.columns table. Likewise, +the target\_table and target\_column must also refer to an entry in \tapschema.columns. A TAP service must provide the tables listed above and may provide other tables in the \tapschema{} namespace. From 0378bc7650a3a2d3cb256f0434ebfa71e70683f8 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Sun, 11 Nov 2018 14:31:17 +0000 Subject: [PATCH 50/68] changed the already mandatory VOSI-availability to must allow anonymous changed text about the root resource representation from may to should and more clearly suggest human readable HTML doc --- TAP.tex | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/TAP.tex b/TAP.tex index a29ed50..25a61d1 100644 --- a/TAP.tex +++ b/TAP.tex @@ -288,7 +288,7 @@ \section{Resources} TAP-async & /async & must \\ TAP-sync & service specific & may (alternate authentication method) \\ TAP-async & service specific & may (alternate authentication method) \\ -VOSI-availability & service specific & must (should be anonymous) \\ +VOSI-availability & service specific & must (must be anonymous) \\ VOSI-availability & service specific & may (alternate authentication method) \\ VOSI-capabilities & /capabilities & must (must be anonymous) \\ VOSI-tables & /tables & should \\ @@ -310,16 +310,15 @@ \section{Resources} primary access mode of the service; this is typically anonymous access and other resource names may be used for authenticated access. However, if a service only supports authenticated access to these resources, the fixed names -may be used for authenticated access. The VOSI resources should allow anonymous -access as they can be used by clients to determine if the service is available +may be used for authenticated access. The VOSI-availabilty and -capabilities resources +must allow anonymous access as they can be used by clients to determine if the service is available and which resources to use with available security (authentication) methods. -The web resource at the root of the tree must represent the service as a whole. +The web resource at the root of the tree represents the service as a whole. This specification defines no standard representation for this root resource. -Implementations may provide a representation, or may return a '404 not found' -response to requests for the root web-resource. One possible representation is -an HTML page describing the scientific usage and content of the service. TAP -clients must not depend on a specific representation of the root web-resource. +Implementations should return a human readable document (HTML) describing +the service as a whole. TAP +clients should not depend on a specific representation of the root resource. \subsection{TAP-sync} \label{sec:tap-sync} From 3261a3b4528b18df4f43c0274d996de28eebd9ae Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 15 Mar 2019 20:43:13 +0000 Subject: [PATCH 51/68] updated doc, role diagram, and capabilities example to single-base-URL concensus --- Makefile | 2 +- TAP.tex | 104 +++++++++++++++++++----------------------- role_diagram.xml | 1 - sample-capability.xml | 57 ++++++----------------- 4 files changed, 61 insertions(+), 103 deletions(-) diff --git a/Makefile b/Makefile index 00d1a16..bdc1317 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2018-10-24 +DOCDATE = 2019-03-15 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = PR diff --git a/TAP.tex b/TAP.tex index 25a61d1..0da4a43 100644 --- a/TAP.tex +++ b/TAP.tex @@ -22,6 +22,7 @@ \editor{Patrick Dowler} +\previousversion[http://www.ivoa.net/Documents/TAP/20181024/]{PR-TAP-1.1-20181024} \previousversion[http://www.ivoa.net/Documents/TAP/20180830/]{PR-TAP-1.1-20180830} \previousversion[http://www.ivoa.net/Documents/TAP/20180416/]{PR-TAP-1.1-20180416} \previousversion[http://www.ivoa.net/Documents/TAP/20170830/]{PR-TAP-1.1-20170830} @@ -194,10 +195,6 @@ \subsection{Role within the VO Architecture} remote calls that require authentication. For example, a URL specified in the UPLOAD parameter may require authentication and the service would use delegated credentials to perform the retrieval. - -\item[UWSRegExt \citep{note:UWSRegExt}] TAP services that support authenticated access may provide additional endpoints (under the base URL) that process authenticated requests. This allows clients to discover the appropriate endpoint (one that is usable with current credentials). VOSI-capabilities -does not provide a way to completely describe this; UWSRegExt describes a usable mechanism that -can be used until a standard is developed. \end{description} \subsection{Motivating Use Cases} @@ -286,39 +283,29 @@ \section{Resources} \sptablerule TAP-sync & /sync & must \\ TAP-async & /async & must \\ -TAP-sync & service specific & may (alternate authentication method) \\ -TAP-async & service specific & may (alternate authentication method) \\ VOSI-availability & service specific & must (must be anonymous) \\ -VOSI-availability & service specific & may (alternate authentication method) \\ VOSI-capabilities & /capabilities & must (must be anonymous) \\ VOSI-tables & /tables & should \\ -VOSI-tables & service specific & may (alternate authentication method) \\ DALI-examples & /examples & should \\ -DALI-examples & service specific & may (alternate authentication method) \\ \sptablerule \end{tabular} \end{inlinetable} \medskip -At least one set of {sync} and {async} resources must be named /sync and -/async respectively for backwards compatibility with TAP-1.0 (which required -these names). Other {sync} and {async} resources may have service specific names. -As required by DALI \citep{2017ivoa.spec.0517D}, all resources except the VOSI-availability must -be siblings of the VOSI-capabilities resource. +A TAP service provides a single base URL with child resources for the various features in tbe table above. +As required by DALI \citep{2017ivoa.spec.0517D}, all resources (including the optional VOSI-tables +resource) except the VOSI-availability must be siblings of the VOSI-capabilities resource. -The fixed name resources above (async, sync, tables) should be used for the -primary access mode of the service; this is typically anonymous access and -other resource names may be used for authenticated access. However, if a -service only supports authenticated access to these resources, the fixed names -may be used for authenticated access. The VOSI-availabilty and -capabilities resources -must allow anonymous access as they can be used by clients to determine if the service is available -and which resources to use with available security (authentication) methods. +The fixed name resources above (async, sync, tables, and examples) are used for both anonynous and +authenticated access to the service; the consequences of having a single base URL are detailed below in +section~\ref{sec:vosi-capabilities}. The VOSI-availabilty and VOSI-capabilities resources must allow anonymous access as they can be used by clients to determine if the service is available and which resources to use with +available security (authentication) methods. The web resource at the root of the tree represents the service as a whole. This specification defines no standard representation for this root resource. Implementations should return a human readable document (HTML) describing -the service as a whole. TAP -clients should not depend on a specific representation of the root resource. +the service as a whole. TAP clients should not depend on a specific representation +of the root resource. \subsection{TAP-sync} \label{sec:tap-sync} @@ -424,41 +411,39 @@ \subsection{VOSI-capabilities} ivo://ivoa.net/std/TAP \end{verbatim} -For TAP-1.1 we use the same standardID for the capability but the version attribute of the interfaces must -use the minor version (e.g. \verb|version="1.1"|). Services are permitted to include interfaces with other -values of the version attribute to describe additional alternate interfaces; omitting the version attribute -is equivalent to \verb|version="1.0"|. - -A TAP service consists of a related set of resource types, as listed above (section~\ref{sec:resources} : TAP-sync, TAP-async, VOSI-capabilities, VOSI-availability, and optionally VOSI-tables and DALI-examples. In some cases a client needs to identify a related ``bundle'' of endpoints providing one each of some or all of these resources in order to orchestrate its interaction with the TAP service. In TAP 1.0, this identification was straightforward, since only one instance of each resource type existed, and these were present at fixed locations relative to the TAP service base URL. In TAP 1.1, the capabilities document may declare multiple variants for some or all of these resource types, for instance to support different authentication contexts, and identifying the related bundle of endpoints that should be used given particular authentication requirements is therefore no longer trivial. +For TAP-1.1 we use the same standardID value. The version attribute of the interfaces +must use the minor version (e.g. \verb|version="1.1"|) of the TAP standard; clients +should treat a missing version attribute is equivalent to \verb|version="1.0"|. -For example, the returned capabilities document for a service supporting TAP and using the prototype UWSRegExt \citep{note:UWSRegExt} extension might look as follows. Note: this use of the extended interface types is non-normative in that the namespace and values shown here may not be the same as those recommended by a future standard; this is simply a prototype extension schema that can be used to describe alternate interfaces. +The interface element within the TAP capability specifies the base URL of the service +under which the fixed-name resources specified above (section~\ref{sec:resources}) are located. +In addition to the accessURL element, the interface element may also contain zero or more securityMethod +elements that specify the supported authention methods. Zero such elements and a securityMethod with no standardID attribute are both interpretted as meaning anonymous; the latter should only be used if other securityMethod(s) are also specified and zero such elements is preferrable in an anonymous-only service. \lstinputlisting[language=XML,basicstyle=\footnotesize] {sample-capability.xml} -Clients are free to combine the declared interfaces in any way they see fit, but the recommended way to interpret a TAP capabilities document as a list of TAP endpoint bundles is as follows: -\begin{itemize} -\item There is one default bundle, corresponding to the TAP 1.0 endpoints. If the service allows unauthenticated access at all, it should be provided by this default bundle. -\item There may also be one or more authenticated bundles. Each distinct security method declared on an interface in the capabilities document (value of an interface/securityMethod/@standardId XPath) defines one authenticated bundle. Each endpoint sharing the same security method is in the same bundle; if no endpoint is declared with that security method, the corresponding default endpoint is used. -\end{itemize} +The example above descibes a TAP service that can be accessed anonymously or by autheticating with a cookie +(\verb|ivo://ivoa.net/sso#cookie|) or an X509 client certificate (\verb|ivo://ivoa.net/sso#tls-with-certificate|). +The same URL (e.g. \verb|https://example.net/tap/sync| for a synchronous query) would be used for both anonymous and authenticated access. -The example above therefore defines the default bundle and two authenticated bundles, defined by the security methods \verb|ivo://ivoa.net/sso#BasicAA| and \verb|ivo://ivoa.net/sso#tls-with-certificate| respectively. Each of these authenticated bundles explicitly declares its TAP-sync, TAP-async and VOSI-tables endpoints, and implicitly uses the default endpoints for VOSI-capabilities and VOSI-availability. +As a consequence of using a single base URL with fixed name child resources, all supported authentication +methods must be able to co-exist on the same URL. At this time, both anonymous and other authentication +methods can be made to work in this way except for HTTP Basic and Digest authentication. In general, +challenge-reponse methods will likely not be able to co-exist with methods that simply deliver credentials +(e.g. cookies or tokens via HTTP headers) with the request. While client certificate usage is technically also +a challenge-response method, this occurs during SSL socket setup and does not interfere with the HTTP request itself and can co-exist with anonymous https access (by making client certificate optional in the server +configuration). As a result of having a single base URL, one can provide an anonymous-only TAP service with http or https; once support for \verb|ivo://ivoa.net/sso#tls-with-certificate| is added, however, the entire service +must use https only. While one can provide a service with \verb|securityMethod="ivo://ivoa.net/sso#BasicAA"|, +this authentication method uses the HTTP protocol and thus cannot co-exist with other methods (including +anonymous); such a service would only be able to describe that single method. -The base URL is given by the interface with type vs:ParamHTTP; this interface supports -finding and using TAP services in a simple and backwards -compatible manner. The subsequent interface elements describe combinations of access URL -and security method(s) that can be used by clients to make authenticated calls. They also -use the type of the interface to specify that the particular access URL is a TAP-async or TAP-sync -resource. Note that in this example the anonymous async and sync endpoints are -described explicitly but could also be inferred from the base service URL using the standard -names. Service implementors must include the base interface in registry records and VOSI-capabilities documents -for backwards compatibility in registry queries and must include relevant UWS-typed interfaces in the -VOSI-capabilities document for direct client use. +In the example above, the VOSI-availability and VOSI-capabilities interfaces are anonymous (no securityMethod). +The VOSI-tables interface is typically also anonymous-only, but in the example we show that it may also support +anonymous and/or authenticated access. In general, clients that support authentication should be prepared to discover and use anonymous-only endpoints for some requests. -The service capabilities must be accessible from a web resource with relative -URL /capabilities that is a direct child of the root web resource. The -/capabilities resource must be accessible via the http GET method. The content -is described by VOSI \citep{2017ivoa.spec.0524G}. +In addition to the basic service descrption in the example above, services should use the TAPRegExt +\citep{std:TAPREGEXT} extension to provide additional metadata within the TAP capability. \subsection{VOSI-tables} \label{sec:vosi-tables} @@ -1464,14 +1449,11 @@ \subsection{TAP\_SCHEMA Changes} \subsection{VOSI/UWS related changes} \begin{itemize} -\item Made use of prototype UWSRegExt to tag interfaces values for the async and sync resources. This allows -services to provide alternate resources for authenticated queries (using different securityMethod(s) within -each interface). (\ref{sec:vosi-capabilities}) -Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. (\ref{sec:Role}) - -\item Added details and VOSI-capabilities example for providing multiple resources with different -authentication requirements (\ref{sec:vosi-capabilities}). -Clarified that VOSI-availability is no longer restricted to a +\item Added details and VOSI-capabilities example to clarify that there is one accessURL for a TAP service and +multiple authentication methods must co-exist in that single URL (\ref{sec:vosi-capabilities}). Clients are +expected to append the TAP-specific resource names (async and sync) to execute queries (\ref{sec:resources}). + +\item Clarified that VOSI-availability is no longer restricted to a specific name or location (\ref{sec:resources}). \item Added explicit reference to VOSI-tables. Updates capabilities example to describe a @@ -1480,6 +1462,12 @@ \subsection{VOSI/UWS related changes} \section{Detailed Changes from Previous Versions} +\subsection{PR-TAP-20190315} + +Modified the resources section to only allow the fixed name resources on a single base URL. Adapted the +VOSI-capabilities example and explanation to demonstrate the single base URL design and specify the meaning +of having zero or more securityMethod(s). Removed all use to the previously proposed UWSRegExt. + \subsection{PR-TAP-1.1-20180830} Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. diff --git a/role_diagram.xml b/role_diagram.xml index bd792a4..68dbaa2 100644 --- a/role_diagram.xml +++ b/role_diagram.xml @@ -20,7 +20,6 @@ with missing dependencies. --> - - - http://example.net/myTAP - - - - - http://example.net/myTAP/async - - - http://example.net/myTAP/sync - - - - - https://example.net/myTAP/auth-async - - - - https://example.net/myTAP/auth-sync - - - - - - https://example.net/myTAP/cert-async - - - - https://example.net/myTAP/cert-sync + https://example.net/srv + + + - - + - http://example.net/myTAP/capabilities + https://example.net/srv/capabilities + - http://example.net/myTAP/availability + https://example.net/srv/availability + - http://example.net/myTAP/tables - - - https://example.net/myTAP/cert-tables + https://example.net/srv/cert-tables + + + - - https://example.net/myTAP/auth-tables - - From 21eb798228a8516f0724da7ca8a5a5186110c81c Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 19 Mar 2019 14:16:17 +0000 Subject: [PATCH 52/68] TAP: - 1 typo. --- TAP.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TAP.tex b/TAP.tex index 0da4a43..5e397da 100644 --- a/TAP.tex +++ b/TAP.tex @@ -418,7 +418,7 @@ \subsection{VOSI-capabilities} The interface element within the TAP capability specifies the base URL of the service under which the fixed-name resources specified above (section~\ref{sec:resources}) are located. In addition to the accessURL element, the interface element may also contain zero or more securityMethod -elements that specify the supported authention methods. Zero such elements and a securityMethod with no standardID attribute are both interpretted as meaning anonymous; the latter should only be used if other securityMethod(s) are also specified and zero such elements is preferrable in an anonymous-only service. +elements that specify the supported authention methods. Zero such elements and a securityMethod with no standardID attribute are both interpreted as meaning anonymous; the latter should only be used if other securityMethod(s) are also specified and zero such elements is preferrable in an anonymous-only service. \lstinputlisting[language=XML,basicstyle=\footnotesize] {sample-capability.xml} From 922a1012a350708903f17451807b85e498a35876 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 26 Apr 2019 20:16:08 +0000 Subject: [PATCH 53/68] small tweaks to paragraph about consequences of the single-base-url design; added SSO to reated standards section --- Makefile | 2 +- TAP.tex | 19 +++++++++++-------- sample-capability.xml | 2 +- 3 files changed, 13 insertions(+), 10 deletions(-) diff --git a/Makefile b/Makefile index bdc1317..49a9f15 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2019-03-15 +DOCDATE = 2019-04-20 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = PR diff --git a/TAP.tex b/TAP.tex index 5e397da..e11b9b4 100644 --- a/TAP.tex +++ b/TAP.tex @@ -162,6 +162,10 @@ \subsection{Role within the VO Architecture} versions are missing features that are required and may be unusable in practice. For example, the overflow reporting and xtype attribute were introduced in VOTable 1.2 so that is the minimum viable version that must be used. + +\item[SSO \citep{std:SSOAUTH2}] TAP services that support authenticated +access declare this in their capabilities using recommendations and security method +identifiers from the SSO standard. \end{description} @@ -429,14 +433,11 @@ \subsection{VOSI-capabilities} As a consequence of using a single base URL with fixed name child resources, all supported authentication methods must be able to co-exist on the same URL. At this time, both anonymous and other authentication -methods can be made to work in this way except for HTTP Basic and Digest authentication. In general, -challenge-reponse methods will likely not be able to co-exist with methods that simply deliver credentials -(e.g. cookies or tokens via HTTP headers) with the request. While client certificate usage is technically also -a challenge-response method, this occurs during SSL socket setup and does not interfere with the HTTP request itself and can co-exist with anonymous https access (by making client certificate optional in the server -configuration). As a result of having a single base URL, one can provide an anonymous-only TAP service with http or https; once support for \verb|ivo://ivoa.net/sso#tls-with-certificate| is added, however, the entire service +methods described in SSO can be made to work in this way, with the exception of HTTP Basic and Digest authentication. With a single base URL, one can provide an anonymous-only TAP service with http or https; once support for \verb|ivo://ivoa.net/sso#tls-with-certificate| is added, however, the entire service must use https only. While one can provide a service with \verb|securityMethod="ivo://ivoa.net/sso#BasicAA"|, -this authentication method uses the HTTP protocol and thus cannot co-exist with other methods (including -anonymous); such a service would only be able to describe that single method. +this authentication method uses the HTTP protocol to implement it's challenge-response and thus cannot co-exist with other methods (including anonymous); such a service would only be able to describe that single method. However, the SSO standard recommends that usernme-password authentication (including BasicAA) be used to login +and obtain another type of credential (e.g. a cookie) and that services should not directly use username-password +for authentication, so this limitation in TAP services should not be a problem. In the example above, the VOSI-availability and VOSI-capabilities interfaces are anonymous (no securityMethod). The VOSI-tables interface is typically also anonymous-only, but in the example we show that it may also support @@ -1462,12 +1463,14 @@ \subsection{VOSI/UWS related changes} \section{Detailed Changes from Previous Versions} -\subsection{PR-TAP-20190315} +\subsection{PR-TAP-20190420} Modified the resources section to only allow the fixed name resources on a single base URL. Adapted the VOSI-capabilities example and explanation to demonstrate the single base URL design and specify the meaning of having zero or more securityMethod(s). Removed all use to the previously proposed UWSRegExt. +Added explicit mention of SSO-2.0 in related standards. + \subsection{PR-TAP-1.1-20180830} Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. diff --git a/sample-capability.xml b/sample-capability.xml index a52ebe1..1a0c1a6 100644 --- a/sample-capability.xml +++ b/sample-capability.xml @@ -35,7 +35,7 @@ - https://example.net/srv/cert-tables + https://example.net/srv/tables From 9406acbe0e65e39e33f00168e26661cdcac92881 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 26 Apr 2019 20:22:42 +0000 Subject: [PATCH 54/68] fix typo and sentence structure from previous commit --- TAP.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/TAP.tex b/TAP.tex index e11b9b4..e0783b3 100644 --- a/TAP.tex +++ b/TAP.tex @@ -435,9 +435,9 @@ \subsection{VOSI-capabilities} methods must be able to co-exist on the same URL. At this time, both anonymous and other authentication methods described in SSO can be made to work in this way, with the exception of HTTP Basic and Digest authentication. With a single base URL, one can provide an anonymous-only TAP service with http or https; once support for \verb|ivo://ivoa.net/sso#tls-with-certificate| is added, however, the entire service must use https only. While one can provide a service with \verb|securityMethod="ivo://ivoa.net/sso#BasicAA"|, -this authentication method uses the HTTP protocol to implement it's challenge-response and thus cannot co-exist with other methods (including anonymous); such a service would only be able to describe that single method. However, the SSO standard recommends that usernme-password authentication (including BasicAA) be used to login +this authentication method uses the HTTP protocol to implement it's challenge-response and thus cannot co-exist with other methods (including anonymous); such a service would only be able to describe that single method. However, the SSO standard recommends that username-password authentication (including BasicAA) be used to login and obtain another type of credential (e.g. a cookie) and that services should not directly use username-password -for authentication, so this limitation in TAP services should not be a problem. +for authentication; the single base URL design here is consistent with the recommendations of SSO. In the example above, the VOSI-availability and VOSI-capabilities interfaces are anonymous (no securityMethod). The VOSI-tables interface is typically also anonymous-only, but in the example we show that it may also support From 8da19f147c1b58811c4254036d3ebc734bd60b60 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Tue, 30 Apr 2019 09:17:14 +0000 Subject: [PATCH 55/68] Experimental attempt to prevent conflicts of TAP 1.1 with caproles. This tries to make clear that only the TAP capability is actually required by this spec and that the VOSI caps, when no longer required by other standards, can be left out. --- TAP.tex | 19 ++++++++++++++++--- sample-capability.xml | 3 +++ 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/TAP.tex b/TAP.tex index e0783b3..bbfed80 100644 --- a/TAP.tex +++ b/TAP.tex @@ -424,9 +424,25 @@ \subsection{VOSI-capabilities} In addition to the accessURL element, the interface element may also contain zero or more securityMethod elements that specify the supported authention methods. Zero such elements and a securityMethod with no standardID attribute are both interpreted as meaning anonymous; the latter should only be used if other securityMethod(s) are also specified and zero such elements is preferrable in an anonymous-only service. +Here is an example for a document as it might be returned from a VOSI +capabilities endpoint of a TAP service: + \lstinputlisting[language=XML,basicstyle=\footnotesize] {sample-capability.xml} +This specification only requires that exactly one capability with a +standardID of \nolinkurl{ivo://ivoa.net/std/TAP} is present. +In addition to this basic service description, production services +should use the TAPRegExt \citep{std:TAPREGEXT} extension to provide +additional metadata within the TAP capability. + +The VOSI capability declarations shown above are not required by this +specification. Clients should obtain the corresponding endpoint URLs through +appending the fixed endpoint names to the access URL(s) given in the +interface(s) defined in the TAP capability. This specifiation leaves the +association of availability endpoint(s) -- which no longer have a fixed +name -- to access and mirror URLs open. + The example above descibes a TAP service that can be accessed anonymously or by autheticating with a cookie (\verb|ivo://ivoa.net/sso#cookie|) or an X509 client certificate (\verb|ivo://ivoa.net/sso#tls-with-certificate|). The same URL (e.g. \verb|https://example.net/tap/sync| for a synchronous query) would be used for both anonymous and authenticated access. @@ -443,9 +459,6 @@ \subsection{VOSI-capabilities} The VOSI-tables interface is typically also anonymous-only, but in the example we show that it may also support anonymous and/or authenticated access. In general, clients that support authentication should be prepared to discover and use anonymous-only endpoints for some requests. -In addition to the basic service descrption in the example above, services should use the TAPRegExt -\citep{std:TAPREGEXT} extension to provide additional metadata within the TAP capability. - \subsection{VOSI-tables} \label{sec:vosi-tables} diff --git a/sample-capability.xml b/sample-capability.xml index 1a0c1a6..1f32794 100644 --- a/sample-capability.xml +++ b/sample-capability.xml @@ -20,6 +20,7 @@ + https://example.net/srv/capabilities @@ -27,6 +28,7 @@ + https://example.net/srv/availability @@ -34,6 +36,7 @@ + https://example.net/srv/tables From 612cb90d9598c7c59432d57f1afa7a5d7da41fc2 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 26 Jun 2019 19:25:24 +0000 Subject: [PATCH 56/68] updated VOSI-capabilities section to balance current and future requirements --- Makefile | 2 +- TAP.tex | 29 +++++++++++++++++++---------- 2 files changed, 20 insertions(+), 11 deletions(-) diff --git a/Makefile b/Makefile index 49a9f15..e111f43 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2019-04-20 +DOCDATE = 2019-06-26 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = PR diff --git a/TAP.tex b/TAP.tex index bbfed80..dfc54a1 100644 --- a/TAP.tex +++ b/TAP.tex @@ -318,7 +318,7 @@ \subsection{TAP-sync} of synchronous query execution. The {sync} resources must conform to the general rules for DALI-sync resources. The exact form of the query, and hence the representation of the resource, is defined by the query parameters as listed in -section~\ref{sec:parameters}. Representations of results of queries is defined in +section~\ref{sec:parameters}. The representation of results of queries is defined in section~\ref{sec:RESPONSEFORMAT} and section~\ref{sec:votable}. For query languages that produce a single result (e.g. ADQL) executed using the @@ -430,18 +430,27 @@ \subsection{VOSI-capabilities} \lstinputlisting[language=XML,basicstyle=\footnotesize] {sample-capability.xml} -This specification only requires that exactly one capability with a +This specification requires that exactly one capability with a standardID of \nolinkurl{ivo://ivoa.net/std/TAP} is present. In addition to this basic service description, production services should use the TAPRegExt \citep{std:TAPREGEXT} extension to provide -additional metadata within the TAP capability. - -The VOSI capability declarations shown above are not required by this -specification. Clients should obtain the corresponding endpoint URLs through -appending the fixed endpoint names to the access URL(s) given in the -interface(s) defined in the TAP capability. This specifiation leaves the -association of availability endpoint(s) -- which no longer have a fixed -name -- to access and mirror URLs open. +additional metadata within the TAP capability. Clients should create +the endpoint URLs by appending the fixed endpoint names to the access URL +given in the interface defined in the TAP capability. The TAP capabilty normally +has a single interface; multiple interfaces are permitted in order to support multiple +versions (different version attribute on the interface element and different +accessURL). + +This specification does not require that the capabilities document includes a capability +description for the VOSI features themselves. However, these are needed in the document +and in registry records until such time that another standard (DALI or VOResource) +provides an alternative mechanism to convey required information to clients +(standardID or equivalent, version, accessURL(s), supported securityMethod(s), etc.). +In the example above, the VOSI-tables capability conveys the version (1.1) and that multiple +securityMethod(s) are supported. The version tells clients that a returned tableset may not +contain column metadata and that the detail parameter is suppoorted. The securityMethod(s) +tell clients that authenticating may effect the output such as exposing metadata for +protected tables. The example above descibes a TAP service that can be accessed anonymously or by autheticating with a cookie (\verb|ivo://ivoa.net/sso#cookie|) or an X509 client certificate (\verb|ivo://ivoa.net/sso#tls-with-certificate|). From 83af47629f2507b000408cfe78c173ad86a7d6cf Mon Sep 17 00:00:00 2001 From: Marco Molinaro Date: Fri, 28 Jun 2019 09:21:31 +0000 Subject: [PATCH 57/68] few typo fixing --- TAP.tex | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/TAP.tex b/TAP.tex index dfc54a1..4b0634e 100644 --- a/TAP.tex +++ b/TAP.tex @@ -300,7 +300,7 @@ \section{Resources} As required by DALI \citep{2017ivoa.spec.0517D}, all resources (including the optional VOSI-tables resource) except the VOSI-availability must be siblings of the VOSI-capabilities resource. -The fixed name resources above (async, sync, tables, and examples) are used for both anonynous and +The fixed name resources above (async, sync, tables, and examples) are used for both anonymous and authenticated access to the service; the consequences of having a single base URL are detailed below in section~\ref{sec:vosi-capabilities}. The VOSI-availabilty and VOSI-capabilities resources must allow anonymous access as they can be used by clients to determine if the service is available and which resources to use with available security (authentication) methods. @@ -422,7 +422,7 @@ \subsection{VOSI-capabilities} The interface element within the TAP capability specifies the base URL of the service under which the fixed-name resources specified above (section~\ref{sec:resources}) are located. In addition to the accessURL element, the interface element may also contain zero or more securityMethod -elements that specify the supported authention methods. Zero such elements and a securityMethod with no standardID attribute are both interpreted as meaning anonymous; the latter should only be used if other securityMethod(s) are also specified and zero such elements is preferrable in an anonymous-only service. +elements that specify the supported authentication methods. Zero such elements and a securityMethod with no standardID attribute are both interpreted as meaning anonymous; the latter should only be used if other securityMethod(s) are also specified and zero such elements is preferable in an anonymous-only service. Here is an example for a document as it might be returned from a VOSI capabilities endpoint of a TAP service: @@ -436,7 +436,7 @@ \subsection{VOSI-capabilities} should use the TAPRegExt \citep{std:TAPREGEXT} extension to provide additional metadata within the TAP capability. Clients should create the endpoint URLs by appending the fixed endpoint names to the access URL -given in the interface defined in the TAP capability. The TAP capabilty normally +given in the interface defined in the TAP capability. The TAP capability normally has a single interface; multiple interfaces are permitted in order to support multiple versions (different version attribute on the interface element and different accessURL). @@ -448,11 +448,11 @@ \subsection{VOSI-capabilities} (standardID or equivalent, version, accessURL(s), supported securityMethod(s), etc.). In the example above, the VOSI-tables capability conveys the version (1.1) and that multiple securityMethod(s) are supported. The version tells clients that a returned tableset may not -contain column metadata and that the detail parameter is suppoorted. The securityMethod(s) +contain column metadata and that the detail parameter is supported. The securityMethod(s) tell clients that authenticating may effect the output such as exposing metadata for protected tables. -The example above descibes a TAP service that can be accessed anonymously or by autheticating with a cookie +The example above describes a TAP service that can be accessed anonymously or by authenticating with a cookie (\verb|ivo://ivoa.net/sso#cookie|) or an X509 client certificate (\verb|ivo://ivoa.net/sso#tls-with-certificate|). The same URL (e.g. \verb|https://example.net/tap/sync| for a synchronous query) would be used for both anonymous and authenticated access. From c3b58e0b70810c2729c9d9ce18511925890fdfe5 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 13 Aug 2019 23:25:58 +0000 Subject: [PATCH 58/68] TCG comments from BM, TD, and MT addressed --- TAP.tex | 61 +++++++++++++++++++++++---------------------------------- 1 file changed, 25 insertions(+), 36 deletions(-) diff --git a/TAP.tex b/TAP.tex index 4b0634e..d224e19 100644 --- a/TAP.tex +++ b/TAP.tex @@ -131,7 +131,7 @@ \subsection{Role within the VO Architecture} \label{fig:archdiag} \end{figure} -Fig.~section~\ref{fig:archdiag} shows the role this document plays within the +Fig.~\ref{fig:archdiag} shows the role this document plays within the IVOA architecture \citep{note:VOARCH}. TAP depends on the following other IVOA standards: @@ -296,7 +296,7 @@ \section{Resources} \end{inlinetable} \medskip -A TAP service provides a single base URL with child resources for the various features in tbe table above. +A TAP service provides a single base URL with child resources for the various features in the table above. As required by DALI \citep{2017ivoa.spec.0517D}, all resources (including the optional VOSI-tables resource) except the VOSI-availability must be siblings of the VOSI-capabilities resource. @@ -315,7 +315,7 @@ \subsection{TAP-sync} \label{sec:tap-sync} A TAP service must provide one or more web resources that represent the results -of synchronous query execution. The {sync} resources must conform to the general rules for +of synchronous query execution. The /sync resources must conform to the general rules for DALI-sync resources. The exact form of the query, and hence the representation of the resource, is defined by the query parameters as listed in section~\ref{sec:parameters}. The representation of results of queries is defined in @@ -417,7 +417,7 @@ \subsection{VOSI-capabilities} For TAP-1.1 we use the same standardID value. The version attribute of the interfaces must use the minor version (e.g. \verb|version="1.1"|) of the TAP standard; clients -should treat a missing version attribute is equivalent to \verb|version="1.0"|. +should treat a missing version attribute as equivalent to \verb|version="1.0"|. The interface element within the TAP capability specifies the base URL of the service under which the fixed-name resources specified above (section~\ref{sec:resources}) are located. @@ -449,7 +449,7 @@ \subsection{VOSI-capabilities} In the example above, the VOSI-tables capability conveys the version (1.1) and that multiple securityMethod(s) are supported. The version tells clients that a returned tableset may not contain column metadata and that the detail parameter is supported. The securityMethod(s) -tell clients that authenticating may effect the output such as exposing metadata for +tell clients that authenticating may affect the output such as exposing metadata for protected tables. The example above describes a TAP service that can be accessed anonymously or by authenticating with a cookie @@ -457,12 +457,7 @@ \subsection{VOSI-capabilities} The same URL (e.g. \verb|https://example.net/tap/sync| for a synchronous query) would be used for both anonymous and authenticated access. As a consequence of using a single base URL with fixed name child resources, all supported authentication -methods must be able to co-exist on the same URL. At this time, both anonymous and other authentication -methods described in SSO can be made to work in this way, with the exception of HTTP Basic and Digest authentication. With a single base URL, one can provide an anonymous-only TAP service with http or https; once support for \verb|ivo://ivoa.net/sso#tls-with-certificate| is added, however, the entire service -must use https only. While one can provide a service with \verb|securityMethod="ivo://ivoa.net/sso#BasicAA"|, -this authentication method uses the HTTP protocol to implement it's challenge-response and thus cannot co-exist with other methods (including anonymous); such a service would only be able to describe that single method. However, the SSO standard recommends that username-password authentication (including BasicAA) be used to login -and obtain another type of credential (e.g. a cookie) and that services should not directly use username-password -for authentication; the single base URL design here is consistent with the recommendations of SSO. +methods must be able to co-exist on the same URL. In the example above, the VOSI-availability and VOSI-capabilities interfaces are anonymous (no securityMethod). The VOSI-tables interface is typically also anonymous-only, but in the example we show that it may also support @@ -538,7 +533,7 @@ \subsection{Parameters} requests are handled). Thus, for asynchronous TAP queries, the parameter requirements must be satisfied (and errors returned if not) only when the query is run (in the sense of UWS job execution). Specifically, asynchronous -queries may be created with with no parameters and multiple, subsequent HTTP +queries may be created with no parameters and multiple, subsequent HTTP POST actions may specify the parameters in any order. Not all combinations of the parameters are meaningful. If a @@ -728,7 +723,7 @@ \section{Use of VOTable} deals with how VOTable is used. However, rules about serialising column values also apply to other formats (e.g. CSV and TSV). -The use of VOTable in TAP services is described in DALI, with additional clarifications +The use of VOTable is described in DALI, with additional clarifications or advice below. \subsection{INFO elements} @@ -743,9 +738,8 @@ \subsection{INFO elements} \begin{verbatim} ... - - select * from stuff.items - + + ... \end{verbatim} @@ -842,20 +836,18 @@ \subsection{Overflows} \subsection{Mapping Table Datatypes} \label{sec:vot-rdbms} -This section describes the bi-directional mapping between VOTable on the -one and the RDBMS (including its -geometric datatypes) on the other side. It extends the basic rules for serialising such values in -VOTable described in DALI. These rules apply to input tables -supplied via an UPLOAD parameter (see section~\ref{sec:UPLOAD}) and to result tables after successful -query execution. - -The mapping to and from VOTable makes use of the datatype, arraysize, and xtype -attributes. Mapping for primitive types (numbers and strings) is -straightforward; services should ensure that input values behave as -expected in query processing and output values should have correct and complete -metadata. Mapping for specially structured values use xtype(s) specified -in DALI. The behaviour of such structured values in queries depends -on the query language (section~\ref{sec:LANG}) being used. +The mapping between VOTable and database tables uses the datatype, arraysize, and xtype values from +the VOTable FIELD elements and the TAP\kern-3pt\_SCHEMA.columns table. Mapping for primitive types +(numbers and strings) is straightforward; services should ensure that input values behave as +expected in query processing and output values should have correct and complete metadata. Mapping for specially +structured values use xtype(s) as specified in DALI. The behaviour and usability of such structured values in +queries depends on the query language (section~\ref{sec:LANG}) being used and support for optional features +of the language. + +Datatype mapping rules apply to input tables supplied via an UPLOAD parameter (see section~\ref{sec:UPLOAD}) +and to result tables after successful query execution. TAP services should at least be able to round-trip all +values from an uploaded VOTable to the database and back when columns in the uploaded table are selected (e.g. +SELECT * from TAP_UPLOAD.mytable). \section{Metadata: TAP\kern-3pt\_SCHEMA} \label{sec:tap-schema} @@ -1013,7 +1005,7 @@ \subsection{Columns} For columns with a database type equivalent to BLOB or CLOB, most database systems support reference to these columns in the select clause but not in every other part of the query where character columns may be used. In addition, services may want to define generated columns where the output is dynamically generated but the content is not stored in the -databasase in a form that supports querying. For example, if service implementors want to make +database in a form that supports querying. For example, if service implementors want to make URL(s) available as column values in the results, but do not actually store the URL(s) in the database, the column with URL(s) could be referenced in the SELECT clause of a query, but could not sensibly be used in the WHERE clause. In general, if a query references a column in an @@ -1110,15 +1102,12 @@ \section{Examples} TAP client and service when using UWS to run an asynchronous query. \subsection{Example: Asynchronous Query} -Consider a TAP service at http://example.com/tap. TAP mandates that the -asynchronous requests be directed to http://example.com/tap/async (e.g. for -anonymous queries). This URL points to the list of ``jobs'', i.e., the list of +Consider a TAP service at http://example.com/tap. Asynchronous requests are directed to the http://example.com/tap/async endpoint. This URL points to the list of ``jobs'', i.e., the list of queries currently executing or recently executed. \subsubsection{Creating and Executing a Simple Query} -Asynchronous queries are created in the same way as synchronous, using -one of the {async} endpoints, for example: +Asynchronous queries are created with the same parameters as synchronous queries, using the /async endpoint, for example: \begin{verbatim} HTTP POST http://example.com/tap/async From d2e247ca78cae68edccff61973cc19599c2279bb Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 14 Aug 2019 17:20:50 +0000 Subject: [PATCH 59/68] additional typo fixes --- TAP.tex | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/TAP.tex b/TAP.tex index d224e19..faf9ebd 100644 --- a/TAP.tex +++ b/TAP.tex @@ -230,7 +230,7 @@ \subsubsection{Query Standard Tables} \subsubsection{Query Standard Data Models} A TAP service should enable users to query (parts of) externally defined data models that are (partially or fully) implemented by the service. Services must -be able to declare their support for data models as well as the way that model +be able to declare their support for data models as well as the way those model elements are mapped to tables and columns. \subsection{Query Languages} @@ -302,7 +302,7 @@ \section{Resources} The fixed name resources above (async, sync, tables, and examples) are used for both anonymous and authenticated access to the service; the consequences of having a single base URL are detailed below in -section~\ref{sec:vosi-capabilities}. The VOSI-availabilty and VOSI-capabilities resources must allow anonymous access as they can be used by clients to determine if the service is available and which resources to use with +section~\ref{sec:vosi-capabilities}. The VOSI-availability and VOSI-capabilities resources must allow anonymous access as they can be used by clients to determine if the service is available and which resources to use with available security (authentication) methods. The web resource at the root of the tree represents the service as a whole. @@ -386,7 +386,7 @@ \subsection{TAP-async} For query languages that produce a single result executed using the /async endpoint, the result of a successful query can be found within the result list specified by UWS; the result must be named result and thus -clients are able to access it directly, e.g.: +clients can access it directly, e.g.: \begin{verbatim} http://example.com/tap/async/42/results/result \end{verbatim} @@ -475,7 +475,7 @@ \subsection{VOSI-tables} map directly; TAPType may be used when VOTableType does not provide a suitable alternative. -Services which do not implement the /tables resource must respond with an HTTP +Services that do not implement the /tables resource must respond with an HTTP response code of 404 when this resource is accessed. \subsection{DALI-examples} @@ -580,7 +580,7 @@ \subsubsection{QUERY} A service must support the QUERY parameter because ADQL is a required language. If timestamp comparisons are supported within ADQL queries, they must use the syntax -defined in DALI. Timestamp values are usable if there are columns with timestamp values, +defined in DALI. Timestamp values may be used if there are columns with timestamp values, including in uploaded tables if table upload is supported. If the service supports the use of spatial coordinates in ADQL queries, the output of @@ -596,7 +596,7 @@ \subsubsection{QUERY} Note: Although it is allowed by the ADQL-2.0 syntax, clients should be careful when mixing constants and column references for coordinate system and coordinate values. For example, POINT('ICRS', t.ra, t.dec) does not cause t.ra and t.dec to -be transformed to ICRS; it simply tells the service to treat the values as +be transformed to ICRS; it tells the service to treat the values as being expressed in that coordinate system. Clients should avoid using the coordinate system argument to geometric functions (supply the empty string, or use an alternate function without the coordinate system argument if available). @@ -618,7 +618,7 @@ \subsubsection{FORMAT and RESPONSEFORMAT} \subsubsection{MAXREC} \label{sec:MAXREC} -The MAXREC parameter and its effect on the query result is fully described in +The MAXREC parameter and its effects on the query result are fully described in DALI. If the result set is truncated in this fashion, it must include an overflow indicator as specified in section~\ref{sec:query-overflow}. @@ -732,8 +732,8 @@ \subsection{INFO elements} The RESOURCE element must contain INFO element(s) as described in DALI. Additional INFO elements may be provided, e.g., to echo the input parameters -back to the client in the query response (a useful feature for debugging or to -self-document the query response), but clients should not depend on these. +back to the client in the query response (a useful feature for debugging or +self-documenting the query response), but clients should not depend on these. \begin{verbatim} @@ -748,7 +748,7 @@ \subsection{Successful Queries} \label{sec:query-ok} The result of a query depends on the query language used and may be one or more -tables in one or more resources. Unsupportable combinations of query result and +tables in one or more resources. Unsupportable combinations of query results and RESPONSEFORMAT (e.g. queries that produce multiple tables and an inherently single-table format like CSV) will cause the request to fail. Currently, an ADQL query result must be a single table (in a single file). @@ -847,14 +847,14 @@ \subsection{Mapping Table Datatypes} Datatype mapping rules apply to input tables supplied via an UPLOAD parameter (see section~\ref{sec:UPLOAD}) and to result tables after successful query execution. TAP services should at least be able to round-trip all values from an uploaded VOTable to the database and back when columns in the uploaded table are selected (e.g. -SELECT * from TAP_UPLOAD.mytable). +\verb|SELECT * from TAP_UPLOAD.mytable|). \section{Metadata: TAP\kern-3pt\_SCHEMA} \label{sec:tap-schema} There are several approaches to getting metadata for a given TAP service. All TAP services must support a set of tables in a schema named -\tapschema\ that describe the tables and columns included in the +\tapschema\ that describes the tables and columns included in the service. In addition to the \tapschema, there are two other ways to get metadata from a TAP service. First, the VOSI tables resource provides metadata on all tables and columns; this resource is described in @@ -877,7 +877,7 @@ \section{Metadata: TAP\kern-3pt\_SCHEMA} them accessible by all supported query mechanisms. Column datatypes in the \tapschema{} are specified using the same concepts used in -VOTable: datatype, arraysize, and xtype. For backwards compatibility, implementors +VOTable: datatype, arraysize, and xtype. For backward compatibility, implementors must also include the \verb|"size"| column and populate it where possible. In the details below, \tapschema{} column types are either string or integer; implementers may choose an appropriate data type that behaves the same way in queries and output (e.g. varchar(16) or @@ -999,7 +999,7 @@ \subsection{Columns} it collides with an ADQL reserved word. Since delimited identifiers are case-sensitive, for the \verb|"size"| column both clients and servers MUST always (in particular, in the creation of the -\tapschema) use lower case exclusively. In the next major version +\tapschema), use lower case exclusively. In the next major version of TAP, the \verb|"size"| column will be removed. For columns with a database type equivalent to BLOB or CLOB, most database systems support @@ -1173,7 +1173,7 @@ \subsubsection{Modify a Query Job Before Execution} m on t.target = m.target \end{verbatim} -Here we have specified with the UPLOAD parameter that the service create a +Here we have specified with the UPLOAD parameter that the service creates a temporary table named mytable with content from the VOTable at the specified URL. The QUERY parameter can then reference the uploaded table with the specified name (but in the \tapupload{} schema). @@ -1217,7 +1217,7 @@ \subsubsection{Modify a Query Job Before Execution} assuming it is started immediately. In practice, it is very hard to estimate the time a query will take; for TAP services it is recommended that this is set to the current time plus the maximum amount of time the query will be allowed to -run. The executionduration resource specifies the amount of time (in seconds) +run. The \verb|executionduration| resource specifies the amount of time (in seconds) the job (query) will be allowed to run before being aborted by the service. The execution duration is set by the service and can be read from the job or directly from the executionduration resource: @@ -1254,7 +1254,7 @@ \subsubsection{Running a Query} The phase URL shows the progress of the job. When the job is created by the service it will normally be set to PENDING, but might be set to ERROR if the service has rejected the job. If the phase is ERROR, then the error URL should -lead to a an error document explaining the problem. If the phase is PENDING, +lead to an error document explaining the problem. If the phase is PENDING, then the client needs to commit the job for execution. The client runs the job by posting to the phase URL: From 39c6a88ac80989c467e44156208c73811db123a1 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 14 Aug 2019 17:37:01 +0000 Subject: [PATCH 60/68] changed OBSCORE ref to 1.1 in ivoabib --- TAP.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TAP.tex b/TAP.tex index faf9ebd..e4c44aa 100644 --- a/TAP.tex +++ b/TAP.tex @@ -178,7 +178,7 @@ \subsection{Role within the VO Architecture} references DALI 1.1's serialisation rules for geometries and timestamps and recommends implementing the examples endpoint defined by DALI. -\item[Obscore \citep{2011ivoa.spec.1028T}] The Obscore data model +\item[Obscore \citep{std:OBSCORE11}] The Obscore data model facilitates the publication of metadata of observational data products. TAP is used to access compliant metadata collections. From f74aa1b8ff85d44c88d00322db31e897cbcdab76 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Mon, 19 Aug 2019 17:02:17 +0000 Subject: [PATCH 61/68] commented out the 'detailed changes' section --- TAP.tex | 274 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 137 insertions(+), 137 deletions(-) diff --git a/TAP.tex b/TAP.tex index e4c44aa..f965929 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1472,143 +1472,143 @@ \subsection{VOSI/UWS related changes} tables-1.1 capability (\ref{sec:resources}). \end{itemize} -\section{Detailed Changes from Previous Versions} - -\subsection{PR-TAP-20190420} - -Modified the resources section to only allow the fixed name resources on a single base URL. Adapted the -VOSI-capabilities example and explanation to demonstrate the single base URL design and specify the meaning -of having zero or more securityMethod(s). Removed all use to the previously proposed UWSRegExt. - -Added explicit mention of SSO-2.0 in related standards. - -\subsection{PR-TAP-1.1-20180830} - -Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. - -\subsection{PR-TAP-1.1-20180416} - -Added updated IVOA architecture diagram showing role of TAP. - -Removed language that somehow defined or restricted usage of ADQL constructs in -favour of just referring to the AQDL spec. Clarified use of serialisation -rules for extended types defined in DALI. - -Removed explicit datatype/arraysize/xtype from \tapschema{} description -in favour of string and integer. Specified which integers are actually -booleans (0 or 1). Added list of foreign keys for \tapschema{} -relational model. Clarified use of delimited identifiers for column names in -\tapschema. Added schema\_index column. Clarified when the \verb|"size"| column -in \tapschema\ can contain a value. Clarified that both arraysize and \verb|"size"| -must be null for scalar numeric columns. - -Fixed use of double-quotes which misbehaved inside tables. - -Fixed BasicAA security method in capabilities example. Included use of prototype -UWSRegExt interface tags in capabilities example and removed use of separate -standardID values for async and sync. - -Fixed numerous typos and gramnmatical errors. - -Removed obsolete REQUEST=doQuery from examples. - -Added explicit reference to VOSI-tables. Updated capabilities example to describe a -tables-1.1 capability. - -Clarified dependency on minor versions of related standards with some recommendations on -using newer versions. - -\subsection{PR-TAP-1.1-20170830} - -Added an example for \verb|examples|. - -Clarified that the QUERY param is intended for use with other values of LANG and is not -reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. - -Removed remaining uses of PQL; replaced one example with something more clearly non-standard. - -Removed restriction from previous WD that the ``size'' column must be null for variable length arrays. In fact, ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column). - -Changed language about mandatory ADQL geometry function support back to optional (should in -the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. - -Removed some VOTable content and reference DALI. Explicitly relaxed datatype and arraysize used in \tapschema{} tables. Fixed various cross-references and typos. - -Added example use of UWS-1.1 blocking requests. - -\subsection{WD-TAP-1.1-20170707} - -Changed arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. - -Clarified required and optional ADQL geometric functions. - -Format tables so column headers are bold. - -Added paragraph specifying allowed values for \tapschema.tables.table\_type. - -Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we -now use the VOTabletype system. - -Fixed URL to schema in VOSI-capabilities example. - -\subsection{WD-TAP-1.1-20161011} - -Removed details of mapping database and VOTable data types and refer to DALI -instead. - -Strongly recommend that VOSI resources allow anonymous access. - -Relax restrictions on column names in uploaded tables; clarify that services -must support delimited identifiers. Advise that services should assign unique -column names in cases where they generate the name. - -\subsection{WD-TAP-1.1-20160428} - -Completed the mapping table from VOTable to RDBMS datatypes using DALI-1.1 xtype values. - -Added details and VOSI-capabilities example for providing multiple resources with different -authentication requirements. Clarified that VOSI-availability is no longer restricted to a -specific name or location. - -\subsection{WD-TAP-1.1-20150930} - -Clarified that MAXREC always overrides limitations in the query (e.g. -TOP in an ADQL query). - -Clarified that services are not required to support queries that reference tables -in different schema. This is primarily to allow the \tapschema{} to be implemented -in a different server from the content. - -Completed the references section. - -\subsection{Changes from TAP-1.0} - -Added table\_index and column\_index to \tapschema. - -Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow -indicator. - -Added advice that the size column \tapschema.columns must always be used -as a delimited identifier because it is a reserved word in many RDBMS -servers. Added arraysize column to \tapschema.columns to replace size and -deprecated size (which will be removed in the next major version). - -Removed REQUEST and VERSION parameters from interface. - -Restructured the document and removed text that duplicates material from DALI. -Rewrite the overly long introduction with some basic use cases to help define -the scope and tell readers what TAP is supposed to accomplish. - -Made clarifications: restricted allowed table names for UPLOAD, clarified that -multiple UPLOAD parameters accumulate, deprecated the size column in -\tapschema.columns and added advice to quote it as a delimited -identifier, made presence of a TABLE element on VOTable output only required for -successful queries, added optional DALI-examples endpoint (text TBD). - -Defined standardID values for the async and sync resource types and explicitly -allow for multiple of each resource (typically to support authentication). The -fixed paths /async and /sync are still required and are to provide anonymous -query access, which should be compatible with existing services. +% \section{Detailed Changes from Previous Versions} +% +% \subsection{PR-TAP-20190420} +% +% Modified the resources section to only allow the fixed name resources on a single base URL. Adapted the +% VOSI-capabilities example and explanation to demonstrate the single base URL design and specify the meaning +% of having zero or more securityMethod(s). Removed all use to the previously proposed UWSRegExt. +% +% Added explicit mention of SSO-2.0 in related standards. +% +% \subsection{PR-TAP-1.1-20180830} +% +% Added reference to UWSRegExt Note and clarified the use of this prototype in VOSI-capabilities. +% +% \subsection{PR-TAP-1.1-20180416} +% +% Added updated IVOA architecture diagram showing role of TAP. +% +% Removed language that somehow defined or restricted usage of ADQL constructs in +% favour of just referring to the AQDL spec. Clarified use of serialisation +% rules for extended types defined in DALI. +% +% Removed explicit datatype/arraysize/xtype from \tapschema{} description +% in favour of string and integer. Specified which integers are actually +% booleans (0 or 1). Added list of foreign keys for \tapschema{} +% relational model. Clarified use of delimited identifiers for column names in +% \tapschema. Added schema\_index column. Clarified when the \verb|"size"| column +% in \tapschema\ can contain a value. Clarified that both arraysize and \verb|"size"| +% must be null for scalar numeric columns. +% +% Fixed use of double-quotes which misbehaved inside tables. +% +% Fixed BasicAA security method in capabilities example. Included use of prototype +% UWSRegExt interface tags in capabilities example and removed use of separate +% standardID values for async and sync. +% +% Fixed numerous typos and gramnmatical errors. +% +% Removed obsolete REQUEST=doQuery from examples. +% +% Added explicit reference to VOSI-tables. Updated capabilities example to describe a +% tables-1.1 capability. +% +% Clarified dependency on minor versions of related standards with some recommendations on +% using newer versions. +% +% \subsection{PR-TAP-1.1-20170830} +% +% Added an example for \verb|examples|. +% +% Clarified that the QUERY param is intended for use with other values of LANG and is not +% reserved for ADQL only. Removed text concerning the case sensitivity of QUERY value. +% +% Removed remaining uses of PQL; replaced one example with something more clearly non-standard. +% +% Removed restriction from previous WD that the ``size'' column must be null for variable length arrays. In fact, ``size'' can be used for 1-dimension arrays but just does not carry any info about them being variable-length (which is only in the new arraysize column). +% +% Changed language about mandatory ADQL geometry function support back to optional (should in +% the case where the tables contain spatial coordinates) so TAP now recommends a set of functions to support and notes others are simply optional (or not supported in the case of REGION). Removed the comment about use of point args to INTERECTS (belongs in ADQL). Clarified that DALI timestamp format support is required only in services where it can be used in queries. +% +% Removed some VOTable content and reference DALI. Explicitly relaxed datatype and arraysize used in \tapschema{} tables. Fixed various cross-references and typos. +% +% Added example use of UWS-1.1 blocking requests. +% +% \subsection{WD-TAP-1.1-20170707} +% +% Changed arraysize in \tapschema{} to allow the complete VOTable arraysize syntax and specified that the effective datatype in TAP is specified as in VOTable using datatype,arraysize, and xtype. Recommend use of VOTableType in VOSI-tables output. +% +% Clarified required and optional ADQL geometric functions. +% +% Format tables so column headers are bold. +% +% Added paragraph specifying allowed values for \tapschema.tables.table\_type. +% +% Changed the principal, indexed, and std columns in \tapschema.columns to boolean since we +% now use the VOTabletype system. +% +% Fixed URL to schema in VOSI-capabilities example. +% +% \subsection{WD-TAP-1.1-20161011} +% +% Removed details of mapping database and VOTable data types and refer to DALI +% instead. +% +% Strongly recommend that VOSI resources allow anonymous access. +% +% Relax restrictions on column names in uploaded tables; clarify that services +% must support delimited identifiers. Advise that services should assign unique +% column names in cases where they generate the name. +% +% \subsection{WD-TAP-1.1-20160428} +% +% Completed the mapping table from VOTable to RDBMS datatypes using DALI-1.1 xtype values. +% +% Added details and VOSI-capabilities example for providing multiple resources with different +% authentication requirements. Clarified that VOSI-availability is no longer restricted to a +% specific name or location. +% +% \subsection{WD-TAP-1.1-20150930} +% +% Clarified that MAXREC always overrides limitations in the query (e.g. +% TOP in an ADQL query). +% +% Clarified that services are not required to support queries that reference tables +% in different schema. This is primarily to allow the \tapschema{} to be implemented +% in a different server from the content. +% +% Completed the references section. +% +% \subsection{Changes from TAP-1.0} +% +% Added table\_index and column\_index to \tapschema. +% +% Clarified the relationship of MAXREC and TOP (in ADQL) and the overflow +% indicator. +% +% Added advice that the size column \tapschema.columns must always be used +% as a delimited identifier because it is a reserved word in many RDBMS +% servers. Added arraysize column to \tapschema.columns to replace size and +% deprecated size (which will be removed in the next major version). +% +% Removed REQUEST and VERSION parameters from interface. +% +% Restructured the document and removed text that duplicates material from DALI. +% Rewrite the overly long introduction with some basic use cases to help define +% the scope and tell readers what TAP is supposed to accomplish. +% +% Made clarifications: restricted allowed table names for UPLOAD, clarified that +% multiple UPLOAD parameters accumulate, deprecated the size column in +% \tapschema.columns and added advice to quote it as a delimited +% identifier, made presence of a TABLE element on VOTable output only required for +% successful queries, added optional DALI-examples endpoint (text TBD). +% +% Defined standardID values for the async and sync resource types and explicitly +% allow for multiple of each resource (typically to support authentication). The +% fixed paths /async and /sync are still required and are to provide anonymous +% query access, which should be compatible with existing services. \bibliography{ivoatex/ivoabib,ivoatex/docrepo} From 726656ca3e06a44a502a4f890c07e8977401d056 Mon Sep 17 00:00:00 2001 From: Markus Demleitner Date: Mon, 26 Aug 2019 11:40:23 +0000 Subject: [PATCH 62/68] TAP: Updating to use docrepo references for IVOA documents. --- TAP.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/TAP.tex b/TAP.tex index f965929..e77956d 100644 --- a/TAP.tex +++ b/TAP.tex @@ -163,7 +163,7 @@ \subsection{Role within the VO Architecture} For example, the overflow reporting and xtype attribute were introduced in VOTable 1.2 so that is the minimum viable version that must be used. -\item[SSO \citep{std:SSOAUTH2}] TAP services that support authenticated +\item[SSO \citep{2017ivoa.spec.0524T}] TAP services that support authenticated access declare this in their capabilities using recommendations and security method identifiers from the SSO standard. \end{description} @@ -178,7 +178,7 @@ \subsection{Role within the VO Architecture} references DALI 1.1's serialisation rules for geometries and timestamps and recommends implementing the examples endpoint defined by DALI. -\item[Obscore \citep{std:OBSCORE11}] The Obscore data model +\item[Obscore \citep{2017ivoa.spec.0509L}] The Obscore data model facilitates the publication of metadata of observational data products. TAP is used to access compliant metadata collections. @@ -433,7 +433,7 @@ \subsection{VOSI-capabilities} This specification requires that exactly one capability with a standardID of \nolinkurl{ivo://ivoa.net/std/TAP} is present. In addition to this basic service description, production services -should use the TAPRegExt \citep{std:TAPREGEXT} extension to provide +should use the TAPRegExt \citep{2012ivoa.spec.0827D} extension to provide additional metadata within the TAP capability. Clients should create the endpoint URLs by appending the fixed endpoint names to the access URL given in the interface defined in the TAP capability. The TAP capability normally From d6077c140fd52deba9ae9c408f341469d63089e6 Mon Sep 17 00:00:00 2001 From: Marco Molinaro Date: Tue, 10 Sep 2019 06:13:13 +0000 Subject: [PATCH 63/68] Updating date for Exec PR submissioon --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index e111f43..efd22bc 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2019-06-26 +DOCDATE = 2019-08-26 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = PR From dd116023001e802c70a7e840ebaae4cbcebeccb7 Mon Sep 17 00:00:00 2001 From: Marco Molinaro Date: Fri, 11 Oct 2019 08:27:28 +0000 Subject: [PATCH 64/68] TAP-1.1 REC meta --- Makefile | 4 ++-- TAP.tex | 3 +++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index efd22bc..629d6e8 100644 --- a/Makefile +++ b/Makefile @@ -7,10 +7,10 @@ DOCNAME = TAP DOCVERSION = 1.1 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2019-08-26 +DOCDATE = 2019-09-27 # What is it you're writing: NOTE, WD, PR, or REC -DOCTYPE = PR +DOCTYPE = REC # Source files for the TeX document (but the main file must always # be called $(DOCNAME).tex diff --git a/TAP.tex b/TAP.tex index e77956d..592a9a4 100644 --- a/TAP.tex +++ b/TAP.tex @@ -22,6 +22,9 @@ \editor{Patrick Dowler} +\previousversion[http://www.ivoa.net/Documents/TAP/20190826/]{PR-TAP-1.1-20190826} +\previousversion[http://www.ivoa.net/Documents/TAP/20190626/]{PR-TAP-1.1-20190626} +\previousversion[http://www.ivoa.net/Documents/TAP/20190420/]{PR-TAP-1.1-20190420} \previousversion[http://www.ivoa.net/Documents/TAP/20181024/]{PR-TAP-1.1-20181024} \previousversion[http://www.ivoa.net/Documents/TAP/20180830/]{PR-TAP-1.1-20180830} \previousversion[http://www.ivoa.net/Documents/TAP/20180416/]{PR-TAP-1.1-20180416} From b4a8024f7b54e0dad9033eacd3eb69f6e400abb2 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 11 Aug 2020 09:02:14 -0700 Subject: [PATCH 65/68] Include CC-BY-SA-4.0 license --- LICENSE | 428 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 428 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a73481c --- /dev/null +++ b/LICENSE @@ -0,0 +1,428 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. + From 98ced0fd1996d83d25d0c6eead2debdb5ea96010 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 11 Aug 2020 09:06:07 -0700 Subject: [PATCH 66/68] Add ivoatex submodule --- .gitmodules | 3 +++ ivoatex | 1 + 2 files changed, 4 insertions(+) create mode 100644 .gitmodules create mode 160000 ivoatex diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..9785d46 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "ivoatex"] + path = ivoatex + url = https://github.com/ivoa-std/ivoatex diff --git a/ivoatex b/ivoatex new file mode 160000 index 0000000..544ddbd --- /dev/null +++ b/ivoatex @@ -0,0 +1 @@ +Subproject commit 544ddbd18b99848dc42af6805d4c54c9468133c5 From 12d2c8128514824a1b112b5ca1607c977f6136f3 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 11 Aug 2020 09:06:31 -0700 Subject: [PATCH 67/68] Remove supported SVN tags --- TAP.tex | 3 --- 1 file changed, 3 deletions(-) diff --git a/TAP.tex b/TAP.tex index 592a9a4..9da5824 100644 --- a/TAP.tex +++ b/TAP.tex @@ -1,9 +1,6 @@ \documentclass[11pt,letter]{ivoa} \input tthdefs -\SVN$Rev$ -\SVN$Date$ -\SVN$URL$ \usepackage{listings} \usepackage{relsize} From b979a2710bb38cd7fecba6186d98d1c839dcde2b Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 11 Aug 2020 09:11:07 -0700 Subject: [PATCH 68/68] add CI workflow --- .github/workflows/build.yml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/workflows/build.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..31f8314 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,32 @@ +name: CI build of the standard + +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v1 + with: + submodules: true + - name: Setup dependencies + run: | + sudo apt update + sudo apt install texlive-latex-base texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended xsltproc ghostscript cm-super librsvg2-bin inkscape + + - name: Build the document + run: make role_diagram.pdf biblio forcetex + + - name: Check the output + run: | + test -f TAP.pdf + test -f TAP.bbl + + - uses: actions/upload-artifact@v1 + with: + name: TAP.pdf Preview + path: TAP.pdf