/[volute]/trunk/projects/dal/DALI/DALI.tex
ViewVC logotype

Contents of /trunk/projects/dal/DALI/DALI.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3304 - (show annotations)
Thu Apr 14 19:42:27 2016 UTC (4 years, 5 months ago) by pdowler.cadc
File MIME type: application/x-tex
File size: 57649 byte(s)
added missing change item; updated release timestamp in Makefile

1 \documentclass[11pt,letter]{ivoa}
2 \input tthdefs
3
4 \usepackage{todonotes}
5 \usepackage{listings}
6 \lstloadlanguages{XML}
7 \lstset{flexiblecolumns=true,basicstyle=\small,tagstyle=\ttfamily}
8
9
10 \title{Data Access Layer Interface}
11
12 \ivoagroup{Data Access Layer Working Group}
13
14 \author{Patrick Dowler}
15 \author{Markus Demleitner}
16 \author{Mark Taylor}
17 \author{Doug Tody}
18
19 \editor{Patrick Dowler}
20
21 \previousversion[http://www.ivoa.net/Documents/DALI/1.0]{DALI-1.0}
22
23 \begin{document}
24
25 \begin{abstract}
26 This document describes the Data Access Layer Interface (DALI). DALI defines
27 the base web service interface common to all Data Access Layer (DAL) services.
28 This standard defines the behaviour of common resources, the meaning and use of
29 common parameters, success and error responses, and DAL service registration.
30 The goal of this specification is to define the common elements that are shared
31 across DAL services in order to foster consistency across concrete DAL service
32 specifications and to enable standard re-usable client and service
33 implementations and libraries to be written and widely adopted.
34 \end{abstract}
35
36
37 \section*{Status of This Document}
38 This document has been produced by the Data Access Layer Working Group.
39
40 It has been reviewed by IVOA Members and other interested parties, and has been
41 endorsed by the IVOA Executive Committee as an IVOA Recommendation. It is a
42 stable document and may be used as reference material or cited as a normative
43 reference from another document. IVOA's role in making the Recommendation is to
44 draw attention to the specification and to promote its widespread deployment.
45 This enhances the functionality and interoperability inside the Astronomical
46 Community.
47
48 A list of current IVOA Recommendations and other technical documents can be
49 found at http://www.ivoa.net/Documents/.
50
51 \section{Introduction}
52 The Data Access Layer Interface (DALI) defines resources, parameters, and
53 responses common to all DAL services so that concrete DAL service specifications
54 need not repeat these common elements.
55
56 \subsection{Role within the VO Architecture}
57 DALI defines how DAL service specifications use other IVOA standards as well as
58 standard internet designs and protocols. Fig.~\ref{fig:archdiag} shows the role
59 this document plays within the IVOA architecture \citep{note:VOARCH}.
60
61 \begin{figure}
62 \centering
63
64 % Get the architecture diagram from the TCG chair
65 % http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG
66 % If they give you a PDF, for now dumb it down to a png by
67 % convert -antialias -density 72x72 archdiag.pdf archdiag.png
68 % Oh -- Notes don't need this; you'd have to remove archdiag.png
69 % from FIGURES in the Makefile, too.
70
71 \includegraphics[width=0.9\textwidth]{archdiag.png}
72 \caption{Architecture diagram for this document}
73 \label{fig:archdiag}
74 \end{figure}
75
76 Astronomical coordinate values accepted and returned by DAL services use a
77 string representation of the Space-Time Coordinates \citep{std:STC} data
78 model. The
79 concrete DAL service specification defines whether the returned resources are
80 serializations of a particular standard data model. For preserving backwards
81 compatibility or to enable service-specific use cases, the concrete DAL service
82 specification may explicitly specify the use of ad-hoc Utypes.
83
84 A registry extension schema, usually extending VODataService \citep{std:VODS11},
85 may be used to
86 describe the capabilities of a DAL service. This schema is used within the
87 VOSI-capabilities \citep{std:VOSI} resource and in registry records for the
88 service.
89
90 \subsection{Example Usage of the DALI Specification}
91 The DALI specification defines common elements that make up Data Access Layer
92 (DAL) services. DAL service specifications will refer to the sections in this
93 document by name rather than include all the explanatory text. For example,
94 suppose a document defines a service that stacks FITS images asynchronously, the
95 specification could say that the service has the following resources:
96
97
98 \begin{itemize}
99 \item a DALI-async resource that accepts one or more UPLOAD parameters
100 (section~\ref{sec:UPLOAD}) where the resources are FITS images; the resource
101 could also define a fixed set of error messages for anticipated failure modes
102
103 \item a VOSI-availability resource (section~\ref{sec:vosi-availability})
104
105 \item a VOSI-capabilities resource (section~\ref{sec:vosi-capabilities}) conforming
106 to a specified registry extension schema
107 \end{itemize}
108
109 and would have to define the registry extension schema to be used to register
110 services and to implement the VOSI-capabilities resource. Most of the service
111 specification would be in defining the semantics (possibly controllable via
112 additional input parameters) of the computations to be performed and in defining
113 the extension schema to describe service functionality and limits (e.g., maximum
114 input or result image sizes, result retention time and policies). The registry
115 extension schema may be part of the service specification or a separate
116 document.
117
118 \section{Resources}
119 \label{sec:resources}
120 DAL services are normally implemented as HTTP REST \citep{fielding00}
121 web services, although
122 other transport protocols could be used in the future. The primary resource in
123 a DAL service is a job. A DAL job is defined by parameters
124 (section~\ref{sec:parameters}) and
125 can be executed either synchronously or asynchronously. A concrete service
126 specification defines the job parameters and the manner of execution is defined
127 by separate resources below.
128
129 In addition to job list resources, DAL services also implement several Virtual
130 Observatory Support Interface \citep{std:VOSI} resources to describe
131 service availability, capabilities, and content.
132
133 A concrete DAL service must define at least one DALI-async or DALI-sync
134 resource. It may define both with the same job semantics (e.g. TAP-1.0
135 \citep{std:TAP}) or it may define one with one kind of job and the other with a
136 separate kind of job (a service that does some things synchronously and others
137 asynchronously).
138
139 The following table summarises the resources that are required in all concrete
140 DAL service specifications (and thus in all DAL services) and which kinds of
141 resources are defined and specified as required or optional in a concrete
142 specification.
143
144
145 \begin{tabular}{l l l l l}
146 \sptablerule
147 \textbf{resource type} & \textbf{resource name} & \textbf{required} \\
148 \sptablerule
149 DALI-sync & service specific & service specific & \\
150 DALI-async & service specific & service specific & \\
151 DALI-examples & /examples & no & \\
152 VOSI-availability & service specific & yes & \\
153 VOSI-capabilities & /capabilities & yes & \\
154 VOSI-tables & service specific & service specific & \\
155 \sptablerule
156 \label{tab:resources}
157 \end{tabular}
158
159 The resource name is the path (relative to the base URL of the service). All
160 DALI and VOSI-tables resources must be siblings of the VOSI-capabilities resource, but
161 concreete service specifications should not constrain the names of these resources further.
162 The relative path limitation enables a client with just the URL for a single resource to
163 find the VOSI-capabilities resource and then discover all the capabilities
164 provided by the service. The naming freedom allows implementers to provide alternate paths to
165 resources; this is needed in order to provide both anonymous and authenticated access to a
166 caability.
167
168 The URL for the VOSI-availability is not constrained; it may be a sibling (e.g. /availability)
169 or it may be URLs hosted on a different server (e.g. VOSI-availability may be implemented as a
170 completely external resource that tests the service from the user perspective).
171
172 A simple query-only DAL service like ConeSearch can be easily described as
173 having a single DALI-sync resource where the job is a query and the response is
174 the result of the query.
175
176 \subsection{Asynchronous Execution: DALI-async}
177 \label{sec:dali-async}
178 Asynchronous resources are resources that represent a list of asynchronous jobs
179 as defined by the Universal Worker Service (UWS) pattern \citep{std:UWS}.
180 Requests can
181 create, modify, and delete jobs in the job list. UWS also specifies special
182 requests to modify the phase of the job (cause the job to execute or abort).
183
184 As specified in UWS, a job is created by using the HTTP POST method to modify
185 the job list. The response will always be an HTTP redirect (status code 303) and
186 the Location (HTTP header) will contain the URL to the job (a child resource of
187 the job list).
188
189 \begin{verbatim}
190 POST http://example.com/base/async-jobs
191 \end{verbatim}
192
193 The response will include the HTTP status code 303 (See Other) and a header
194 named Location with a URL to the created job as a value, for example:
195
196 \begin{verbatim}
197 Location: http://example.com/base/async-jobs/123
198 \end{verbatim}
199
200 The job description (an XML document defined by the UWS schema) can always be
201 retrieved by accessing the job URL with the HTTP GET method:
202
203 \begin{verbatim}
204 GET http://example.com/base/async-jobs/123
205 \end{verbatim}
206
207 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
208 <?xml version="1.0" encoding="UTF-8"?>
209 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0">
210 <uws:jobId>123</uws:jobId>
211 <uws:runId>test</uws:runId>
212 <uws:ownerId xsi:nil="true" />
213 <uws:phase>PENDING</uws:phase>
214 <uws:quote>2013-01-01T12:34:56</uws:quote>
215 <uws:startTime/>
216 <uws:endTime/>
217 <uws:executionDuration>600</uws:executionDuration>
218 <uws:destruction>2013-02-01T00:00:00</uws:destruction>
219 <uws:parameters>
220 <uws:parameter id="LANG">ADQL</uws:parameter>
221 <uws:parameter id="REQUEST">doQuery</uws:parameter>
222 <uws:parameter id="QUERY">select * from tab</uws:parameter>
223 </uws:parameters>
224 <uws:results/>
225 </uws:job>
226 \end{lstlisting}
227
228 In addition to the UWS job metadata, DAL jobs are defined by a set of
229 parameter-value pairs. The client may include parameters in the initial POST
230 that creates a job or it may add additional paramaters by a POST to the current
231 list of parameters, for example:
232
233 \begin{verbatim}
234 http://example.com/base/async-jobs/123/parameters
235 \end{verbatim}
236
237 DALI-async resources may provide other ways to interact with jobs as specified
238 in current or future UWS specifications, with the following exception: the
239 UWS-1.0 standard may be interpreted to allow POSTing of job parameters to the
240 job URL, but DALI-async resources must not accept job parameters at this URL.
241
242 Job parameters may only be POSTed while the job is in the PENDING phase; once
243 execution has been requested and the job is in any other phase, job parameters
244 may not be modified.
245
246 A concrete DAL service specification will specify zero or more asynchronous job
247 submission resources and whether they are mandatory or optional. It may mandate
248 a specific resource name to support simple client use, or it can allow the
249 resource name to be described in the service metadata (Section 2.5 ).
250
251 \subsection{Synchronous Execution: DALI-sync}
252 \label{sec:dali-sync}
253 Synchronous resources are resources that accept a request (a DAL job
254 description) and return the response (the result) directly. Synchronous requests
255 can be made using either the HTTP GET or POST method. If a specific type of job
256 is exposed through both DALI-async and DALI-sync resources (e.g. TAP queries),
257 then the parameters used to specify the job are the same for this pair of
258 (synchronous and asynchronous) jobs. Service specifications may also specify
259 different types of jobs on different resources, which would have different job
260 parameters.
261
262 A synchronous job is created by a GET or POST request to a synchronous job list,
263 executed automatically, and the result returned in the response. The web service
264 is permitted to split the operation of a synchronous request into multiple HTTP
265 requests as long as it is transparent to standard clients. This means that the
266 service may use HTTP redirects (status code 302 or 303) and the Location header
267 to execute a synchronous job in multiple steps. For example, a service may
268
269 \begin{itemize}
270 \item immediately execute and return the result in the response, or
271 \item the response is an HTTP redirect (status code 303) and the Location (HTTP
272 header) will contain a URL; the client accesses this URL with the HTTP GET
273 method to execute the job and get the result
274 \end{itemize}
275
276 Clients must be prepared to get redirects and follow them (using normal HTTP
277 semantics) in order to complete requests.
278
279 A concrete DAL service specification will specify zero or more synchronous job
280 submission resources and whether they are mandatory or optional. It may mandate
281 a specific resource name to support simple client use, or it can allow the
282 resource name to be described in the service capability metadata (Section 2.5 ).
283
284 \subsection{DALI-examples}
285 \label{sec:dali-examples}
286 The DALI-examples resource returns a document with usage examples or similar
287 material to the user. In DAL services, this resource is always accessed as a
288 resource named examples that is a child of the base URL for the service. The
289 following specification is intended to make sure the content is usable for both
290 machines and humans. As such, the DALI-examples resource contains additional
291 markup conforming to the RDFa 1.1 Lite \citep{std:RDFaLite11} specification,
292 which defines the
293 following attributes: \xmlel{vocab}, \xmlel{typeof}, \xmlel{property},
294 \xmlel{resource}, and \xmlel{prefix} (although we
295 do not include any use of the \xmlel{prefix} attribute).
296
297 The DALI-examples capability identifier is:
298
299 $$
300 \hbox{\nolinkurl{ivo://ivoa.net/std/DALI#examples}}
301 $$
302
303 DAL services may implement the /examples resource and include it in the
304 capabilities described by the VOSI-capabilities resource (Section 2.5 ); if they
305 do not, retrieving its URL must yield a 404 HTTP error code.
306
307 The document at /examples must be well-formed XML. This restriction is imposed
308 in order to let clients parse the document using XML parsers rather than
309 much more complex parsers (e.g. HTML5 parsers). It is therefore advisable to
310 author it in XHTML, although this specification does not prescribe any document
311 types.
312
313 The document should be viewable with ``common web browsers''. Javascript or CSS
314 must not be necessary to find and interpret the elements specified below. Apart
315 from that, service operators are free to include whatever material or styling
316 they desire in addition and within the example elements defined here.
317
318 The elements containing examples must be descendants of an element that has a
319 \xmlel{vocab} attribute with the value equal to the DALI-examples capability identifier
320 (above), for example:
321
322 \begin{lstlisting}[language=XML]
323 <div vocab="ivo://ivoa.net/std/DALI#examples">
324 ...
325 </div>
326 \end{lstlisting}
327
328 No other \xmlel{vocab} attributes are allowed in the document. Each example resides in
329 an element that has a \xmlel{typeof} attribute with the value
330 \emph{example}. All such elements
331 must have an \xmlel{id} attribute to allow external referencing via fragments and a
332 \xmlel{resource} attribute with a reference pointing to the element itself. As an
333 example,
334
335 \begin{lstlisting}[language=XML]
336 <div id="x" resource="#x" typeof="example"> ... </div>
337 \end{lstlisting}
338
339 \noindent located inside the element having the \xmlel{vocab} attribute would
340 contain an example referrable via the \emph{x} fragment identifier. The
341 \xmlel{div} element is
342 a suitable HTML element to hold an example.
343
344 The content of the example is expressed using the \xmlel{property} attribute. For
345 DALI-examples, we define the following values for the \xmlel{property} attribute:
346
347 \begin{itemize}
348 \item \emph{name}
349 \item \emph{capability}
350 \item \emph{generic-parameter}
351 \item \emph{continuation}.
352 \end{itemize}
353
354 Each example must include one
355 name. DAL service specifications may define additional
356 properties so they can mark up additional information in their examples.
357
358 In principle, any element permitted by the document type can include the RDFa
359 attributes, so authors may re-use existing markup intended for display.
360 Alternatively, the \xmlel{span} element is a good choice when the example values are
361 included in surrounding text and the author does not want any special rendering
362 to be applied by the machine-readable additions.
363
364 \subsubsection{name property}
365
366 The content of this element should be suitable for display within a
367 space-limited label in user interface and still give some idea about the meaning
368 of the example. In XHTML, a head element (\xmlel{h2}, say) would usually be a good
369 choice for the example name, for example:
370
371 \begin{lstlisting}[language=XML]
372 <h2 property="name">Synchronous TAP query</h2>
373 \end{lstlisting}
374
375 \subsubsection{capability property}
376
377 The capability property for an example specifies which service capability the
378 example is to be used with. For example, if the text is describing how to use a
379 SODA-1.0 service, the example could contain:
380
381 \begin{lstlisting}[language=XML]
382 <span property="capability">ivo://ivoa.net/std/SODA#sync-1.0</span>
383 \end{lstlisting}
384
385 IVOA standard service capabilities are defined as URIs, so example documents
386 may want to show the URI or show more user-friendly text depending on the
387 expected audience for the document. For specifications that do not define
388 specific capability identifiers, the IVOID for the specification itself should
389 be used.
390
391 \subsubsection{generic-parameter property}
392
393 Request parameters are included within the example by using the
394 generic-parameter property. The element must also be assigned a
395 \xmlel{typeof} attribute
396 with value of \emph{keyval}. Within this element, the document must include a pair of
397 elements with \xmlel{property} attributes valued key and value, where the plain-text content are
398 the parameter name and value respectively. Multiple generic-parameter(s) are
399 permitted, for example:
400
401 \begin{lstlisting}[language=XML]
402 <span property="generic-parameter" typeof="keyval">
403 <span property="key">REQUEST</span>
404 <span property="value">doQuery</span>
405 </span>
406 <span property="generic-parameter" typeof="keyval">
407 <span property="key">LANG</span>
408 <span property="value">ADQL</span>
409 </span>
410 <span property="generic-parameter" typeof="keyval">
411 <span property="key">QUERY</span>
412 <span property="value">SELECT * from tap_schema.tables</span>
413 </span>
414 \end{lstlisting}
415
416 \subsubsection{continuation property}
417
418 If the examples are spread over multiple linked documents, the links to
419 documents with additional examples must be within the parent element defining
420 the \xmlel{vocab} attribute and the link elements must contain the following additional
421 attributes: a \xmlel{property} attribute with the value
422 \emph{continuation}, a \xmlel{resource}
423 attribute with an empty value (referring to the current document), and
424 the \xmlel{href}
425 attribute with the URL of another document formatted as above (i.e. another
426 collection of examples that clients should read to collect the full set of
427 examples).
428
429 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
430 <div vocab="ivo://ivoa.net/std/DALI#examples">
431 <div id="x" resource="#x" typeof="example">
432 <h2 property="name">Synchronous TAP query</h2>
433 <p property="capability">ivo://ivoa.net/std/TAP/v1.0</p>
434 <p property="generic-parameter" typeof="keyval">
435 <span property="key">REQUEST</span>=<span
436 property="value">doQuery</span>
437 </p>
438 <p property="generic-parameter" typeof="keyval">
439 <span property="key">LANG</span>=<span
440 property="value">ADQL</span>
441 </p>
442 <p property="generic-parameter" typeof="keyval">
443 <span property="key">QUERY</span>=<span
444 property="value">SELECT * from tap_schema.tables</span>
445 </p>
446 </div>
447 <a property="continuation"
448 href="simple_examples.html">Simple examples</a>
449 <a property="continuation"
450 href="fancy_examples.html">Fancy examples</a>
451 </div>
452 \end{lstlisting}
453
454 In the above example, the two linked documents would also contain some element
455 with a vocab and examples as described above.
456
457 \subsection{Availability: VOSI-availability}
458 \label{sec:vosi-availability}
459 VOSI-availability \citep{std:VOSI} defines a simple web resource that
460 reports on the current ability of the service to perform.
461
462 All DAL services must implement the VOSI-availability resource and provide a description
463 of this capability in the VOSI-capabilities document. The VOSI-availability resource is
464 intended to respond with a dynamically generated document describing the current state of the service
465 operation, e.g.:
466
467 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
468 <?xml version="1.0" encoding="UTF-8"?>
469 <vosi:availability
470 xmlns:vosi="http://www.ivoa.net/xml/VOSIAvailability/v1.0">
471 <vosi:available>true</vosi:available>
472 <vosi:note>service is accepting queries</vosi:note>
473 </vosi:availability>
474 \end{lstlisting}
475
476 \subsection{Capabilities: VOSI-capabilities}
477 \label{sec:vosi-capabilities}
478 VOSI-capabilities \citep{std:VOSI} defines a simple web resource that
479 returns an XML document
480 describing the service. In DAL services, this resource is always accessed as a
481 resource named capabilities that is a child of the base URL for the service. The
482 VOSI-capabilities should describe all the resources exposed by the service,
483 including which standards each resource implements.
484
485 All DAL services must implement the /capabilities resource. The following
486 capabilities document shows the three VOSI resources and a TAP base resource:
487
488 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
489 <?xml version="1.0" encoding="UTF-8"?>
490 <vosi:capabilities
491 xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
492 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
493 xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">
494
495 <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
496 <interface xsi:type="vod:ParamHTTP" version="1.0">
497 <accessURL use="full">
498 http://example.com/tap/capabilities
499 </accessURL>
500 </interface>
501 </capability>
502
503 <capability standardID="ivo://ivoa.net/std/VOSI#availability">
504 <interface xsi:type="vod:ParamHTTP" version="1.0">
505 <accessURL use="full">
506 http://example.com/tap/availability
507 </accessURL>
508 </interface>
509 </capability>
510
511 <capability standardID="ivo://ivoa.net/std/VOSI#tables">
512 <interface xsi:type="vod:ParamHTTP" version="1.0">
513 <accessURL use="full">
514 http://example.com/tap/tables
515 </accessURL>
516 </interface>
517 </capability>
518
519 <capability xmlns:tr="http://www.ivoa.net/xml/TAPRegExt/v1.0"
520 standardID="ivo://ivoa.net/std/TAP" xsi:type="tr:TableAccess">
521 <interface xsi:type="vod:ParamHTTP" role="std" version="1.0">
522 <accessURL use="full">
523 http://example.com/tap/
524 </accessURL>
525 </interface>
526 <!-- service details from TAPRegExt go here -->
527 </capability>
528 </vosi:capabilities>
529 \end{lstlisting}
530
531 Note that while this example shows the use of a registry extension schema (the
532 inline \verb|xmlns:tr="http://www.ivoa.net/xml/TAPRegExt/v1.0"| in the last capability
533 element) this is not required; services may be registered and described without
534 such an extension. The use of \xmlel{standardID} -- which should contain the
535 IVOID of
536 the standard a capability adheres to -- does not imply a particular (or any)
537 \xmlel{xsi:type} be included.
538
539 \subsection{Tables: VOSI-tables}
540 \label{sec:vosi-tables}
541 VOSI-tables \citep{std:VOSI} defines a simple web resource that returns an
542 XML document
543 describing the content of the service. The document format is defined by the
544 VOSI \citep{std:VOSI} standard and allows the service to
545 describe their content
546 as a tableset: schemas, tables, and columns.
547
548 A concrete DAL service specification will specify if the VOSI-tables resource is
549 permitted or required and may restrict the resource name or location.
550 The current VOSI-tables specification has some scalablity
551 issues for services with many or large tables, so that specification is subject
552 to change in future. Since DAL services with a VOSI-tables resource will specify
553 in the capabilities which version they are using, DAL services can make use of
554 new versions without change to the DAL service specification.
555
556 \section{Parameters}
557 \label{sec:parameters}
558 A DAL job is defined by a set of parameter-value pairs. Some of these parameters
559 have a standard meaning and are defined here, but most are defined by the
560 service specification or another related standard.
561
562 \subsection{Case Sensitivity}
563 Parameter names are not case sensitive; a DAL service must treat
564 \hbox{upper-,} \hbox{lower-,}
565 and mixed-case parameter names as equal. Parameter values are case sensitive
566 unless a concrete DAL service specification explicitly states that the values of
567 a specific parameter are to be treated as case-insensitive. For example, the
568 following are equivalent:
569
570 \begin{verbatim}
571 FOO=bar
572 Foo=bar
573 foo=bar
574 \end{verbatim}
575
576 Unless explicitly stated by the service specification, these are not equivalent:
577
578 \begin{verbatim}
579 FOO=bar
580 FOO=Bar
581 FOO=BAR
582 \end{verbatim}
583
584 In this document, parameter names are typically shown in upper-case for
585 typographical clarity, not as a requirement.
586
587 \subsection{Multiple Values}
588 Parameters may be assigned multiple values with multiple parameter=value pairs
589 using the same parameter name. Whether or not multiple values are permitted and
590 the meaning of multiple values is specified for each parameter by the
591 specification that defines the parameter. For example, the UPLOAD parameter
592 (section~\ref{sec:UPLOAD}) permits multiple occurrences of the specified
593 pair (table,uri), e.g.:
594
595 \begin{verbatim}
596 UPLOAD=foo,http://example.com/foo
597 UPLOAD=bar,http://example.com/bar
598 \end{verbatim}
599
600 Services must respond with an error if the request includes multiple values for
601 parameters defined to be single-valued.
602
603 \subsection{Literal Values}
604 In this section we specify how values are to be expressed. These literal values
605 are used as input or output from DAL services: as parameter values when
606 invoking simple services, as data values in response documents (e.g. VOTable),
607 etc. We define some general purpose values for the \xmlel{xtype} attribute of
608 the VOTable \xmlel{FIELD} and \xmlel{PARAM} elements for simple
609 structured values: \emph{interval},
610 \emph{point}, \emph{circle}, and \emph{polygon} (see below).
611
612 \subsubsection{Numbers}
613 Integer numbers must be represented in a manner consistent with the
614 specification for integers in XML Schema Datatypes \citep{std:XSD2}.
615
616 Real numbers must be represented in a manner consistent with the specification
617 for double-precision numbers in XML Schema Datatypes \citep{std:XSD2}. This
618 representation allows for integer, decimal and exponential notations.
619
620 \subsubsection{Boolean}
621 Boolean values must be represented in a manner consistent with the
622 specification
623 for Boolean in XML Schema Datatypes \citep{std:XSD2}. The values 0 and false
624 are equivalent. The values 1 and true are equivalent.
625
626 \begin{verbatim}
627 FOO=1
628 FOO=true
629 \end{verbatim}
630
631 \begin{verbatim}
632 BAR=0
633 BAR=false
634 \end{verbatim}
635
636 \subsubsection{Timestamp}
637 Date and time values must be represented using the convention established for
638 FITS \citep{std:FITS} and STC \citep{std:STC}:
639
640 \begin{verbatim}
641 YYYY-MM-DD['T'hh:mm:ss[.SSS]]
642 \end{verbatim}
643
644 where the T is a character separating the date and time components. The time
645 component is optional, in which case the T separator is not used. Fractions of a
646 second are permitted but not required. For example:
647
648 \begin{verbatim}
649 2000-01-02T15:20:30.456
650 2001-02-03T04:05:06
651 2002-03-04
652 \end{verbatim}
653
654 are all legal date or date plus time values. Values never include a time zone
655 indicator and are always interpreted as follows. In cases where values may be
656 expressed using Julian Date (JD) or Modified Julian Date (MJD), these follow the
657 rules for double precision numbers above and may have additional metadata as
658 described in the VOTable standard \citep{std:VOTABLE}. All date-time values (formatted string, JD,
659 and MJD) shall be interpreted as referring to time scale UTC and time reference
660 position UNKNOWN, unless either or both of these are explicitly specified to be
661 different \citep{std:STC}.
662
663 Note that the format used here is very close to the standard ISO8601 timestamp
664 format except with respect to timezone handling. ISO8601 requires a Z character
665 at the end of the string when the timezone is UTC; here, we follow the FITS
666 \citep{std:FITS} convention by omitting the Z but still defaulting to UTC.
667
668 Timestamp values serialised on VOTable or in service parameters must have the following metadata in
669 the \xmlel{FIELD} element: \verb|datatype="char"|, \verb|arraysize="*"|,
670 \verb|xtype="timestamp"|; the arraysize may be set to a more specific value if it is known (e.g.
671 \verb|arraysize="10"| for dates only).
672
673 \subsubsection{Intervals}
674 Numeric intervals are pairs of numeric values (integer and floating-pont). For floating point
675 intervals, special values for positive and negative infinity may be used to specify open-ended intervals.
676 Finite bounding values are included in the interval. Open-ended floating-point
677 intervals have one or both bounding values that are infinite. Intervals with two identical values
678 are equivalent to a scalar value but must still be serialised as a pair of values.
679
680 The representation of an interval follows the array serialisation from VOTable. For example:
681
682 \begin{verbatim}
683 0.5 1.0
684 -Inf 0.0
685 0.0 Inf
686 -Inf Inf
687 1.0 1.0
688 \end{verbatim}
689
690
691 \noindent are all legal floating-point interval values and:
692
693 \begin{verbatim}
694 0 2
695 -5 5
696 0 0
697 \end{verbatim}
698
699 \noindent are all legal integer interval values.
700
701 Floating point interval values serialised in VOTable or service parameters must have the following metadata in the
702 \xmlel{FIELD} element: \verb|datatype="double"| or \verb|datatype="float"|,
703 \verb|arraysize="2"|, \verb|xtype="interval"|.
704
705 Integer interval values serialised in VOTable or service parameters must have the following metadata in the
706 \xmlel{FIELD} element: \verb|datatype="short"| or \verb|datatype="int"| or
707 \verb|datatype="long"|, \verb|arraysize="2"|, \verb|xtype="interval"|.
708
709 \subsubsection{Point}
710 Geometry values are two-dimensional; although they are usually longitude and
711 latitude values in spherical coordinates this is specified in the coordinate
712 metadata and not in the values.
713
714 Point values serialised in VOTable or service parameters must have the following metadata in the
715 \xmlel{FIELD} element: \verb|datatype="double"| or \verb|datatype="float"|, \verb|arraysize="2"|,
716 \verb|xtype="point"|. For points in a
717 spherical coordinate system, the values are ordered as: longitude latitude. For
718 example:
719
720 \begin{verbatim}
721 12.3 45.6
722 \end{verbatim}
723
724 \subsubsection{Circle}
725 Circle values serialised in VOTable or service parameters must have the following metadata in the
726 \xmlel{FIELD} element: \verb|datatype="double"| or \verb|datatype="float"|, \verb|arraysize="3"|,
727 \verb|xtype="circle"|. For circles
728 in a spherical coordinate system, the values are ordered as: longitude latitude
729 radius; longitude values must fall within [0,360], latitude values within [-90,90], and radius values in (0, 90]. For example:
730
731 \begin{verbatim}
732 12.3 45.6 0.5
733 \end{verbatim}
734
735 \subsubsection{Polygon}
736 Polygon values serialised in VOTable or service parameters must have the following metadata in the
737 \xmlel{FIELD} element: \verb|datatype="double"| or \verb|datatype="float"|, \verb|arraysize="*"|,
738 \verb|xtype="polygon"|. The
739 array holds a sequence of vertices (points) (e.g. longitude latitude longitude
740 latitude ...) with an even number of values and at least three (3) points (six
741 (6) numeric values). For example:
742
743 \begin{verbatim}
744 10.0 10.0 10.2 10.0 10.2 10.2 10.0 10.2
745 \end{verbatim}
746
747 In spherical coordinates, all longitude values must fall within [0,360] and all
748 latitude values within [-90,90].
749
750 \todo{Choose one of these options}
751 Option 1: The vertices of a polygon must be specified in counter-clockwise
752 order.
753
754 Option 2: The vertices of a polygon may be specified in clockwise or
755 counter-clockwise order. The inside is the region with the smallest area;
756 polygons in spherical coordinates are limited to less than half the sphere.
757
758 \subsubsection{More geometry?}
759 \todo{Do we want any of this?}
760 Ellipse? Coord-range? STC Box?
761
762 \subsection{Standard Parameters}
763
764 \subsubsection{REQUEST}
765 \label{sec:REQUEST}
766 The REQUEST parameter is intended for service capabilities that have
767 multiple modes or operations, including non-standard (site-specific) optional
768 features. Most standard service capabilities will not define values for this
769 parameter.
770
771 If defined for a specific service capability, the REQUEST parameter is always
772 single-valued.
773
774 \subsubsection{VERSION}
775 \label{sec:VERSION}
776 The VERSION parameter has been removed because the different
777 meaning of request
778 parameters it is intended to disambiguate are not allowed within minor
779 revisions of a standard; there are no useful scenarios where VERSION would work.
780
781 \subsubsection{RESPONSEFORMAT}
782 \label{sec:RESPONSEFORMAT}
783 The RESPONSEFORMAT parameter is used so the client can specify the format of the
784 response (e.g. the output of the job). For DALI-sync requests, this is the
785 content-type of the response. For DALI-async requests, this is the content-type
786 of the result resource(s) the client can retrieve from the UWS result list
787 resource; if a DALI-async job creates multiple results, the RESPONSEFORMAT
788 should control the primary result type, but details can be specific to
789 individual service specifications. While the list of supported values are
790 specific to a concrete service specification, the general usage is to support
791 values that are MIME media types \citep{std:MIME} for known
792 formats as well as
793 shortcut symbolic values.
794
795 \begin{tabular}{l l l l l}
796 \sptablerule
797 table type & media type & short form \\
798 \sptablerule
799 VOTable & application/x-votable+xml & votable & \\
800 VOTable & text/xml & votable & \\
801 comma-separated values & text/csv & csv & \\
802 tab separated values & text/tab-separated-values & tsv & \\
803 FITS file & application/fits & fits & \\
804 pretty-printed text & text/plain & text & \\
805 pretty-printed Web page & text/html & html & \\
806 \sptablerule
807 \label{tab:mimetypes}
808 \end{tabular}
809
810 In some cases, the specification for a specific format may be parameterised
811 (e.g., the media type may include optional semi-colon and additional key-value
812 parameters). A DAL service must accept a RESPONSEFORMAT parameter indicating a
813 format that the service supports and should fail (Section 4.2 ) where the
814 RESPONSEFORMAT parameter specifies a format not supported by the service
815 implementation.
816
817 A concrete DAL service specification will specify any mandatory or optional
818 formats as well as new formats not listed above; it may also place limitations
819 on the structure for formats that are flexible. For example, a resource that
820 responds with tabular output may impose a limitation that FITS files only
821 contain FITS tables, possibly only of specific types (ascii or binary).
822
823 If a client requests a format by specifying the media type (as opposed to one of
824 the short forms), the response that delivers that content must set that
825 media type
826 in the Content-Type header. This is only an issue when a format has multiple
827 acceptable media types (e.g., VOTable). This allows the client to control the
828 Content-Type so that it can reliably cause specific applications to handle the
829 response (e.g., a browser rendering a VOTable generally requires the text/xml
830 media type). If the client requests a plain media type (e.g., not parameterised) and
831 the media type does allow optional parameters, the service may respond with a
832 parameterised media type to more clearly describe the output. For example, the
833 text/csv media type allows two optional parameters: charset and header. If the
834 request includes RESPONSEFORMAT=text/csv the response could have Content-Type
835 text/csv or text/csv;header=absent at the discretion of the service. If the
836 request specifies specific values for parameters, the response must be
837 equivalent.
838
839 Individual DAL services (not just specifications) are free to support custom
840 formats by accepting non-standard values for the RESPONSEFORMAT parameter.
841
842 The RESPONSEFORMAT parameter should not be confused with the FORMAT parameter
843 used in many DAL services. The latter is generally used as a query parameter to
844 search for data in the specified format; FORMAT and RESPONSEFORMAT have the same
845 sense in TAP-1.0, but this is not generally the case.
846
847 The RESPONSEFORMAT parameter is always single-valued.
848
849 \subsubsection{MAXREC}
850 \label{sec:MAXREC}
851 For resources performing discovery (querying for an arbitrary number of
852 records), the resource must accept a MAXREC parameter specifying the maximum
853 number of records to be returned. If MAXREC is not specified in a request, the
854 service may apply a default value or may set no limit. The service may also
855 enforce a limit on the value of MAXREC that is smaller than the value in the
856 request. If the size of the result exceeds the resulting limit, the service must
857 only return the requested number of rows. If the result set is truncated in this
858 fashion, it must include an overflow indicator as specified in Section 4.4.1 .
859
860 The service must support the special value of MAXREC=0. This value indicates
861 that, in the event of an otherwise valid request, a valid response be returned
862 containing metadata, no results, and an overflow indicator (Section 4.4.1 ). The
863 service is not required to execute the request and the overflow indicator does
864 not necessarily mean that there is at least one record satisfying the query. The
865 service may perform validation and may try to execute the request, in which case
866 a MAXREC=0 request can fail.
867
868 The MAXREC parameter is always single-valued.
869
870 \subsubsection{UPLOAD}
871 \label{sec:UPLOAD}
872 The UPLOAD parameter is used to reference read-only external resources
873 (typically files) via their URI, to be uploaded for use as input resources to
874 the query. The value of the UPLOAD parameter is a resource name-URI pair. For
875 example:
876
877 \begin{verbatim}
878 UPLOAD=table1,http://example.com/t1
879 \end{verbatim}
880
881 would define an input named table1 at the given URI. Resource names must be
882 simple strings made up of alphabetic, numeric, and the underscore characters
883 only and must start with an alphabetic character.
884
885 Services that implement UPLOAD must support http as a URI scheme (e.g., must
886 support treating an http URI as a URL). A VOSpace URI (vos:<something>) is a
887 more generic example of a URI that requires more service-side functionality;
888 support for the vos scheme is optional.
889
890 To upload a resource inline, the caller specifies the UPLOAD parameter (as
891 above) using a special URI scheme \emph{param}. This scheme indicates that the value
892 after the colon will be the name of the inline content. The content type used is
893 multipart/form-data, using a \emph{file} type input element. The \xmlel{name} attribute
894 must match that used in the UPLOAD parameter.
895
896 For example, in the POST data we would have this parameter:
897
898 \begin{verbatim}
899 UPLOAD=table3,param:t3
900 \end{verbatim}
901
902 and this content:
903
904 \begin{verbatim}
905 Content-Type: multipart/form-data; boundary=AaB03
906 [...]
907 --AaB03x
908 Content-disposition: form-data; name="t3"; filename="t3.xml"
909 Content-type: application/x-votable+xml
910 [...]
911 --AaB03x
912 [...]
913 \end{verbatim}
914
915 If inline upload is used by a client, the client must POST both the UPLOAD
916 parameter and the associated inline content in the same request. Services that
917 implement upload of resources must support the param scheme for inline uploads.
918
919 In principle, any number of resources can be uploaded using the UPLOAD parameter
920 and any combination of URI schemes supported by the service as long as they are
921 assigned unique names in the request. For example:
922
923 \begin{verbatim}
924 UPLOAD=table1,http://example.com/t1.xml
925 UPLOAD=image1,vos://example.authority!tempSpace/foo.fits
926 UPLOAD=table3,param:t3
927 \end{verbatim}
928
929 Services may limit the size and number of uploaded resources; if the service
930 refuses to accept the upload, it must respond with an error as described in
931 Section \ref{sec:response-error}. Specific service specifications specify how uploaded resources are
932 referenced in other request parameters (for example, in a query), and
933 interpreted.
934
935 \subsubsection{RUNID}
936 \label{sec:RUNID}
937 The service should implement the RUNID parameter, used to tag service requests
938 with the identifier of a larger job of which the request may be part. The RUNID
939 value is a string with a maximum length of 64 characters.
940
941 For example, if a cross match portal issues multiple requests to remote services
942 to carry out a cross-match operation, all would receive the same RUNID, and the
943 service logs could later be analysed to reconstruct the service operations
944 initiated in response to the job. The service should ensure that RUNID is
945 preserved in any service logs and should pass on the RUNID value in calls to
946 other services made while processing the request.
947
948 The RUNID parameter is always single-valued.
949
950 \section{Responses}
951 \label{sec:responses}
952 All DAL service requests eventually result in one of three kinds of responses:
953 successful HTTP status code (200) and a service- and resource-specific
954 representation of the results, an HTTP status code and a standard error document
955 (see below) or a service- and resource-specific error document, or a redirect
956 HTTP status code (302 or 303) with a URL in the HTTP Location header.
957
958 \subsection{Successful Requests}
959 \label{sec:response-ok}
960 Successfully executed requests must eventually (after zero or more redirects)
961 result in a response with HTTP status code 200 (OK) and a response in the format
962 requested by the client (Section \ref{sec:RESPONSEFORMAT}) or in the default format for the
963 service. The service should set HTTP headers (\citep{std:HTTP}) that are useful to the correct values
964 where possible. Recommended headers to set when possible:
965
966 \begin{tabular}{l l l l l}
967 \label{tab:headers}
968 Content-Type \\
969 Content-Encoding \\
970 Content-Length \\
971 Last-Modified \\
972 \end{tabular}
973
974 For jobs executed using a DALI-async resource, the result(s) must be made
975 available as child resources of the result list and directly accessible there.
976 For jobs that inherently create a fixed result, service specifications may
977 specify the name of the result explicitly. For example, TAP-1.0 has a single
978 result and it must be named result, e.g.:
979
980 \begin{verbatim}
981 GET http://example.com/base/joblist/123/results/result
982 \end{verbatim}
983
984 For concrete DAL service specifications where multiple result files may be
985 produced, the specification may dictate the names or it may leave it up to
986 implementations to choose suitable names.
987
988 \subsection{Errors}
989 \label{sec:response-error}
990 If the service detects an exceptional condition, it must return an error
991 document with an appropriate HTTP-status code. DAL services distinguish three
992 classes of errors:
993
994 \begin{itemize}
995 \item Errors in communicating with the DAL service
996
997 \item Errors in the use of the specific DAL protocol, including an invalid
998 request
999
1000 \item Errors caused by a failure of the service to complete a valid request
1001 \end{itemize}
1002
1003 Error documents for communication errors, including those caused by accessing
1004 non-existent resources, authentication or authorization failures, services being
1005 off-line or broken are not specified here since responses to these errors may be
1006 generated by other off-the-shelf software and cannot be controlled by service
1007 implementations. There are several cases where a DAL service could return such
1008 an error. First, a DALI-async resource must return a 404 (not found) error if
1009 the client accesses a job within the UWS job list that does not exist, or
1010 accesses a child resource of the job that does not exist (e.g., the error
1011 resource of a job that has not run and failed, or a specific result resource in
1012 the result list that does not exist). Second, access to a resource could result
1013 in an HTTP 401 (not authorized) response if authentication is required or an
1014 HTTP 403 (forbidden) error if the client is not allowed to access the requested
1015 resource. Although UWS is currently specified for HTTP transport only, if it
1016 were to be extended for use via other transport protocols, the normal mechanisms
1017 of those protocols should be used.
1018
1019 An error document describing errors in use of the DAL service protocol may be a
1020 VOTable document \citep{std:VOTABLE} or a plain text document.
1021 The content of
1022 VOTable error documents is described in Section \ref{sec:use-votable} below. Service
1023 specifications will enumerate specific text to be included. For plain text error
1024 documents the required text would be included at the start of the document; for
1025 VOTable error documents, the required (and optional) text would be included as
1026 content of the INFO element described in Section 4.4.2 . In either case, DAL
1027 services will allow service implementers to add additional explanatory text
1028 after the required text (on the same line or on subsequent lines). In all cases,
1029 these are errors that occur when the job is executed and do not override any
1030 error behaviour for a UWS resource which specifies the behaviour and errors
1031 associated with interacting with the job itself.
1032
1033 If the invalid job is being executed using a DALI-async resource, the error
1034 document must be accessible from the <DALI-async>/<jobid>/error resource
1035 (specified by UWS) and when accessed via that resource it must be returned with
1036 an HTTP status code 200, e.g.:
1037
1038 \begin{verbatim}
1039 GET http://example.com/base/joblist/123/error
1040 \end{verbatim}
1041
1042 For DALI-async errors, services should recommend and may mandate that required
1043 text be included in the error summary field of the UWS job in addition to the
1044 error document; this permits generic UWS clients to consume the standard part of
1045 the error description.
1046
1047 If the error document is being returned directly after a DALI-sync request, the
1048 service should use a suitable error code to describe the failure and include the
1049 error document in the body of the response. The Content-Type header will tell
1050 the client the format of the error document that is included in the body of the
1051 response. In general, HTTP status codes from 400-499 signify a problem with the
1052 client request and status codes greater than or equal to 500 signify that the
1053 request is (probably) valid but the server has failed to function. For transport
1054 protocols other than HTTP, the normal error reporting mechanisms of those
1055 protocols should be used.
1056
1057 \subsection{Redirection}
1058 \label{sec:redirects}
1059 A concrete DAL service specification may require that HTTP redirects (302 or
1060 303) be used to communicate the location of an alternate resource which should
1061 be accessed by the client via the HTTP GET method. For example, the UWS pattern
1062 used for DALI-async (Section 2.1 ) requires this behaviour. Even when not
1063 required, concrete DAL service specifications must allow implementers to use
1064 redirects and clients must be prepared to follow these redirects using normal
1065 HTTP semantics \citep{std:HTTP}.
1066
1067 \subsection{Use of VOTable}
1068 \label{sec:use-votable}
1069 VOTable is a general format. In DAL services we require that it be used in a
1070 particular way. The result VOTable document must comply with VOTable v1.2
1071 \citep{std:VOTABLE}
1072 or later versions.
1073
1074 The VOTable format permits table creators to add additional metadata to describe
1075 the values in the table. Once a standard for including such metadata is
1076 available, service implementers should use such mechanisms to augment the
1077 results with additional metadata. Concrete DAL service specifications may
1078 require additional metadata of this form.
1079
1080 The VOTable must contain one \xmlel{RESOURCE} element identified with the attribute
1081 \verb|type="results"|; this resource contains the primary result (e.g., the only result
1082 for simple DAL services). Concrete DAL service specifications define what goes
1083 into the primary result. The primary \xmlel{RESOURCE} element must contain, before the
1084 \xmlel{TABLE} element, an
1085 \xmlel{INFO} element with attribute \xmlel{name} valued \emph{QUERY\_STATUS}. The value
1086 attribute must contain one of the following values:
1087
1088 \begin{tabular}{l p{8cm}}
1089 \sptablerule
1090 \emph{QUERY\_STATUS}&\textbf{Interpretation}\\
1091 \sptablerule
1092 OK & the job executed successfully and the result is included in the resource \\
1093 ERROR & an error was detected at the level of the protocol, the job failed to
1094 execute, or an error occurred while writing the table data \\
1095 OVERFLOW & the job executed successfully, the result is included in the
1096 resource, and the result was truncated at MAXREC rows \\
1097 \sptablerule
1098 \label{tab:query-status}
1099 \end{tabular}
1100
1101 The content of the \xmlel{INFO} element conveying the status should be a message
1102 suitable for display to the user describing the status.
1103
1104 \begin{lstlisting}[language=XML]
1105 <INFO name="QUERY_STATUS" value="OK"/>
1106 \end{lstlisting}
1107
1108 \begin{lstlisting}[language=XML]
1109 <INFO name="QUERY_STATUS" value="OK">Successful query</INFO>
1110 \end{lstlisting}
1111
1112 \begin{lstlisting}[language=XML]
1113 <INFO name="QUERY_STATUS" value="ERROR">
1114 value out of range in POS=45,91
1115 </INFO>
1116 \end{lstlisting}
1117
1118 Additional \xmlel{RESOURCE} elements may be present, but the usage of any such elements
1119 is not defined here. Concrete DAL service specifications may define additional
1120 resources (and the type attribute to describe them) and service implementers are
1121 also free to add their own.
1122
1123 \subsubsection{Overflow}
1124 \label{sec:response-overflow}
1125 If an overflow occurs (result exceeds MAXREC), the service must include an
1126 \xmlel{INFO}
1127 element in the \xmlel{RESOURCE} with \texttt{name="QUERY\_STATUS"} and the
1128 \texttt{value="OVERFLOW"}. If
1129 the initial \xmlel{INFO} element (above) specified the overflow, no further elements are
1130 needed, e.g.:
1131
1132 \begin{lstlisting}[language=XML]
1133 <RESOURCE type="results">
1134 <INFO name="QUERY_STATUS" value="OVERFLOW"/>
1135 ...
1136 <TABLE>...</TABLE>
1137 </RESOURCE>
1138 \end{lstlisting}
1139
1140 If the initial \xmlel{INFO} element specified a status of OK then the service must
1141 append an \xmlel{INFO} element for the overflow after the table, e.g.:
1142
1143 \begin{lstlisting}[language=XML]
1144 <RESOURCE type="results">
1145 <INFO name="QUERY_STATUS" value="OK"/>
1146 ...
1147 <TABLE>...</TABLE>
1148 <INFO name="QUERY_STATUS" value="OVERFLOW"/>
1149 </RESOURCE>
1150 \end{lstlisting}
1151
1152 In the above examples, the TABLE should have exactly MAXREC rows.
1153
1154 \subsubsection{Errors}
1155 If an error occurs, the service must include an \xmlel{INFO} element with
1156 \verb|name="QUERY\_STATUS"| and the \verb|value="ERROR"|. If the initial info element (above)
1157 specified the error, no further elements are needed, e.g.:
1158
1159 \begin{lstlisting}[language=XML]
1160 <RESOURCE type="results">
1161 <INFO name="QUERY_STATUS" value="ERROR"/>
1162 ...
1163 <TABLE>...</TABLE>
1164 </RESOURCE>
1165 \end{lstlisting}
1166
1167 If the initial \xmlel{INFO} element specified a status of OK then the service must
1168 append an \xmlel{INFO} element for the error after the table, e.g.:
1169
1170 \begin{lstlisting}[language=XML]
1171 <RESOURCE type="results">
1172 <INFO name="QUERY_STATUS" value="OK"/>
1173 ...
1174 <TABLE>...</TABLE>
1175 <INFO name="QUERY_STATUS" value="ERROR">
1176 unexpected IO error while converting something
1177 </INFO>
1178 </RESOURCE>
1179 \end{lstlisting}
1180
1181 The use of trailing \xmlel{INFO} element allows a service to stream output and still
1182 report overflows or errors to the client. The content of these trailing INFO
1183 elements is optional and intended for users; client software should not depend
1184 on it.
1185
1186 \subsubsection{Additional Information}
1187 Additional \xmlel{INFO} elements may be provided, e.g., to echo the input parameters
1188 back to the client in the query response (a useful feature for debugging or to
1189 self-document the query response), but clients should not depend on these. For
1190 example:
1191
1192 \begin{lstlisting}[language=XML]
1193 <RESOURCE type="results">
1194 ...
1195 <INFO name="standardID" value="ivo://ivoa.net/TAP"/>
1196 <INFO name="standardVersion" value="1.0"/>
1197 ...
1198 </RESOURCE>
1199 \end{lstlisting}
1200
1201 The following names for \xmlel{INFO} elements should be used if applicable, but this
1202 list is not definitive.
1203
1204 \begin{tabular}{l p{8cm}}
1205 \sptablerule
1206 \textbf{Info Name}&\textbf{Value Interpretation}\\
1207 \sptablerule
1208 standardID & IVOA standardID for the service specification \\
1209 citation & Reference to a publication that can/should be referenced if the
1210 result is used \\
1211 \sptablerule
1212 \end{tabular}
1213
1214 For citations, the \xmlel{INFO} element should also include a
1215 \xmlel{ucd} attribute with the
1216 value \emph{meta.bib} (if the value is a free-text reference) or
1217 \emph{meta.bib.bibcode} (if
1218 the value is a bibcode). If other \xmlel{meta.bib} UCDs are added to the vocabulary in
1219 future, they may also be used to describe the value.
1220
1221 \appendix
1222
1223 \section{Changes}
1224
1225 \subsection{WC-DALI-1.1-20160415}
1226
1227 \begin{itemize}
1228 \item Removed introductory language on including capability-propertied elements in
1229 examples.
1230 \item Expanded section on intervals to allow use of all integer and floating point datatypes
1231 supported by VOTable; only floating point intervals support open-ended intervals.
1232 \item Expanded section on geomery to allow use of datatype="float" in addition to double.
1233 \item Removed restrictions on the resource name and location for VOSI-availability resource.
1234 \item Removed restrictions on resource name for VOSI-tables resources.
1235 \item Fixed the timestamp format specification to correctly specify optional parts.
1236 \item Added reference to RFC2616 and minimised discussion of HTTP headers.
1237 \end{itemize}
1238
1239 \subsection{WD-DALI-1.1-20151027}
1240
1241 Removed the requirement that the REQUEST must be a standard parameter. It is
1242 now recommended if a service capability supports more than one mode or
1243 operation. Removed VERSION parameter following experiences with TAP-1.1
1244 prototypes.
1245
1246 Re-organised the section on literal values and clarified that these rules
1247 are intended to make input (parameters and other input docs) and output
1248 (response documnets like VOTable) of services consistent. Added specification
1249 of interval, point, circle, and polygon literal values and specified VOTable
1250 xtype values for serialising such values in VOTable. Added VOTable serialisation
1251 and xtype for timestamp values. (Needed by SIA-2.0 and TAP-1.1)
1252
1253 Added bibtex cross-references.
1254
1255 \subsection{PR-DALI-1.0-20130919}
1256 The following changes are in response to additional RFC commands and during the
1257 TCG review.
1258
1259 New architecture diagram and minor editorial changes to improve document.
1260
1261 Clarified RESPONSEFORMAT text to allow services to append mimetype parameters if
1262 the client did not specify them.
1263
1264 Relaxed the VERSION parameter so services should default to latest (instead of
1265 must) and to not differentiate between REC and pre-REC status.
1266
1267 Clarified the requirement for a VOTable RESOURCE with type="results" attribute
1268 so it is clear that this is the primary result and other RESOURCES may be
1269 present.
1270
1271 Clarified that HTTP-specific rules apply to RESTful web services and that
1272 although we describe such services here we do not preclude future use of other
1273 transport protocols.
1274
1275 \subsection{PR-DALI-1.0-20130521}
1276 The following changes are in response to comments from the RFC period.
1277
1278 Made editorial changes from the DALI wiki page that were missed during WG
1279 review.
1280
1281 Changed all cross-references to be readable text.
1282
1283 Replaced example curl output from a POST with explanatory text.
1284
1285 POST of job parameters directly to job: restricted to creation and /parameters
1286 resource
1287
1288 Changed number of DALI-async and DALI-sync resources to zero or more.
1289
1290 Clarified that job parameters are the same if the type of job is the same, but
1291 services can have different types of jobs (and hence different parameters) on
1292 different job-list resources.
1293
1294 Fixed text forbidding any other vocab attributes in DALI-examples document.
1295
1296 Replace http-action and base-url with something or add sync vs async: replaced
1297 with capability property
1298
1299 Preventing loops with continuation in examples: removed.
1300
1301 Clarified that VOSI-capabilities does not require a registry extension schema
1302 and use of xsi:type.
1303
1304 Explicitly require that if VOSI-tables is not implemented, the service responds
1305 with a 404.
1306
1307 Clarified the purpose of requiring the service to use client-specified
1308 RESPONSEFORMAT as the Content-Type of the response.
1309
1310 Attempted to clarify the acceptable use of status codes for errors.
1311
1312 Removed single-table restriction from votable usage.
1313
1314 Clarified interpretation of dates and times as UTC timescale by default but
1315 permitting specific metadata to be specified.
1316
1317 Removed formatting of example links so they are not real hyperlinks in output
1318 documents.
1319
1320 Clarified that services can enforce a smaller limit than a requested MAXREC.
1321
1322 Removed text refering to IVOA notes on STC and Photometric metadata; added more
1323 general text that services should include additional metadata once standards for
1324 such are in place.
1325
1326 Explain the table at start of section 2.
1327
1328 Clarify requests that effect UWS job phase in DALI-async.
1329
1330 Removed malformed http post example from DALI-async section.
1331
1332 Remove reference to SGML specifically, but mention HTML5 as a poor choice for
1333 DALI-examples.
1334
1335 Add reference to RFC2616 in the RESPONSEFORMAT section since it talks about
1336 mimetypes.
1337
1338 Clarified text about setting job parameters and banned posting parameters
1339 directly to the job URL.
1340
1341 Replaced the base-url and http-action properties with a single capability
1342 property in DAL-examples. Changed the vocab identifier to be the IVOID for DALI
1343 with fragment indicating the DALI-examples section of the document.
1344
1345 \subsection{WD-DALI-1.0-20130212}
1346 Simplified DALI-examples to conform to RDFa-1.1 Lite in usage of attributes.
1347
1348 \bibliography{ivoatex/ivoabib}
1349
1350
1351 \end{document}

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26