/[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 3924 - (show annotations)
Thu Mar 30 15:16:34 2017 UTC (4 years, 4 months ago) by msdemlei
File MIME type: application/x-tex
File size: 60723 byte(s)
Minor quote-related fixes

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

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