/[volute]/trunk/projects/registry/VODataService/VODataService.tex
ViewVC logotype

Contents of /trunk/projects/registry/VODataService/VODataService.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5951 - (show annotations)
Mon May 10 06:51:54 2021 UTC (6 weeks, 1 day ago) by msdemlei
File MIME type: application/x-tex
File size: 106699 byte(s)
Fixing a second verbal uniqueness requirement on unique names in tablesets.

1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
3 % widen up the display a bit so that 75 column listings still fit on
4 % the page
5 \usepackage[width=14cm,left=4cm]{geometry}
6 \usepackage{listings}
7 \lstloadlanguages{XML}
8 \lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False}
9 \usepackage{amsmath}
10
11 \iftth
12 \newcommand{\tapschema}{TAP\_SCHE\-MA}
13 \hyphenation{TAP\_SCHEMA}
14 \hyphenation{\tapschema}
15 \newcommand{\tapupload}{TAP\_UPLOAD}
16 \else
17 \newcommand{\tapschema}{\mbox{%
18 TAP\discretionary{-}{}{\kern-2pt\_}SCHEMA}}
19 \newcommand{\tapupload}{%
20 TAP\discretionary{-}{}{\kern-2pt\_}UPLOAD}
21 \fi
22
23 \title{VODataService: A VOResource Schema Extension for Describing
24 Collections and Services}
25
26 \ivoagroup{Registry}
27
28 \author[http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante]{Raymond Plante}
29 \author[http://www.ivoa.net/twiki/bin/view/IVOA/MarkusDemleitner]{Markus Demleitner}
30 \author[http://www.ivoa.net/twiki/bin/view/IVOA/AurelienStebe]{Aurélien Stébé}
31 \author[http://www.ivoa.net/twiki/bin/view/IVOA/KevinBenson]{Kevin Benson}
32 \author[http://www.ivoa.net/twiki/bin/view/IVOA/PatrickDowler]{Patrick Dowler}
33 \author[http://www.ivoa.net/twiki/bin/view/IVOA/MatthewGraham]{Matthew Graham}
34 \author[http://www.ivoa.net/twiki/bin/view/IVOA/GretchenGreene]{Gretchen Greene}
35 \author[http://www.ivoa.net/twiki/bin/view/IVOA/PaulHarrison]{Paul Harrison}
36 \author[http://www.ivoa.net/twiki/bin/view/IVOA/GerardLemson]{Gerard Lemson}
37 \author[http://www.ivoa.net/twiki/bin/view/IVOA/TonyLinde]{Tony Linde}
38 \author[http://www.ivoa.net/twiki/bin/view/IVOA/GuyRixon]{Guy Rixon}
39
40 \editor{Markus Demleitner}
41 \editor{Ray Plante}
42
43 \previousversion[https://ivoa.net/documents/VODataService/20190715/PR-VODataService-1.2-20190715.html]{PR-2019-07-15}
44 \previousversion[https://ivoa.net/documents/VODataService/20181026/]{WD-2018-10-26}
45 \previousversion[http://www.ivoa.net/Documents/VODataService/20101202]{REC
46 1.1}
47
48 \begin{document}
49 \begin{abstract}
50 VODataService refers to an XML encoding standard for a specialized
51 extension of the IVOA Resource Metadata that is useful for describing
52 data collections and the services that access them. It is defined as
53 an extension of the core resource metadata encoding standard known as
54 VOResource \citep{2018ivoa.spec.0625P} using XML Schema.
55 The specialized resource types defined by the VODataService schema
56 allow one to describe how the data underlying the resource cover the
57 sky and the frequency and time axes.
58 VODataService also enables detailed
59 descriptions of tables that includes information useful to the
60 discovery of tabular data. It is intended that the VODataService data
61 types will be particularly useful in describing services that support
62 standard IVOA service protocols.
63 \end{abstract}
64
65 \section*{Acknowledgments}
66
67 Versions 1.0 and 1.1 of this document have been developed with support from the
68 National Science Foundation's
69 Information Technology Research Program under Cooperative Agreement
70 AST0122449 with The Johns Hopkins University, from the
71 UK Particle Physics and Astronomy
72 Research Council (PPARC), from the European Commission's (EC)
73 Sixth
74 Framework Programme via the
75 Optical Infrared Coordination Network (OPTICON), and from EC's
76 Seventh Framework Programme
77 via its
78 eInfrastructure Science Repositories initiative.
79
80 Version 1.2 of this document was developed in part with support from the
81 German federal ministry for research and education's e-inf-astro project (BMBF
82 FKZ 05A17VH2).
83
84
85 \section*{Conformance-related definitions}
86
87 The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
88 ``OPTIONAL'' (in upper or lower case) used in this document are to be
89 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
90
91 The \emph{Virtual Observatory (VO)} is a
92 general term for a collection of federated resources that can be used
93 to conduct astronomical research, education, and outreach.
94 The \href{http://www.ivoa.net}{International
95 Virtual Observatory Alliance (IVOA)} is a global
96 collaboration of separately funded projects to develop standards and
97 infrastructure that enable VO applications.
98
99
100 \section*{Syntax Notation Using XML Schema}
101
102 The eXtensible Markup Language, or XML, is a document syntax for marking
103 textual information with named tags and is defined by \citet{std:XML}.
104 The set of XML tag names and the syntax
105 rules for their use is referred to as the document schema. One way to
106 formally define a schema for XML documents is using the W3C standard
107 known as XML Schema \citep{std:XSD}.
108
109 The XML Schemas of VODataService as well as VOResource and its other
110 extensions are
111 available from the IVOA schema
112 repository\footnote{\url{http://www.ivoa.net/xml}} at any time.
113 Parts of the schema appear within the main sections of this document;
114 however, documentation nodes have been left out for the sake of brevity.
115 Where the content of the pieces of schema embedded in this text
116 diverges from the schema document in the IVOA document
117 repository, the version in the schema repository is authoritative.
118
119 References to specific elements and types defined in the VOResource
120 schema include the namespace prefix \xmlel{vr} as in
121 \xmlel{vr:Resource} (a type defined in the VOResource schema).
122
123 \section{Introduction}
124
125 The VOResource standard \citep{2018ivoa.spec.0625P} provides a means of
126 encoding resource metadata as defined by DataCite \citep{std:DataCite40}
127 and the VO-specific IVOA Resource Metadata \citep{2007ivoa.spec.0302H} in XML.
128 VOResource uses XML Schema \citep{std:XSD} to define
129 most of the XML syntax rules (while a few of the syntax rules are
130 outside the scope of Schema). VOResource also describes mechanisms
131 for creating extensions to the core VOResource metadata. This allows
132 for the standardization of new metadata for describing specialized
133 kinds of resources in a modular way without deprecating the core
134 schema or other extensions.
135
136 This document defines one such extension referred to as VODataService.
137 It provides types to define data services, their underlying tabular
138 structures, their service interfaces, and the location of the data
139 served in space, time, and energy.
140
141 The remainder of the document introduces the use cases addressed by this
142 specification, then provides a high-level overview over the concepts and
143 usage patterns in sect.~\ref{sect:model} and finally discusses the
144 concrete classes in sect.~\ref{sect:metadata}.
145
146
147 \subsection{The Role in the IVOA Architecture}
148
149 \begin{figure}
150 \centering
151 \includegraphics[width=0.9\textwidth]{role_diagram.pdf}
152 \caption{Architecture diagram for VODataService}
153 \label{fig:archdiag}
154 \end{figure}
155
156 Fig.~\ref{fig:archdiag} shows the role VODataService plays within the
157 IVOA Architecture \citep{2010ivoa.rept.1123A}.
158
159 VODataService directly depends on the following other VO standards
160 (unless specified otherwise, the dependency is on the major version of
161 the cited standard rather than on the exact version):
162
163 \begin{description}
164 \item[VOResource, v1.1 \citep{2018ivoa.spec.0625P}] VOResource gives
165 the fundamental types and structures extended here.
166 \item[STC, v1.33 \citep{2007ivoa.spec.1030R}] The deprecated mechanism
167 for declaring coverage through STCResourceProfile still uses concepts
168 from version 1 of the IVOA data model for Space-Time Coordinates. The
169 updated mechanism has no such dependence any more.
170 \end{description}
171
172 VODataService is closely related to the following other VO standards:
173
174 \begin{description}
175 \item[VOSI, v1.1 \citep{2017ivoa.spec.0524G}] VODataService defines the
176 schema for the responses on the table metadata endpoint. It also
177 defines the ParamHTTP interface type currently used in the capabilities of most
178 standard protocols.
179 \item[RegTAP, v1.1 \citep{2019ivoa.spec.1011D}] RegTAP maps the concepts
180 defined here into a relational structure. In that sense it is the
181 user interface to what is specified here. RegTAP will need an update
182 to support the space-time constraints added here.
183 \item[MOC, v1.1 \citep{2019ivoa.spec.1007F}] Multi-Order coverage maps
184 are used by VODataService to communicate spatial coverage.
185 \end{description}
186
187 \subsection{Purpose}
188
189
190 The purpose of this extension is to define common XML Schema
191 types -- in particular new resource types -- that are useful for describing
192 data collections and services that access data. One aspect of such a
193 description is the resource's \emph{coverage}: the parts of the
194 sky with which the data is associated and the time and frequency ranges that
195 were observed or modeled to create the data. Another important aspect
196 is the detailed metadata for tables underlying the resource, including
197 names, types, UCDs
198 \citep{2005ivoa.spec.1231D}, units,
199 and textual descriptions for the columns making them up.
200
201 Resource records using VODataService types are commonly used to register
202 services that support standard IVOA data access layer protocols such
203 as Simple Image Access \citep{2015ivoa.spec.1223D} and Simple Cone Search
204 \citep{2008ivoa.specQ0222P}. As of October 2018, there are more than
205 20000~resources of type \xmlel{vs:CatalogService} in the VO Registry.
206
207 While other VOResource extensions
208 define the protocol-specific metadata (encapsulated as a standard
209 \emph{capability} from VOResource), the general service
210 resource description shares the common data concepts such as
211 coverage and tabular data. Note, however, that a service described
212 using the VODataService schema need not support any standard
213 protocols. With the VODataService extension schema plus the core
214 VOResource schema, it is possible to describe a custom service
215 interface that accesses data.
216
217
218
219 As a legal extension of VOResource, the use
220 of VODataService is subject to the rules and recommendations for XML
221 \citep{std:XML}, XML Schema \citep{std:XSD},
222 and VOResource itself.
223
224 \subsection{Additional Use Cases for Version 1.2}
225
226 In the following, we collect use cases that guided the development of
227 VODataService to its version 1.2. We do not formally derive
228 requirements from them but briefly note which new features enable or
229 facilitate the specific use case.
230
231 A few of the changes in version 1.2 are necessary for consistency with other standards
232 such as TAP (extendedType interpretation, requirement to use ADQL
233 delimited identifier literals in names where appropriate) or VOTable
234 (arraysize interpretation). These were obviously not guided by specific
235 use cases.
236
237
238 \paragraph{What services have data for the Crab nebula covering the
239 H$\boldsymbol\alpha$
240 line taken in the second half of 2015?} In version 1.1, this use case
241 would have been covered by the \xmlel{stc:STCResourceProfile} type,
242 which, however, was never properly standardised or widely adopted. In the current
243 version, the \xmlel{spatial}, \xmlel{spectral}, and \xmlel{temporal}
244 children of \xmlel{coverage} enable discovery by coverage on the various
245 axes. It is worth noting that the spectral coverage is for the solar
246 system barycenter, so this use case does \emph{not} immediately enable
247 the discovery of, say, H$\alpha$ images of remote galaxies. Redshift
248 correction has to be applied by the client based on knowledge about the
249 object(s) investigated. At the time of writing, coverage also does not
250 directly address non-celestial reference systems, although in particular
251 planetary surfaces are considered in scope, and the coverage element's
252 \xmlel{@frame} attribute is defined to ensure non-ICRS coverages can
253 safely be declared as the need arises.
254
255 \paragraph{Find all ObsCore services publishing data taken at the
256 Telescope X.} This use case could be satisfied in version 1.1 through
257 the use of \xmlel{vs:DataCollection} records and relationships to the
258 respective TAP services. However, this scheme led to error-prone query
259 patterns, and few such data collections were actually registered; see
260 the IVOA Note on discovering data collections \citep{2019ivoa.rept.0520D} for
261 details. To better support the scheme proposed there, version 1.2 adds
262 the \xmlel{vs:DataResource} and \xmlel{vs:CatalogResource} types
263 that identify a resource as data-like but
264 permits the addition of various capabilities to the record (which
265 \xmlel{vs:DataCollection} did not). An analogous use case would be
266 ``Find all TAP services publishing tables from Gaia DR2''.
267
268 \paragraph{Find a large-scale survey of sources between 20 and 40 GHz.}
269 While the spectral constraint is easily satisfied by the new coverage
270 children, the ``large-scale'' part is much harder to operationalize.
271 However, the plain table size often is a useful proxy in such discovery
272 problems. The new \xmlel{nrows} child of \xmlel{vs:Table} communicates
273 it.
274
275
276 \subsection{Additional Use Cases for Future Versions}
277
278 The following use cases were originally envisioned for VODataService
279 1.2, but were postponed because building multiply implemented solutions
280 for them seemed likely to unnecessarily delay the standardisation of, in
281 particular, the STC part of the present document. They will likely be
282 addressed by future versions of VODataService.
283
284 \paragraph{Find a resource that has sources in M51 down to 27 mag in V.}
285 The constraint about finding a resource that has V magnitudes for M51 is
286 expressible using spatial coverage and the column's UCDs. To express
287 something like ``down to $27^{\rm m}$'' one would at least need
288 VOTable-style \xmlel{VALUES} children for columns; however, metadata
289 sufficient to address the next use case would certainly be sufficient
290 here as well.
291
292 \paragraph{Plan a cross-service query.} Systems like OGSA-DAI
293 \citep{2011ASPC..442..579H} perform orchestration of SQL-like queries
294 between multiple services automatically, in particular cross-service
295 JOINs. In order to work efficiently, such services need column
296 statistics like histograms and the percentage of NULL values.
297
298 \paragraph{Find services serving time series.} In the current registry
299 model, users looking for spectra would select SSAP services. With the
300 growing adoption of ObsCore (and a growing number of services abusing
301 SSAP to serve time series), the model of selecting data types by
302 constraining the service protocol no longer works; in the ObsCore
303 example, clients now have to query all services and constrain the
304 \verb|dataproduct_type| column. However, for dataset types not overly
305 common, well more than 90\% of the services could be excluded without
306 sending a query there based on a declaration of dataset types available
307 in the Registry.
308
309 \paragraph{Facilitate discovery of full DALI services.} The issue here
310 is that DALI forsees synchronous and asynchronous endpoints as the
311 standard case for many protocols -- it already is standard for TAP.
312 Also, several auxiliary endpoints (mostly defined in VOSI) are declared as
313 separate capabilities and need to be matched with the functional
314 endpoints. This matching is becoming a problem when multiple
315 authentication schemes or mirror sites necessitate multiple sync/async
316 pairs. A longer treatment of this problem has been published while this
317 document was in WD \citep{note:caproles}, but at the time of writing the
318 process of finding consensus has just begun, so again a normative
319 solution has to be deferred to a later version of this standard.
320
321
322
323 \section{The VODataService Data Model}
324 \label{sect:model}
325
326
327 The VODataService extension in general enables the description of two
328 types of resources: Services that access data on the one side, and data
329 being accessed through services on the other.
330
331 For simple services just publishing a simple resource -- still a fairly
332 common pattern -- the metadata of the data published can be folded into
333 the service record.
334 Here is an example of such a record (abbreviated for the
335 purposes of illustration) that describes a service from the NASA
336 Extragalactic Database (NED) that provides measured redshifts for a
337 given object.
338
339
340 \lstinputlisting[language=XML,basicstyle=\footnotesize,numbers=left]{ipac-resource.xml}
341
342 This example illustrates some of the features of the VODataService
343 extension:
344
345 \begin{enumerate}
346 \item The specific type of resource indicated by
347 the value of the \xmlel{xsi:type} attribute; in this case
348 \xmlel{vs:CatalogService} indicates that this is
349 describing a service that accesses tabular data (line 1).
350 \item The extra namespace declaration for
351 VODataService metadata with the canonical prefix (line 5).
352 \item The location of the VOResource-related schema
353 documents used by this description (line 7ff.)
354 \item The core VOResource metadata (line 12ff.)
355 \item An interface described by the
356 VODataService type \xmlel{vs:ParamHTTP}; this
357 type can indicate input arguments the service supports (line
358 40ff.)
359 \item A description of the
360 coverage, including quantitative coverage
361 plus waveband keywords (line 62ff.)
362 \item A description of the table that is returned
363 by the service (line 73ff.)
364 \end{enumerate}
365
366 \subsection{The Schema Namespace and Location}
367
368
369 The namespace associated with VODataService extensions is
370 $$\mbox{\texttt{http://www.ivoa.net/xml/VODataService/v1.1}}.$$
371 As required by the IVOA schema versioning policies
372 \citep{2018ivoa.spec.0529H}, this namespace is identical to the one
373 associated with version 1.1 of this document. It is regrettable that a
374 misleading minor version is present in the namespace URI, but dropping
375 it would break existing software for creating and processing
376 VODataService instance documents. Hence, the namespace URI ending in
377 \verb|1.1| is also used for schema versions 1.2, 1.3, and so forth.
378
379 Resolving the VODataService namespace URI will redirect to a schema
380 document having the actual version number (for the schema associated
381 with this document version, this will end in VODataService-1.2.xsd).
382 Following the schema versioning policies, the minor version will be
383 declared in the \xmlel{version} attribute of this file's root element.
384 This information should not in general be used in production software;
385 all versions with the above schema URI are compatible with each
386 other in the sense defined in the IVOA schema versioning policies.
387
388 Authors of VOResource instance documents may choose to
389 provide a location for the VOResource XML Schema document and its
390 extensions using the
391 \xmlel{xsi:schemaLocation} attribute. While authors are free to
392 choose a location (as long as it resolves to the schema document), this
393 specification
394 recommends using the VODataService namespace URI as its location URL
395 (as illustrated in the example above), as in
396 \begin{verbatim}
397 xsi:schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1
398 http://www.ivoa.net/xml/VODataService/v1.1"
399 \end{verbatim}
400
401 The canonical prefix for VODataService is \xmlel{vs}; this means, in
402 particular, that in non-XML contexts (e.g., relational mappings
403 like RegTAP) the VODataService types \emph{must} be qualified with
404 vs:.
405
406 As recommended by the VOResource standard, the
407 VODataService schema sets \xmlel{element\-Form\-Default} to \emph{unqualified}.
408 This means that element names defined
409 in this schema may not be used with a namespace prefix.
410 The only place the namespace prefix must be used is the
411 type names given as the value of an
412 \xmlel{xsi:type} attribute.
413
414
415 \subsection{Summary of Metadata Concepts}
416 \label{sect:summ}
417
418
419 VODataService defines several resource types and some auxiliary classes
420 necessary to describe resources of these new types.
421
422 \subsubsection{Auxiliary Classes}
423
424 The VODataService type \xmlel{vs:Coverage} allows the declaration of
425 the physical coverage of a resource on the sky (or on spherical bodies),
426 in time, and in the energy of the messenger particle. In addition, the
427 element should contain a rough indication of the messenger type
428 (e.g., ``Optical''), and it can contain a link to a footprint endpoint and an
429 indication of the spatial resolution within a service.
430
431 VODataService has several classes for the declaration of the tabular
432 structure underlying a service; this can be the tables in a
433 TAP-accessible resource,
434 or it can relate to the data structure returned by the service. This
435 metadata is held in
436 \xmlel{vs:TableSet}-typed elements consisting
437 of one or more (possibly anonymous)
438 \xmlel{vs:TableSchema} instances. These have some very basic metadata
439 (name, title, description, utype) and otherwise contain \xmlel{vs:Table}
440 instances. These in turn have simple metadata, but mainly give column
441 metadata (including UCDs and units) in \xmlel{vs:TableParam}-typed
442 children. These are the basis for enabling discovery queries like
443 ``find all resources having redshifts and far infrared fluxes''.
444
445 Note that table and schema metadata is deliberately shallow. If the
446 main resource metadata is not enough to discover the table -- as is
447 fairly typical when a TAP service contains multiple unrelated tables --,
448 data providers should define separate records for them as described in
449 sect.~\ref{sect:discoverdata}.
450
451 VODataService further defines a specialized interface type
452 (inheriting from \xmlel{vr:Interface}) called
453 \xmlel{vs:ParamHTTP}. This type is used to describe
454 straightforward HTTP interfaces directly operating on
455 arguments encoded as
456 \emph{name=value} pairs. Such interface declarations can
457 enumerate a service's input arguments, which enables clients
458 to generate simple
459 user interfaces from VOSI capabilities responses.
460
461 To be able to express the types of table columns and service arguments
462 alike, VODataService defines several type systems. All of these are
463 basically just enumerations of type names, possibly with some additional
464 metadata like VOTable-style array sizes. In new resource records, only
465 \xmlel{vs:SimpleDataType} (for ParamHTTP parameters on non-DALI
466 interfaces) and
467 \xmlel{vs:VOTableType} (for table columns) should be used.
468
469 \subsubsection{VODataService Resource Classes}
470
471 \begin{figure}
472 \includegraphics{resclasses.pdf}
473 \caption{The four major resource classes in VODataService and their
474 derivation tree}
475 \label{fig:rescls}
476 \end{figure}
477
478 While no common VO service discovery pattern relies on the XSD type of the
479 resource,\footnote{Of course, in non-service discovery (e.g., authorities
480 or standards), resource types are important.} resource
481 record authors should
482 nevertheless choose appropriate types for their resources. At the
483 very least, this helps Registry maintenance.
484
485 VODataService provides four major resource classes; their derivation
486 tree is shown in Fig.~\ref{fig:rescls}. The vertical distinction in
487 that figure reflects whether a resource has an associated tableset
488 (DataX vs.~CatalogX); you would typically use the DataX types when a
489 resource does not naturally admit a relational structure. The classical
490 example for this would be a collection of files on an FTP server. CatalogX,
491 on the other hand, has an associated tableset. That does not mean that
492 it is limited to what is conventionally thought of as a ``catalogue'',
493 i.e., a table of data on astronomical objects. On the
494 contrary, CatalogX should also be used for collections of images,
495 spectra, time series, etc, as long as their metadata is sufficiently
496 structured. That a data collection is published through the standard
497 IVOA discovery protocols (ObsCore,
498 SIAP, SSAP) certainly is a strong indication that this requirement is
499 satisfied.
500
501 The horizontal distinction (XResource vs.~XService) is somewhat more
502 subtle and will be discussed in sect.~\ref{sect:discoverdata}.
503
504 Two further resource classes defined VODataService 1.1,
505 \xmlel{vs:DataCollection} and \xmlel{vs:StandardSTC},
506 are deprecated in version 1.2.
507 Resource record authors are requested to migrate or discard resource
508 records using these deprecated types. If all such records have
509 disappeared from the VO by version 1.3 of this specification, their
510 type declarations may be removed from the schema.
511
512 \subsubsection{Discovering Data Within Other Services}
513 \label{sect:discoverdata}
514
515 The content models of CatalogResource and CatalogService are identical.
516 To understand why the two classes are present nevertheless, a short
517 historical excursion is in order. A full treatment of this is found in
518 the IVOA Endorsed Note on discovering data collections within services
519 \citep{2019ivoa.rept.0520D}, hereafter referred to as DDC.
520
521 In the early VO, there was almost throughout a $1:1$ relationship between
522 data collections and services. For instance, a catalogue of variable
523 stars had a single cone search interface, and the spectra from a given
524 spectrograph had a single SSA interface. This is the model reflected by
525 the CatalogService class, and it was, by and large, sufficient for
526 IVOA's ``simple'' protocols (SCS, SIAP, SSAP, SLAP), although even these
527 protocols have facilities for multi-collection services.
528
529 With the advent of services very naturally publishing what clearly
530 are multiple different resources -- TAP, with its multiple tables, and
531 Obscore building on top of it are the prime examples --, this model
532 proved inadequate; furthermore, publishers increasingly offered data
533 through multiple interfaces: An object catalogue now quite typically is
534 published as both a cone search service and within a TAP service; an
535 image collection could have both SIAP and Obscore interfaces.
536
537 Thus, the relationship between data collections and services gradually
538 became $n:m$. With this came the realisation that two classes of
539 discovery need to be supported; for all-VO queries, validation, and the
540 like, an enumeration of all \emph{services} (``give me all SSAP
541 services\dots'') needs to be performed. For data discovery (``Where are
542 images from instrument X of object Y?''), a selection over all
543 \emph{collections} needs to be made.
544
545 The solution eventually adopted for these problems are auxiliary
546 capabilities as introduced in DDC. They provide stubs merely
547 identifying an access protocol -- at the same time identifying the
548 capability as an auxiliary one -- and access URLs, delegating all
549 further service metadata to a separate record, linked to the original
550 resource through an \emph{isServedBy} relationship.
551
552 Thus, CatalogService-typed records should be used
553
554 \begin{itemize}
555 \item when a service serves a single data collection, in which case the
556 metadata on the record describes the data collection (e.g., ``These are
557 observations of\dots'').
558 \item for a service serving multiple data collections, in which case the
559 metadata on the record describes the service (e.g., ``This is the TAP
560 service of\dots''').
561 \end{itemize}
562
563 CatalogResource-typed records should be used for resources that only
564 have auxiliary capabilities.
565
566 Here is a sketch of a resource record of a table within a TAP service::
567
568 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
569 <ri:Resource
570 xsi:type="vs:CatalogResource"
571 <title>Sample Table</title>
572 <identifier>ivo://example/sample</identifier>
573 <curation>...</curation>
574 <content> ...
575 <relationship>
576 <relationshipType>IsServedBy</relationshipType>
577 <relatedResource ivo-id="ivo://example/tap"
578 >Example TAP service</relatedResource>
579 </relationship>
580 </content>
581 <capability standardID="ivo://ivoa.net/std/TAP#aux">
582 <interface role="std" xsi:type="vs:ParamHTTP">
583 <accessURL use="base"
584 >http://example.org/svcs/tap</accessURL>
585 </interface>
586 </capability>
587 <coverage>...</coverage>
588 <tableset>
589 <schema>
590 <name>someschema</name>
591 <table>
592 <name>someschema.sample</name>...
593 ...
594 </table>
595 </schema>
596 </tableset>
597 </ri:Resource>
598 \end{lstlisting}
599
600 A complete example can be found in DDC.
601
602 Note that it is legal to add auxiliary capabilities to CatalogService
603 records as well. The classical example could be a cone search service
604 serving a single catalogue that is also queriable within a larger TAP
605 service.
606
607 Analogous considerations would apply to DataResource versus DataService,
608 although at this point no obvious use cases have been identified;
609 DataResource was included mainly for symmetry with CatalogResource.
610
611 \section{The VODataService Metadata}
612 \label{sect:metadata}
613
614
615 This section enumerates the types and elements defined in the
616 VODataService extension schema and describes their meaning.
617
618
619 \subsection{VODataService Resource Types}
620 \label{sect:resext}
621
622 \subsubsection{DataResource}
623 \label{sect:DataResource}
624
625 The \xmlel{vs:DataResource} resource type is used to describe a
626 resource containing generic astronomical data without a dominating
627 tabular structure. An example might be a largely unstructured archive
628 of various observations. Resources that have structured metadata tables
629 (like most VO services) or are tabular in nature (like usual
630 astronomical catalogues) should use \xmlel{vs:CatalogResource}.
631
632 The type is derived from \xmlel{vr:Service}, which means that instances
633 can have
634 capabilities. For \xmlel{vs:DataResource}, only auxiliary capabilities
635 (e.g., DataServices serving multiple DataResources) or plain capabilities
636 with \xmlel{vr:WebBrowser} interfaces should be given. Resources with a
637 primary access mode dedicated to the resource's data content should use
638 \xmlel{vs:DataService}-typed resources.
639
640 In addition to \xmlel{vr:Service}'s content, DataResource adds
641 elements for declaring the observing facilities and/or instruments used
642 to obtain the data, and it supports the declaration of
643 the physical coverage of data via the \xmlel{coverage}
644 element.
645
646 % GENERATED: !schemadoc VODataService-v1.2.xsd DataResource
647 \begin{generated}
648 \begingroup
649 \renewcommand*\descriptionlabel[1]{%
650 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:DataResource} Type Schema Documentation}
651
652 \noindent{\small
653 A resource publishing astronomical data.
654 \par}
655
656 \noindent{\small
657 This resource type should only be used if the resource has no
658 common underlying tabular schema (e.g., an inhomogeneous archive).
659 Use CatalogResource otherwise.
660 \par}
661
662 \vspace{1ex}\noindent\textbf{\xmlel{vs:DataResource} Type Schema Definition}
663
664 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
665 <xs:complexType name="DataResource" >
666 <xs:complexContent >
667 <xs:extension base="vr:Service" >
668 <xs:sequence >
669 <xs:element name="facility" type="vr:ResourceName" minOccurs="0"
670 maxOccurs="unbounded" />
671 <xs:element name="instrument" type="vr:ResourceName" minOccurs="0"
672 maxOccurs="unbounded" />
673 <xs:element name="coverage" type="vs:Coverage" minOccurs="0" />
674 </xs:sequence>
675 </xs:extension>
676 </xs:complexContent>
677 </xs:complexType>
678 \end{lstlisting}
679
680 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:DataResource} Extension Metadata Elements}
681
682 \begingroup\small\begin{bigdescription}\item[Element \xmlel{facility}]
683 \begin{description}
684 \item[Type] string with ID attribute: vr:ResourceName
685 \item[Meaning]
686 The observatory or facility used to collect the data
687 contained or managed by this resource.
688
689 \item[Occurrence] optional; multiple occurrences allowed.
690
691 \end{description}
692 \item[Element \xmlel{instrument}]
693 \begin{description}
694 \item[Type] string with ID attribute: vr:ResourceName
695 \item[Meaning]
696 The instrument used to collect the data contain or
697 managed by a resource.
698
699 \item[Occurrence] optional; multiple occurrences allowed.
700
701 \end{description}
702 \item[Element \xmlel{coverage}]
703 \begin{description}
704 \item[Type] composite: \xmlel{vs:Coverage}
705 \item[Meaning]
706 Extent of the content of the resource over space, time,
707 and frequency.
708
709 \item[Occurrence] optional
710
711 \end{description}
712
713
714 \end{bigdescription}\endgroup
715
716 \endgroup
717 \end{generated}
718
719 % /GENERATED
720
721 \subsubsection{DataService}
722
723 The \xmlel{vs:DataService} resource type has the same content model as
724 \xmlel{vs:DataResource}. It should be used instead of
725 \xmlel{vs:DataResource} when the resource's capabilties give
726 access to (essentially) only the resource's data, as for instance
727 ``ftp service for the XY instrument'', or for a service giving access
728 to multiple resources; in this latter case, the resource-level
729 metadata should pertain to the service itself rather than any specific
730 data collection served by it.
731
732 As with \xmlel{vs:CatalogResource}, instances SHOULD
733 declare the metadata of the table(s) underlying the service or
734 delivered by it in a \xmlel{tableset} element.
735
736 Whenever the service operates on clearly definable tabular
737 data, the resource should use the \xmlel{vs:CatalogService} resource type
738 in preference to \xmlel{vs:DataService}, and that tabular structure
739 should be given in a table set.
740
741 DataService's content model is exactly the one of
742 \xmlel{vs:DataResource}; please refer to sect.~\ref{sect:DataResource}
743 for the motivation of this duplication.
744
745
746
747
748 \subsubsection{CatalogResource}
749 \label{sect:CatalogResource}
750
751
752 The \xmlel{vs:CatalogResource} resource type is used to describe a
753 resource containing astronomical data or metadata in a set of one or
754 more tables. It extends \xmlel{vs:DataResource} and thus has metadata
755 on coverage and the facilities and instruments that produced the
756 resource. Additionally, \xmlel{vs:CatalogResource} instances SHOULD
757 declare of the metadata of the table(s) making up the data
758 \xmlel{tableset} element.
759
760 As with \xmlel{vs:DataResource}, this type should only be used if all
761 capabilities declared in the resource are either auxiliary or
762 nonstandard. This is typically the case for catalogues or data
763 collections within larger TAP, ObsTAP, or perhaps SIAP services. When
764 a service only publishes a single resource, use the
765 \xmlel{vs:CatalogService} type.
766
767
768 % GENERATED: !schemadoc VODataService-v1.2.xsd CatalogResource
769 \begin{generated}
770 \begingroup
771 \renewcommand*\descriptionlabel[1]{%
772 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:CatalogResource} Type Schema Documentation}
773
774 \noindent{\small
775 A resource giving astronomical data in tabular form.
776 \par}
777
778 \noindent{\small
779 While this includes classical astronomical catalogues,
780 this resource is also appropriate for collections of observations
781 or simulation results provided their metadata are available
782 in a sufficiently structured form (e.g., Obscore, SSAP, etc).
783 \par}
784
785 \vspace{1ex}\noindent\textbf{\xmlel{vs:CatalogResource} Type Schema Definition}
786
787 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
788 <xs:complexType name="CatalogResource" >
789 <xs:complexContent >
790 <xs:extension base="vs:DataResource" >
791 <xs:sequence >
792 <xs:element name="tableset" type="vs:TableSet" minOccurs="0" >
793 <xs:unique name="CatalogService-schemaName" >
794 <xs:selector xpath="schema" />
795 <xs:field xpath="name" />
796 </xs:unique>
797 <xs:unique name="CatalogService-tableName" >
798 <xs:selector xpath="schema/table" />
799 <xs:field xpath="name" />
800 </xs:unique>
801 </xs:element>
802 </xs:sequence>
803 </xs:extension>
804 </xs:complexContent>
805 </xs:complexType>
806 \end{lstlisting}
807
808 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:CatalogResource} Extension Metadata Elements}
809
810 \begingroup\small\begin{bigdescription}\item[Element \xmlel{tableset}]
811 \begin{description}
812 \item[Type] composite: \xmlel{vs:TableSet}
813 \item[Meaning]
814 A description of the tables that are accessible
815 through this service.
816
817 \item[Occurrence] optional
818 \item[Comment]
819 Each schema name and each table name must be
820 unique within this tableset.
821
822
823 \end{description}
824
825
826 \end{bigdescription}\endgroup
827
828 \endgroup
829 \end{generated}
830
831 % /GENERATED
832
833
834 \subsubsection{CatalogService}
835
836 The \xmlel{vs:CatalogService} resource type is used to describe a
837 service publishing astronomical data or metadata based on tabular
838 representations. Its relationship to \xmlel{vs:CatalogResource}
839 is as between \xmlel{vs:DataResource}
840 and \xmlel{vs:DataService}: Use \xmlel{vs:CatalogService} when either
841 the resource's capabilties are exclusive to the resource described by
842 the resource-level metadata (``SSAP service for the XY instrument'') or
843 if the service publishes multiple other CatalogResources; in that latter
844 case, again, the resource-level metadata should not refer to any
845 specific data collection contained.
846
847 This is the type that should be used for one-resource VO
848 services.
849
850 CatalogService's content model is exactly the one of
851 \xmlel{vs:CatalogResource}; please refer to sect.~\ref{sect:CatalogResource}
852 for the motivation of this duplication.
853
854 \subsubsection{DataCollection}
855 \label{sect:datacollection}
856
857 The \xmlel{vs:DataCollection} type is deprecated and should no longer be
858 used in new resource records. It was used in version 1.1 to define
859 simple collections of data, much like \xmlel{vs:CatalogResource} in the
860 current version. It did not admit capabilities, though, and since the
861 addition of capabilities would essentially have created a CatalogService
862 clone with a different child sequence, it was decided to abandon rather
863 than repair it.
864
865 Existing \xmlel{vs:DataCollection}-typed
866 records should be migrated to records of type \xmlel{vs:DataResource} or
867 \xmlel{vs:CatalogResource} as appropriate. If \xmlel{accessURL}
868 children are present in the
869 \xmlel{vs:DataCollection}\/s,
870 they can be replaced with a plain capability with a
871 \xmlel{vr:WebBrowser}-typed interface.
872
873 This type may be removed from the schema when all resource records using
874 it have vanished from the VO Registry.
875
876 \subsubsection{StandardSTC}
877
878 The \xmlel{vs:StandardSTC} type is deprecated and should no longer be
879 used in new resource records. Since the XML serialisation of the STC 1
880 data model was never promoted to an IVOA recommendation, there also is
881 no properly standardised way of creating such records. Since no such
882 records ever existed in the Registry, this type will probably be removed
883 from the schema in version 1.3 of this specification.
884
885
886
887 \subsection{Coverage in Space, Time, and Spectrum}
888 \label{sect:cover}
889
890 The \xmlel{vs:Coverage} type summarily describes how the data served is
891 distributed on the
892 sky, in energy, and in time.
893
894 In addition, there is the \xmlel{waveband} element that originally
895 contained a qualitative indication of the location of the resource's
896 coverage on the electromagnetic spectrum. As more resources cover
897 non-electromagnetic messengers, the element's meaning has somewhat
898 shifted, and it now admits values from an extendable vocabulary of
899 messengers\footnote{\url{http://www.ivoa.net/rdf/messenger}} that, for
900 instance, includes Neutrinos.
901
902 Historically, the quantitative footprints were expected to be given in
903 the element of type \xmlel{stc:STCResourceProfile}. As discussed in
904 \citet{note:regstc}, this expectation turned out to be erroneous,
905 and the underlying standard, STC-X \citep{note:stcx}, never proceeded to become
906 a recommendation. Hence, this version of VODataService deprecates the
907 use of \xmlel{STCResourceProfile}.
908
909 Instead, resource record authors are strongly encouraged to provide
910 coverage information in the \xmlel{spatial}, \xmlel{spectral}, and
911 \xmlel{temporal} children of \xmlel{coverage}.
912
913 Spatial coverage is conveyed as a MOC. To enable easy embedding into
914 resource records written in VOResource (i.e., XML),
915 VODataService uses the string serialisation defined in section 2.3.2 of
916 \citet{2019ivoa.spec.1007F}.
917
918 By default, the MOCs are to be interpreted in the ICRS. Future
919 extensions to non-celestial frames (e.g., on planet
920 surfaces) will use the \xmlel{frame} attribute.
921 However, the only celestial reference system allowed is
922 ICRS. If a resource's native coordinates are given for another frame (e.g.,
923 Galactic or FK4 for some equinox), it is the resource record author's
924 responsibility to convert the spatial coverage into the ICRS.
925
926 An important characteristic of MOCs is the order of the smallest scale
927 (the ``MOC resolution''). Higher orders yield more faithful
928 representations of the actual coverage, but also lead to a possibly
929 significant increase of the size of the serialized MOC. We suggest a
930 ``typical resolution'' of the Registry of about a degree (i.e., MOC
931 order 6), but resources are free to choose a higher maximum orders if
932 appropriate and the resource record size remains reasonable.
933
934 Resources that need to communicate high-resolution spatial coverage,
935 perhaps for some non-discovery use case, can use the \xmlel{footprint}
936 element with its \xmlel{ivo-id} attribute set to
937 \nolinkurl{ivo://ivoa.net/std/moc} to declare a URL giving a
938 footprint in one of the approved MOC serialisations and of arbitrary
939 level and size.
940
941 Time and spectral coverage are modeled as unions of simple
942 intervals over real numbers; the serialisation here is a space-separated
943 pair of floating point numbers as governed by the DALI \emph{interval}
944 xtype.
945
946 Times are given in Barycentric Dynamical Time (TDB) at the solar system
947 barycenter. They must be specified as Modified Julian Dates. Since
948 discovery use cases in which high-precision times are required are not
949 forseen, resource record authors are encouraged to pad their actual
950 temporal coverage such that differences in time scales (of the order of
951 10s of seconds) or reference positions (of the order of minutes between
952 ground-based observatories and the barycenter) do not matter. In other
953 words, the temporal resolution of the Registry at this point should be
954 assumed to be of order 10 minutes.
955
956 Deviating from common VO practice (which currently fairly consistently
957 uses wavelengths of electromagnetic waves in vacuum), spectral limits are
958 given in Joules of messenger energy. This is intended to allow seamless
959 integration of non-electromagnetic messengers. The reference position
960 for the spectral axis is the solar system barycenter. Again, discovery
961 use cases on a level where the difference between reference frames of
962 ground-based observatories versus the solar system barycenter matters
963 are not forseen, and resource record authors are advised to pad their
964 intervals on that level.
965
966 % GENERATED: !schemadoc VODataService-v1.2.xsd Coverage
967 \begin{generated}
968 \begingroup
969 \renewcommand*\descriptionlabel[1]{%
970 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:Coverage} Type Schema Documentation}
971
972 \noindent{\small
973 A description of how a resource's contents or behavior maps
974 to the sky, to time, and to frequency space, including
975 coverage and resolution.
976 \par}
977
978 \vspace{1ex}\noindent\textbf{\xmlel{vs:Coverage} Type Schema Definition}
979
980 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
981 <xs:complexType name="Coverage" >
982 <xs:sequence >
983 <xs:element ref="stc:STCResourceProfile" minOccurs="0" />
984 <xs:element name="spatial" type="vs:SpatialCoverage" minOccurs="0" />
985 <xs:element name="temporal" type="vs:FloatInterval" minOccurs="0"
986 maxOccurs="unbounded" />
987 <xs:element name="spectral" type="vs:FloatInterval" minOccurs="0"
988 maxOccurs="unbounded" />
989 <xs:element name="footprint" type="vs:ServiceReference" minOccurs="0" />
990 <xs:element name="waveband" type="xs:token" minOccurs="0"
991 maxOccurs="unbounded" />
992 <xs:element name="regionOfRegard" type="xs:float" minOccurs="0" />
993 </xs:sequence>
994 </xs:complexType>
995 \end{lstlisting}
996
997 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:Coverage} Metadata Elements}
998
999 \begingroup\small\begin{bigdescription}\item[Element \xmlel{stc:STCResourceProfile}]
1000
1001 An STC 1.0 description of the location of the resource's
1002 data on the sky, in time, and in frequency space,
1003 including resolution. This is deprecated in favour
1004 of the separate spatial, temporal, and spectral elements.
1005
1006
1007 This element is imported from another schema. See
1008 there for details.\item[Element \xmlel{spatial}]
1009 \begin{description}
1010 \item[Type] a string with optional attributes
1011 \item[Meaning]
1012 An ASCII-serialized MOC defining the spatial coverage
1013 of the resource.
1014
1015 \item[Occurrence] optional
1016 \item[Comment]
1017 The MOC is to be understood in the ICRS reference frame
1018 unless a frame attribute is given.
1019 Resources should give the coverage at least to order 6
1020 (a resolution of about one degree). The order should be
1021 chosen so as to keep the resulting MOC smaller than a few
1022 dozens of kB. If desired, a more precise MOC can be provided
1023 on a dedicated endpoint declared in the footprint element.
1024
1025
1026 \end{description}
1027 \item[Element \xmlel{temporal}]
1028 \begin{description}
1029 \item[Type] string of the form: \emph{[+-]?([0-9]+$\backslash$.?[0-9]*|$\backslash$.[0-9]+)([eE][+-]?[0-9]+)? [+-]?([0-9]+$\backslash$.?[0-9]*|$\backslash$.[0-9]+)([eE][+-]?[0-9]+)?}
1030 \item[Meaning]
1031 A pair of lower, upper limits of a time interval
1032 for which the resource offers data.
1033
1034 \item[Occurrence] optional; multiple occurrences allowed.
1035
1036 \item[Comment]
1037 This is written as for VOTable tabledata (i.e.,
1038 whitespace-separated C-style floating point literals), as
1039 in “47847.2 51370.2”.
1040 The limits must be given as MJD. While they
1041 are not intended to be precise, they are to be understood
1042 in TDB for the solar system barycenter. The total coverage
1043 of the resource is the union of all such intervals.
1044
1045
1046 \end{description}
1047 \item[Element \xmlel{spectral}]
1048 \begin{description}
1049 \item[Type] string of the form: \emph{[+-]?([0-9]+$\backslash$.?[0-9]*|$\backslash$.[0-9]+)([eE][+-]?[0-9]+)? [+-]?([0-9]+$\backslash$.?[0-9]*|$\backslash$.[0-9]+)([eE][+-]?[0-9]+)?}
1050 \item[Meaning]
1051 A pair of lower, upper limits of a spectral interval
1052 for which the resource offers data.
1053
1054 \item[Occurrence] optional; multiple occurrences allowed.
1055
1056 \item[Comment]
1057 This is written as for VOTable tabledata (i.e.,
1058 whitespace-separated C-style floating point literals).
1059 The limits must be given in Joules of particle
1060 energies. While the limits are not intended
1061 to be precise, they are to be understood for the
1062 solar system barycenter.
1063
1064 \item[Comment]
1065 For instance, the Johnson V waveband (480 .. 730 nm)
1066 would be specified as “2.72e-19 4.14e-19”
1067
1068
1069 \end{description}
1070 \item[Element \xmlel{footprint}]
1071 \begin{description}
1072 \item[Type] a URI with optional attributes
1073 \item[Meaning]
1074 A reference to a footprint service for retrieving
1075 precise and up-to-date description of coverage.
1076
1077 \item[Occurrence] optional
1078 \item[Comment]
1079 The ivo-id attribute here refers to the standard in which
1080 the footprint is given. The only value defined by
1081 VODataService at this point is ivo://ivoa.net/std/moc,
1082 which indicates that retrieving the footprint URL will return
1083 a MOC (any IVOA-approved serialisation is legal). Note that
1084 the ivo-id attribute was intended to have a different
1085 function in VODataService 1.1. The current meaning is what
1086 implementors actually adopted.
1087
1088
1089 \end{description}
1090 \item[Element \xmlel{waveband}]
1091 \begin{description}
1092 \item[Type] string: \xmlel{xs:token}
1093 \item[Meaning]
1094 A name of a messenger that the resource is relevant for
1095 (e.g., was used in the measurements). Terms must
1096 be taken from the vocabulary at
1097 http://www.ivoa.net/rdf/messenger.
1098
1099 \item[Occurrence] optional; multiple occurrences allowed.
1100 \item[Comment]
1101 It is a bit unfortunate that the element is still called
1102 waveband when it is now also coverage non-electromagnetic
1103 messengers. It was deemed that this slight notional
1104 sloppiness is preferable to introducing new and
1105 deprecating old elements.
1106
1107
1108 \end{description}
1109 \item[Element \xmlel{regionOfRegard}]
1110 \begin{description}
1111 \item[Type] floating-point number: \xmlel{xs:float}
1112 \item[Meaning]
1113 A single numeric value representing the angle, given
1114 in decimal degrees, by which a positional query
1115 against this resource should be “blurred” in order
1116 to get an appropriate match.
1117
1118 \item[Occurrence] optional
1119 \item[Comment]
1120 In the case of image repositories, it might refer to
1121 a typical field-of-view size, or the primary beam
1122 size for radio aperture synthesis data. In the case
1123 of object catalogues RoR should normally be the
1124 largest of the typical size of the objects, the
1125 astrometric errors in the positions, or the
1126 resolution of the data.
1127
1128
1129 \end{description}
1130
1131
1132 \end{bigdescription}\endgroup
1133
1134 \endgroup
1135 \end{generated}
1136
1137 % /GENERATED
1138
1139 In order to avoid future ambiguity in the spatial coverage, we already
1140 add a \xmlel{frame} attribute to the \xmlel{spatial} element. In its
1141 absence, the MOC contained is for ICRS coordinates. Any value indicates
1142 non-celestial coordinates, where actual, interoperable values are not
1143 defined here.
1144
1145
1146 % GENERATED: !schemadoc VODataService-v1.2.xsd SpatialCoverage
1147 \begin{generated}
1148 \begingroup
1149 \renewcommand*\descriptionlabel[1]{%
1150 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:SpatialCoverage} Type Schema Documentation}
1151
1152 \noindent{\small
1153 A coverage on a sphere. By default, this refers to the
1154 celestial sphere in the ICRS frame. Non-celestial frames
1155 are indicated by non-NULL values of the frame attribute.
1156 \par}
1157
1158 \vspace{1ex}\noindent\textbf{\xmlel{vs:SpatialCoverage} Type Schema Definition}
1159
1160 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1161 <xs:complexType name="SpatialCoverage" >
1162 <xs:simpleContent >
1163 <xs:extension base="xs:token" >
1164 <xs:attribute name="frame" type="xs:token" />
1165 </xs:extension>
1166 </xs:simpleContent>
1167 </xs:complexType>
1168 \end{lstlisting}
1169
1170 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:SpatialCoverage} Attributes}
1171
1172 \begingroup\small\begin{bigdescription}
1173 \item[frame]
1174 \begin{description}
1175 \item[Type] string: \xmlel{xs:token}
1176 \item[Meaning]
1177 When present, the MOC is written in a non-celestial (e.g.,
1178 planetary) frame. Note that for celestial coverages,
1179 ICRS must be used.
1180
1181 \item[Occurrence] optional
1182 \item[Comment]
1183 VODataService 1.2 does not prescribe a vocabulary for
1184 what values are allowed here; an external standard. As
1185 long as no such vocabulary is agreed upon, the frame
1186 attribute should not be set.
1187
1188 \end{description}
1189
1190
1191 \end{bigdescription}\endgroup
1192
1193 \endgroup
1194 \end{generated}
1195
1196 % /GENERATED
1197
1198 \subsection{Tabular Data}
1199 \label{sect:table}
1200
1201
1202 The \xmlel{vs:TableSet} type can be used
1203 to describe a set of tables that are part of a single resource and can
1204 be considered functionally all located at a single site. While there is
1205 no expectation that the table set directly corresponds to the responses
1206 of tabular services,
1207 services should not include metadata for purely internal
1208 tables.
1209
1210
1211
1212 % GENERATED: !schemadoc VODataService-v1.2.xsd TableSet
1213 \begin{generated}
1214 \begingroup
1215 \renewcommand*\descriptionlabel[1]{%
1216 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableSet} Type Schema Documentation}
1217
1218 \noindent{\small
1219 The set of tables hosted by a resource.
1220 \par}
1221
1222 \vspace{1ex}\noindent\textbf{\xmlel{vs:TableSet} Type Schema Definition}
1223
1224 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1225 <xs:complexType name="TableSet" >
1226 <xs:sequence >
1227 <xs:element name="schema" type="vs:TableSchema" minOccurs="1"
1228 maxOccurs="unbounded" >
1229 <xs:unique name="DataCollection-tableName" >
1230 <xs:selector xpath="table" />
1231 <xs:field xpath="name" />
1232 </xs:unique>
1233 </xs:element>
1234 </xs:sequence>
1235 <xs:anyAttribute namespace="##other" />
1236 </xs:complexType>
1237 \end{lstlisting}
1238
1239 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:TableSet} Metadata Elements}
1240
1241 \begingroup\small\begin{bigdescription}\item[Element \xmlel{schema}]
1242 \begin{description}
1243 \item[Type] composite: \xmlel{vs:TableSchema}
1244 \item[Meaning]
1245 A named description of a group of logically related tables.
1246
1247 \item[Occurrence] required; multiple occurrences allowed.
1248 \item[Comment]
1249 The name given by the “name” child element must
1250 be unique within this TableSet instance. If there is
1251 only one schema in this set and/or there is no locally
1252 appropriate name to provide, the name can be set to
1253 “default”.
1254
1255 \item[Comment]
1256 This aggregation does not need to map to an
1257 actual database, catalogue, or schema, though the
1258 publisher may choose to aggregate along such
1259 designations. Particular service protocols may
1260 require stricter patterns.
1261
1262
1263 \end{description}
1264
1265
1266 \end{bigdescription}\endgroup
1267
1268 \endgroup
1269 \end{generated}
1270
1271 % /GENERATED
1272
1273
1274 The \xmlel{vs:TableSchema} type groups
1275 tables that are logically related.
1276 For example, a single
1277 resource may provide access to several major astronomical catalogues
1278 (e.g., SDSS, 2MASS, and FIRST) from one site, enabling high-performance
1279 cross-correlations between them. Each catalogue can be described in a
1280 separate \xmlel{schema} element, using the elements from
1281 the \xmlel{vs:TableSchema} type.
1282
1283
1284 % GENERATED: !schemadoc VODataService-v1.2.xsd TableSchema
1285 \begin{generated}
1286 \begingroup
1287 \renewcommand*\descriptionlabel[1]{%
1288 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableSchema} Type Schema Documentation}
1289
1290 \noindent{\small
1291 A detailed description of a logically related group of tables.
1292 \par}
1293
1294 \vspace{1ex}\noindent\textbf{\xmlel{vs:TableSchema} Type Schema Definition}
1295
1296 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1297 <xs:complexType name="TableSchema" >
1298 <xs:sequence >
1299 <xs:element name="name" type="xs:token" minOccurs="1" maxOccurs="1" />
1300 <xs:element name="title" type="xs:token" minOccurs="0" />
1301 <xs:element name="description" type="xs:token" minOccurs="0"
1302 maxOccurs="1" />
1303 <xs:element name="utype" type="xs:token" minOccurs="0" />
1304 <xs:element name="table" type="vs:Table" minOccurs="0"
1305 maxOccurs="unbounded" />
1306 </xs:sequence>
1307 <xs:anyAttribute namespace="##other" />
1308 </xs:complexType>
1309 \end{lstlisting}
1310
1311 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:TableSchema} Metadata Elements}
1312
1313 \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}]
1314 \begin{description}
1315 \item[Type] string: \xmlel{xs:token}
1316 \item[Meaning]
1317 A name for the group of tables.
1318
1319 \item[Occurrence] required
1320 \item[Comment]
1321 This is used to uniquely identify the group of tables among
1322 several groups. If no title is given, this
1323 name can be used for display purposes.
1324
1325 \item[Comment]
1326 If there is no appropriate logical name associated with
1327 this group, the name should be explicitly set to
1328 “default”.
1329
1330
1331 \end{description}
1332 \item[Element \xmlel{title}]
1333 \begin{description}
1334 \item[Type] string: \xmlel{xs:token}
1335 \item[Meaning]
1336 A descriptive, human-interpretable name for the group of
1337 tables.
1338
1339 \item[Occurrence] optional
1340 \item[Comment]
1341 This is used for display purposes. There is no requirement
1342 regarding uniqueness. It is useful when there are
1343 multiple schemas in the context (e.g., within a
1344 tableset; otherwise, the resource title could be
1345 used instead).
1346
1347
1348 \end{description}
1349 \item[Element \xmlel{description}]
1350 \begin{description}
1351 \item[Type] string: \xmlel{xs:token}
1352 \item[Meaning]
1353 A free text description of the group of tables that should
1354 explain in general how all of the tables in the group are
1355 related.
1356
1357 \item[Occurrence] optional
1358
1359 \end{description}
1360 \item[Element \xmlel{utype}]
1361 \begin{description}
1362 \item[Type] string: \xmlel{xs:token}
1363 \item[Meaning]
1364 An identifier for a concept in a data model that
1365 the data in this schema as a whole represent.
1366
1367 \item[Occurrence] optional
1368 \item[Comment]
1369 The form of the utype string depends on the data
1370 model; common forms are sequences of dotted identifiers
1371 (e.g., in SSA) or URIs (e.g., in RegTAP).
1372
1373
1374 \end{description}
1375 \item[Element \xmlel{table}]
1376 \begin{description}
1377 \item[Type] composite: \xmlel{vs:Table}
1378 \item[Meaning]
1379 A description of one table.
1380
1381 \item[Occurrence] optional; multiple occurrences allowed.
1382
1383 \end{description}
1384
1385
1386 \end{bigdescription}\endgroup
1387
1388 \endgroup
1389 \end{generated}
1390
1391 % /GENERATED
1392
1393
1394 Each table in a schema is described in detail using the
1395 \xmlel{vs:Table} type.
1396
1397
1398
1399 % GENERATED: !schemadoc VODataService-v1.2.xsd Table
1400 \begin{generated}
1401 \begingroup
1402 \renewcommand*\descriptionlabel[1]{%
1403 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vs:Table} Type Schema Definition}
1404
1405 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1406 <xs:complexType name="Table" >
1407 <xs:sequence >
1408 <xs:element name="name" type="xs:token" minOccurs="1" maxOccurs="1" />
1409 <xs:element name="title" type="xs:token" minOccurs="0" />
1410 <xs:element name="description" type="xs:token" minOccurs="0" />
1411 <xs:element name="utype" type="xs:token" minOccurs="0" />
1412 <xs:element name="nrows" type="xs:nonNegativeInteger" minOccurs="0"
1413 maxOccurs="1" />
1414 <xs:element name="column" type="vs:TableParam" minOccurs="0"
1415 maxOccurs="unbounded" />
1416 <xs:element name="foreignKey" type="vs:ForeignKey" minOccurs="0"
1417 maxOccurs="unbounded" />
1418 </xs:sequence>
1419 <xs:attribute name="type" type="xs:string" />
1420 <xs:anyAttribute namespace="##other" />
1421 </xs:complexType>
1422 \end{lstlisting}
1423
1424 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:Table} Attributes}
1425
1426 \begingroup\small\begin{bigdescription}
1427 \item[type]
1428 \begin{description}
1429 \item[Type] string: \xmlel{xs:string}
1430 \item[Meaning]
1431 A name for the role this table plays. Recognized
1432 values include “output”, indicating this table is output
1433 from a query; “base\_table”, indicating a table
1434 whose records represent the main subjects of its
1435 schema; and “view”, indicating that the table represents
1436 a useful combination or subset of other tables. Other
1437 values are allowed.
1438
1439 \item[Occurrence] optional
1440 \end{description}
1441
1442
1443 \end{bigdescription}\endgroup
1444
1445
1446
1447 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:Table} Metadata Elements}
1448
1449 \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}]
1450 \begin{description}
1451 \item[Type] string: \xmlel{xs:token}
1452 \item[Meaning]
1453 The fully qualified name of the table. This name
1454 should include all catalogue or schema prefixes
1455 needed to sufficiently uniquely distinguish it in a
1456 query.
1457
1458 \item[Occurrence] required
1459 \item[Comment]
1460 In general, the format of the qualified name may
1461 depend on the context; however, when the
1462 table is intended to be queryable via ADQL, then the
1463 catalogue and schema qualifiers are delimited from the
1464 table name with dots (.).
1465
1466
1467 \end{description}
1468 \item[Element \xmlel{title}]
1469 \begin{description}
1470 \item[Type] string: \xmlel{xs:token}
1471 \item[Meaning]
1472 A descriptive, human-interpretable name for the table.
1473
1474 \item[Occurrence] optional
1475 \item[Comment]
1476 This is used for display purposes. There is no requirement
1477 regarding uniqueness.
1478
1479
1480 \end{description}
1481 \item[Element \xmlel{description}]
1482 \begin{description}
1483 \item[Type] string: \xmlel{xs:token}
1484 \item[Meaning]
1485 A free-text description of the table's contents
1486
1487 \item[Occurrence] optional
1488
1489 \end{description}
1490 \item[Element \xmlel{utype}]
1491 \begin{description}
1492 \item[Type] string: \xmlel{xs:token}
1493 \item[Meaning]
1494 An identifier for a concept in a data model that
1495 the data in this table represent.
1496
1497 \item[Occurrence] optional
1498 \item[Comment]
1499 The form of the utype string depends on the data
1500 model; common forms are sequences of dotted identifiers
1501 (e.g., in SSA) or URIs (e.g., in RegTAP).
1502
1503
1504 \end{description}
1505 \item[Element \xmlel{nrows}]
1506 \begin{description}
1507 \item[Type] \xmlel{xs:nonNegativeInteger}
1508 \item[Meaning]
1509 The approximate size of the table in rows.
1510
1511 \item[Occurrence] optional
1512 \item[Comment]
1513 This is not expected to be exact. For instance, the
1514 estimates on table sizes databases keep for query
1515 planning purposes are suitable for this field.
1516
1517
1518 \end{description}
1519 \item[Element \xmlel{column}]
1520 \begin{description}
1521 \item[Type] composite: \xmlel{vs:TableParam}
1522 \item[Meaning]
1523 A description of a table column.
1524
1525 \item[Occurrence] optional; multiple occurrences allowed.
1526
1527 \end{description}
1528 \item[Element \xmlel{foreignKey}]
1529 \begin{description}
1530 \item[Type] composite: \xmlel{vs:ForeignKey}
1531 \item[Meaning]
1532 A description of a foreign keys, one or more columns
1533 from the current table that can be used to join with
1534 another table.
1535
1536 \item[Occurrence] optional; multiple occurrences allowed.
1537
1538 \end{description}
1539
1540
1541 \end{bigdescription}\endgroup
1542
1543 \endgroup
1544 \end{generated}
1545
1546 % /GENERATED
1547
1548
1549
1550
1551 Each column in a table can be described using the
1552 \xmlel{vs:TableParam} type which is described in
1553 section~\ref{sect:param}. The foreign keys in the table that
1554 can be used to join it with another table can be described with the
1555 \xmlel{vs:ForeignKey} type (section~\ref{sect:fkey}).
1556 A foreign key description should only refer to tables described within
1557 the current table set.
1558
1559 When the table set describes a set of TAP-accessible tables, the value of
1560 a \xmlel{table}'s \xmlel{name} child must be in a form immediately
1561 usable for use in ADQL or SQL queries. This corresponds to the analogous
1562 requirement for \tapschema. This means that all qualifications (schema,
1563 catalogue) must be present, but also that when delimited
1564 identifiers are used as table names on the relational side,
1565 the quotes must be part of \xmlel{name}'s value, and the
1566 capitalisation used in the DDL must be preserved.
1567
1568
1569 The \xmlel{vs:Table} also provides an attribute for indicating
1570 the role a table plays in the schema.
1571
1572
1573
1574
1575
1576 \subsubsection{Unique Names for Tables}
1577 \label{sect:unique}
1578
1579
1580 The definitions of the \xmlel{tableset} elements used in
1581 the \xmlel{vs:DataCollection} and
1582 \xmlel{vs:Catalog\-Ser\-vice} types
1583 constrain certain names to be unique. In particular, all schema names
1584 within a \xmlel{tableset} element must be unique, and all
1585 table names within a \xmlel{schema} element must be
1586 unique. A schema and table may share a common name, such as
1587 ``default''. These constraints make it possible to uniquely locate
1588 the description of a schema or table within a VOResource description.
1589
1590
1591 \subsubsection{Foreign Keys}
1592 \label{sect:fkey}
1593
1594
1595 The \xmlel{vs:ForeignKey} type is used to describe foreign
1596 keys in a table that allow it to be joined efficiently with another
1597 table. A foreign key is a set of columns that map to a corresponding
1598 set of columns in another table.
1599
1600
1601 % GENERATED: !schemadoc VODataService-v1.2.xsd ForeignKey
1602 \begin{generated}
1603 \begingroup
1604 \renewcommand*\descriptionlabel[1]{%
1605 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:ForeignKey} Type Schema Documentation}
1606
1607 \noindent{\small
1608 A description of the mapping a foreign key -- a set of
1609 columns from one table -- to columns in another table.
1610 \par}
1611
1612 \noindent{\small
1613 When foreign keys are declared in this way, clients can expect
1614 that joins constrained with the foreign keys are preformed
1615 efficiently (e.g., using an index).
1616 \par}
1617
1618 \vspace{1ex}\noindent\textbf{\xmlel{vs:ForeignKey} Type Schema Definition}
1619
1620 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1621 <xs:complexType name="ForeignKey" >
1622 <xs:sequence >
1623 <xs:element name="targetTable" type="xs:token" />
1624 <xs:element name="fkColumn" type="vs:FKColumn" minOccurs="1"
1625 maxOccurs="unbounded" />
1626 <xs:element name="description" type="xs:token" minOccurs="0" />
1627 <xs:element name="utype" type="xs:token" minOccurs="0" />
1628 </xs:sequence>
1629 </xs:complexType>
1630 \end{lstlisting}
1631
1632 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:ForeignKey} Metadata Elements}
1633
1634 \begingroup\small\begin{bigdescription}\item[Element \xmlel{targetTable}]
1635 \begin{description}
1636 \item[Type] string: \xmlel{xs:token}
1637 \item[Meaning]
1638 The fully qualified name (including catalogue and schema, as
1639 applicable) of the table that can be joined with the
1640 table containing this foreign key.
1641
1642 \item[Occurrence] required
1643
1644 \end{description}
1645 \item[Element \xmlel{fkColumn}]
1646 \begin{description}
1647 \item[Type] composite: \xmlel{vs:FKColumn}
1648 \item[Meaning]
1649 A pair of column names, one from this table and one
1650 from the target table that should be used to join the
1651 tables in a query.
1652
1653 \item[Occurrence] required; multiple occurrences allowed.
1654
1655 \end{description}
1656 \item[Element \xmlel{description}]
1657 \begin{description}
1658 \item[Type] string: \xmlel{xs:token}
1659 \item[Meaning]
1660 A free-text description of what this key points to
1661 and what the relationship means.
1662
1663 \item[Occurrence] optional
1664
1665 \end{description}
1666 \item[Element \xmlel{utype}]
1667 \begin{description}
1668 \item[Type] string: \xmlel{xs:token}
1669 \item[Meaning]
1670 An identifier for a concept in a data model that
1671 the association enabled by this key represents.
1672
1673 \item[Occurrence] optional
1674 \item[Comment]
1675 The form of the utype string depends on the data
1676 model; common forms are sequences of dotted identifiers
1677 (e.g., in SSA) or URIs (e.g., in RegTAP).
1678
1679
1680 \end{description}
1681
1682
1683 \end{bigdescription}\endgroup
1684
1685 \endgroup
1686 \end{generated}
1687
1688 % /GENERATED
1689
1690
1691 In this model, the source of the foreign
1692 key is the current table being described (i.e., represented by the
1693 \xmlel{table} element that contains the
1694 \xmlel{vs:ForeignKey} description, and thus does not need to be
1695 named explicitly). The key that is described points to the table
1696 given by the \xmlel{targetTable} child element. Each child
1697 \xmlel{fkColumn} element then gives a pair of columns, one
1698 from the source table and one from the target table, that can be
1699 constrained to be equal in a query that joins the two tables.
1700
1701
1702
1703
1704
1705
1706 \subsubsection{Extending Table Metadata}
1707 \label{sect:tblext}
1708
1709 It is envisioned that it may be useful in the future to provide richer
1710 metadata for describing tables within a VOResource description than
1711 what are defined in this document. This document recommends the
1712 use of the following extension mechanisms when richer descriptions are
1713 desired:
1714
1715 \begin{enumerate}
1716 \item Use extended types by applying the \xmlel{xsi:type}
1717 attribute to the \xmlel{tableset},
1718 \xmlel{schema}, \xmlel{table},
1719 \xmlel{column} and/or
1720 \xmlel{dataType} elements. The values provided in the
1721 attributes must refer to an XML type legally extended from the types
1722 associated with these elements according to the rules of XML Schema
1723 \citep{std:XSD} and the VOResource specification.
1724
1725 \item Apply a globally-defined attribute from a schema other than
1726 VODataService (i.e. from a namespace other than
1727 \url{http://www.ivoa.net/xml/VODataService/v1.1}) to any of the
1728 \xmlel{tableset}, \xmlel{schema},
1729 \xmlel{table}, and/or \xmlel{column}
1730 elements.
1731
1732 \item When the extended metadata is specific to how the table data is
1733 accessed via a particular service protocol, then the new
1734 metadata can be incorporated into a specific capability
1735 extension (as described in the VOResource specification).
1736 This extension may make use of the
1737 various names within the \xmlel{tableset} to
1738 indicate where the extension metadata apply.
1739
1740 \item Use the \xmlel{extendedType} attribute of the
1741 \xmlel{dataType} element (see
1742 section~\ref{sect:tbldatatypes})
1743 to indicate a more specific data type then those defined by the
1744 \xmlel{vs:TableParam} type.
1745 \end{enumerate}
1746
1747 \subsection{Interface Type Extension: ParamHTTP}
1748 \label{sect:paramif}
1749
1750
1751 The \xmlel{vs:ParamHTTP} type is a specialized service interface
1752 description that extends the VOResource \xmlel{vr:Interface} type
1753 (as recommended by VOResource 1.1, section 2.2). It
1754 describes a service interface that is invoked over HTTP via a GET or a
1755 POST in which the inputs are parameters
1756 encoded in multipart/form-data or application/x-www-form-urlencoded
1757 containers.
1758
1759 % GENERATED: !schemadoc VODataService-v1.2.xsd ParamHTTP
1760 \begin{generated}
1761 \begingroup
1762 \renewcommand*\descriptionlabel[1]{%
1763 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:ParamHTTP} Type Schema Documentation}
1764
1765 \noindent{\small
1766 A service invoked via an HTTP Query (either Get or Post)
1767 with a set of arguments consisting of keyword name-value pairs.
1768 \par}
1769
1770 \noindent{\small
1771 Note that the URL for help with this service can be put into
1772 the service/referenceURL element.
1773 \par}
1774
1775 \vspace{1ex}\noindent\textbf{\xmlel{vs:ParamHTTP} Type Schema Definition}
1776
1777 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1778 <xs:complexType name="ParamHTTP" >
1779 <xs:complexContent >
1780 <xs:extension base="vr:Interface" >
1781 <xs:sequence >
1782 <xs:element name="queryType" type="vs:HTTPQueryType" minOccurs="0"
1783 maxOccurs="2" />
1784 <xs:element name="resultType" type="xs:token" minOccurs="0"
1785 maxOccurs="1" />
1786 <xs:element name="param" type="vs:InputParam" minOccurs="0"
1787 maxOccurs="unbounded" />
1788 <xs:element name="testQuery" type="xs:string" minOccurs="0"
1789 maxOccurs="1" />
1790 </xs:sequence>
1791 </xs:extension>
1792 </xs:complexContent>
1793 </xs:complexType>
1794 \end{lstlisting}
1795
1796 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:ParamHTTP} Extension Metadata Elements}
1797
1798 \begingroup\small\begin{bigdescription}\item[Element \xmlel{queryType}]
1799 \begin{description}
1800 \item[Type] string with controlled vocabulary
1801 \item[Meaning]
1802 The type of HTTP request, either GET or POST.
1803
1804 \item[Occurrence] optional; up to 2 occurrences allowed.
1805
1806 \item[Terms]\hfil
1807 \begin{longtermsdescription}
1808 \item[GET]
1809 \item[POST]
1810 \end{longtermsdescription}
1811 \item[Comment]
1812 The service may indicate support for both GET
1813 and POST by providing 2 queryType elements, one
1814 with GET and one with POST. Since the IVOA standard
1815 DALI requires standard services to support both
1816 GET and POST, this piece of metadata is not
1817 useful in the description of standard DAL services
1818 and does not need to be given for those.
1819
1820
1821 \end{description}
1822 \item[Element \xmlel{resultType}]
1823 \begin{description}
1824 \item[Type] string: \xmlel{xs:token}
1825 \item[Meaning]
1826 The MIME media type of a document returned in
1827 the HTTP response.
1828
1829 \item[Occurrence] optional
1830
1831 \end{description}
1832 \item[Element \xmlel{param}]
1833 \begin{description}
1834 \item[Type] composite: \xmlel{vs:InputParam}
1835 \item[Meaning]
1836 A description of a input parameter that can be
1837 provided as a name=value argument to the service.
1838
1839 \item[Occurrence] optional; multiple occurrences allowed.
1840
1841 \end{description}
1842 \item[Element \xmlel{testQuery}]
1843 \begin{description}
1844 \item[Type] string: \xmlel{xs:string}
1845 \item[Meaning]
1846 An ampersand-delimited list of arguments that
1847 can be used to test this service interface;
1848 when provided as the input to this interface,
1849 it will produce a legal, non-null response.
1850
1851 \item[Occurrence] optional
1852 \item[Comment]
1853 When the interface supports GET, then the full
1854 query URL is formed by the concatenation of the
1855 base URL (given by the accessURL) and the value
1856 given by this testQuery element.
1857
1858
1859 \end{description}
1860
1861
1862 \end{bigdescription}\endgroup
1863
1864 \endgroup
1865 \end{generated}
1866
1867 % /GENERATED
1868
1869 The extension metadata defined in the schema definition above are all
1870 optional. Nevertheless, even when an \xmlel{interface}
1871 instance does not include any of these extended child elements, the
1872 use of \verb|xsi:type="vs:ParamHTTP"| indicates that the interface
1873 accessed via the URL given by the \xmlel{accessURL}
1874 element complies with the general parameter-based protocol described
1875 in this section.
1876
1877 % resultType stinks when we have DALI RESPONSEFORMAT. Let's think
1878 % about fixing this in 1.3.
1879
1880
1881
1882
1883
1884
1885 An important intended use of the \xmlel{vs:ParamHTTP} type is
1886 describing the interface of an IVOA standard service protocol
1887 of the ``simple'' variety, such as the Simple Image Access Protocol
1888 \citep{2015ivoa.spec.1223D}. In particular, it is recommended that
1889 specifications that define how a standard service is registered in a
1890 registry \emph{require} the use of the \xmlel{vs:ParamHTTP}
1891 interface type when it is applicable.
1892
1893
1894
1895 Normally, a VOResource
1896 description indicates its support for a standard protocol with
1897 \xmlel{capability} element having a
1898 \xmlel{standardID} attribute set to specific URI representing the
1899 standard. The standard will usually spell out the HTTP query type,
1900 the returned media type, and input parameters required for compliance;
1901 therefore, it is not necessary that the \xmlel{vs:ParamHTTP}
1902 description provide any of the optional extended metadata, as they are
1903 already implied by the \xmlel{standardID}. The description need
1904 only reflect the optional or locally unique features of the
1905 interface. In particular, description may include
1906
1907
1908 \begin{itemize}
1909 \item a \xmlel{queryType} element for a type that is not
1910 required by the standard (as long as the required query type is
1911 supported as well),
1912
1913 \item \xmlel{param}\/ elements for any optional parameters
1914 or local extended parameters (when allowed by the standard).
1915 \end{itemize}
1916
1917
1918 Listing required parameters is allowed, even when
1919 describing a standard interface as long as these are consistent with
1920 the service specification and the corresponding \xmlel{param}
1921 elements include the attribute \verb|std="true"| (see
1922 section~\ref{sect:inputparam}). The \xmlel{param}
1923 elements for custom parameters that are not part of the standard (but
1924 are rather local customizations) should include the attribute
1925 \verb|std="false"|.
1926
1927
1928
1929
1930
1931 \subsection{Data Parameters}
1932 \label{sect:param}
1933
1934
1935 The VODataService schema provides several element types for describing
1936 different kinds of data parameters used in datasets and services,
1937 including service input parameters and table columns. The parameter
1938 types describe a parameter in terms of elementary metadata
1939 including name, data type, and meaning.
1940
1941
1942 All the VODataService parameter types derive from the base type
1943 \xmlel{vs:BaseParam} which defines all the common parameter
1944 metadata except the data type.
1945
1946
1947 % GENERATED: !schemadoc VODataService-v1.2.xsd BaseParam
1948 \begin{generated}
1949 \begingroup
1950 \renewcommand*\descriptionlabel[1]{%
1951 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:BaseParam} Type Schema Documentation}
1952
1953 \noindent{\small
1954 A description of a parameter that places no restriction on
1955 the parameter's data type.
1956 \par}
1957
1958 \noindent{\small
1959 As the parameter's data type is usually important, schemas
1960 normally employ a sub-class of this type
1961 rather than this type directly.
1962 \par}
1963
1964 \vspace{1ex}\noindent\textbf{\xmlel{vs:BaseParam} Type Schema Definition}
1965
1966 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1967 <xs:complexType name="BaseParam" >
1968 <xs:sequence >
1969 <xs:element name="name" type="xs:token" minOccurs="0" />
1970 <xs:element name="description" type="xs:token" minOccurs="0" />
1971 <xs:element name="unit" type="xs:token" minOccurs="0" />
1972 <xs:element name="ucd" type="xs:token" minOccurs="0" />
1973 <xs:element name="utype" type="xs:token" minOccurs="0" />
1974 </xs:sequence>
1975 <xs:anyAttribute namespace="##other" />
1976 </xs:complexType>
1977 \end{lstlisting}
1978
1979 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:BaseParam} Metadata Elements}
1980
1981 \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}]
1982 \begin{description}
1983 \item[Type] string: \xmlel{xs:token}
1984 \item[Meaning]
1985 The name of the parameter or column.
1986
1987 \item[Occurrence] optional
1988
1989 \end{description}
1990 \item[Element \xmlel{description}]
1991 \begin{description}
1992 \item[Type] string: \xmlel{xs:token}
1993 \item[Meaning]
1994 A free-text description of a parameter's or column's
1995 contents.
1996
1997 \item[Occurrence] optional
1998
1999 \end{description}
2000 \item[Element \xmlel{unit}]
2001 \begin{description}
2002 \item[Type] string: \xmlel{xs:token}
2003 \item[Meaning]
2004 The unit associated with the values in the parameter
2005 or column.
2006
2007 \item[Occurrence] optional
2008
2009 \end{description}
2010 \item[Element \xmlel{ucd}]
2011 \begin{description}
2012 \item[Type] string: \xmlel{xs:token}
2013 \item[Meaning]
2014 The name of a unified content descriptor that
2015 describes the scientific content of the parameter.
2016
2017 \item[Occurrence] optional
2018 \item[Comment]
2019 There are no requirements for compliance with any
2020 particular UCD standard. The format of the UCD can
2021 be used to distinguish between UCD1, UCD1+, and
2022 SIA-UCD.
2023
2024
2025 \end{description}
2026 \item[Element \xmlel{utype}]
2027 \begin{description}
2028 \item[Type] string: \xmlel{xs:token}
2029 \item[Meaning]
2030 An identifier for a concept in a data model that
2031 the data in this schema represent.
2032
2033 \item[Occurrence] optional
2034 \item[Comment]
2035 The form of the utype string depends on the data
2036 model; common forms are sequences of dotted identifiers
2037 (e.g., in SSA) or URIs (e.g., in RegTAP).
2038
2039
2040 \end{description}
2041
2042
2043 \end{bigdescription}\endgroup
2044
2045 \endgroup
2046 \end{generated}
2047
2048 % /GENERATED
2049
2050 Leaving the data type metadatum out of \xmlel{vs:BaseParam}
2051 allows the different kinds of parameters derived from
2052 \xmlel{vs:BaseParam} to restrict the allowed data types to
2053 specific sets. The subsections below describe the different data
2054 types associated with input parameters
2055 (\xmlel{vs:InputParam}) and table
2056 columns (\xmlel{vs:TableParam}). The
2057 XML types associated with their \xmlel{dataType} elements
2058 derive from a common parent, \xmlel{vs:DataType}.
2059
2060
2061 % GENERATED: !schemadoc VODataService-v1.2.xsd DataType
2062 \begin{generated}
2063 \begingroup
2064 \renewcommand*\descriptionlabel[1]{%
2065 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:DataType} Type Schema Documentation}
2066
2067 \noindent{\small
2068 A type (in the computer language sense) associated with a
2069 parameter with an arbitrary name
2070 \par}
2071
2072 \noindent{\small
2073 This XML type is used as a parent for defining data types
2074 with a restricted set of names.
2075 \par}
2076
2077 \vspace{1ex}\noindent\textbf{\xmlel{vs:DataType} Type Schema Definition}
2078
2079 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2080 <xs:complexType name="DataType" >
2081 <xs:simpleContent >
2082 <xs:extension base="xs:token" >
2083 <xs:attribute name="arraysize" type="vs:ArrayShape" />
2084 <xs:attribute name="delim" type="xs:string" />
2085 <xs:attribute name="extendedType" type="xs:string" />
2086 <xs:attribute name="extendedSchema" type="xs:anyURI" />
2087 <xs:anyAttribute namespace="##other" />
2088 </xs:extension>
2089 </xs:simpleContent>
2090 </xs:complexType>
2091 \end{lstlisting}
2092
2093 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:DataType} Attributes}
2094
2095 \begingroup\small\begin{bigdescription}
2096 \item[arraysize]
2097 \begin{description}
2098 \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}
2099 \item[Meaning]
2100 The shape of the array that constitutes the value.
2101
2102 \item[Occurrence] optional
2103
2104 \item[Comment]
2105 Leave arraysize empty for scalar values. In version 1.1,
2106 this defaulted to 1, which was intended to indicate
2107 a scalar. This is now deprecated; an arraysize of 1 should
2108 be avoided now, the future interpretation, in accord with
2109 VOTable, will be “array of size 1”.
2110
2111 \end{description}
2112 \item[delim]
2113 \begin{description}
2114 \item[Type] string: \xmlel{xs:string}
2115 \item[Meaning]
2116 A string that is used to delimit elements of an array
2117 value in InputParams.
2118
2119 \item[Occurrence] optional
2120 \item[Comment]
2121 Unless specifically disallowed by the context,
2122 applications should allow optional spaces to
2123 appear in an actual data value before and after
2124 the delimiter (e.g., “1, 5” when delim=“,”).
2125
2126 \item[Comment]
2127 This should not be used for VOTable types; there,
2128 VOTable (typcially TABLEDATA) conventions for writing
2129 arrays are binding.
2130
2131 \end{description}
2132 \item[extendedType]
2133 \begin{description}
2134 \item[Type] string: \xmlel{xs:string}
2135 \item[Meaning]
2136 The data value represented by this type can be
2137 interpreted as of a custom type identified by
2138 the value of this attribute.
2139
2140 \item[Occurrence] optional
2141 \item[Comment]
2142 If an application does not recognize this
2143 extendedType, it should attempt to handle value
2144 assuming the type given by the element's value.
2145 string is a recommended default type.
2146
2147 \item[Comment]
2148 This element may make use of the extendedSchema
2149 attribute to refine the identification of the
2150 type. extendedTypes without an extendedSchema
2151 mean VOTable xtypes as defined by DALI.
2152
2153 \end{description}
2154 \item[extendedSchema]
2155 \begin{description}
2156 \item[Type] a URI: \xmlel{xs:anyURI}
2157 \item[Meaning]
2158 An identifier for the schema that the value given
2159 by the extended attribute is drawn from.
2160
2161 \item[Occurrence] optional
2162 \item[Comment]
2163 This attribute is normally ignored if the
2164 extendedType attribute is not present. A missing
2165 extendedSchema indicates that extendedType is a
2166 VOTable xtype.
2167
2168 \end{description}
2169
2170
2171 \end{bigdescription}\endgroup
2172
2173 \endgroup
2174 \end{generated}
2175
2176 % /GENERATED
2177
2178 The content of an element of type \xmlel{vs:DataType} is the name
2179 of the data type for the current parameter. When the element is explicitly
2180 a \xmlel{vs:DataType} (as opposed to one of its derived types),
2181 there are no restrictions on the names that may be included.
2182
2183
2184
2185 A data type description can be augmented via a common set of
2186 \xmlel{vs:DataType} attributes. The
2187 \xmlel{arraysize} attribute indicates the parameter is an array
2188 of values of the named type. Its value describes the shape of the
2189 array. When there is no natural serialisation defined through the type
2190 system, the \xmlel{delim} attribute may be used to indicate
2191 a delimiter that should appear between elements of an array value. This
2192 attribute must not be combined with VOTableDataType, which always
2193 uses VOTable serialisation rules.
2194
2195
2196
2197 More descriptive information about the type can be provided via
2198 \xmlel{extendedType} and \xmlel{extendedSchema}, which
2199 provide an alternate data type name. The name
2200 given in the type's element content, then, represents a commonly
2201 understood “fallback” type. For instance, in VOTable, timestamps are
2202 serialised into strings, which implies a VOTableType of char with
2203 arraysize \verb|*|, as supported by all VOTable readers. VOTable readers
2204 interpreting the timestamp xtype, however, can turn this string into a
2205 timestamp value native to its clients. Such readers will interpret
2206 a VOTable \xmlel{FIELD}'s \xmlel{xtype} attribute.
2207 Such information is reflected in \xmlel{extendedType}.
2208
2209 Arbitrary information can also be
2210 provided via any prefix-qualified, globally defined attribute drawn
2211 from an XML Schema other than VODataService (by virtue of the
2212 \xmlel{xs:anyAttribute} specification present
2213 on \xmlel{vs:DataType}).
2214
2215
2216
2217
2218
2219 Note that in the derived parameter description types described below,
2220 the \xmlel{dataType} element is optional. Its absence
2221 from the parameter description does \emph{not} mean that the
2222 parameter can support any data type; rather, it means that the data
2223 type simply has not been provided (which may limit what an application
2224 can do with the parameter). If a parameter can truly support any data
2225 type, the \xmlel{vs:BaseParam} type can be used directly when the
2226 context permits.
2227
2228
2229 \subsubsection{Input Parameters}
2230 \label{sect:inputparam}
2231
2232
2233 Actual parameters are normally described with types derived from
2234 \xmlel{vs:BaseParam}. The \xmlel{vs:InputParam} is intended
2235 for describing an input parameter to a service or function. In previous
2236 versions of VODataService, input parameters were restricted to be defined
2237 in terms of simple data types, which are intended to be
2238 sufficient for describing an input parameter to a simple REST-like
2239 service or a function in a weakly-typed language. They are defined
2240 in \xmlel{vs:SimpleDataType}:
2241
2242 % GENERATED: !schemadoc VODataService-v1.2.xsd SimpleDataType
2243 \begin{generated}
2244 \begingroup
2245 \renewcommand*\descriptionlabel[1]{%
2246 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Type Schema Documentation}
2247
2248 \noindent{\small
2249 A data type restricted to a small set of names which is
2250 imprecise as to the format of the individual values.
2251 \par}
2252
2253 \noindent{\small
2254 This set is intended for describing simple input parameters to
2255 a service or function.
2256 \par}
2257
2258 \vspace{1ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Type Schema Definition}
2259
2260 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2261 <xs:complexType name="SimpleDataType" >
2262 <xs:simpleContent >
2263 <xs:restriction base="vs:DataType" >
2264 <xs:enumeration value="integer" />
2265 <xs:enumeration value="real" />
2266 <xs:enumeration value="complex" />
2267 <xs:enumeration value="boolean" />
2268 <xs:enumeration value="char" />
2269 <xs:enumeration value="string" />
2270 <xs:attribute name="arraysize" type="vs:ArrayShape" />
2271 <xs:attribute name="delim" type="xs:string" default=" " />
2272 <xs:attribute name="extendedType" type="xs:string" />
2273 <xs:attribute name="extendedSchema" type="xs:anyURI" />
2274 <xs:anyAttribute namespace="##other" />
2275 </xs:restriction>
2276 </xs:simpleContent>
2277 </xs:complexType>
2278 \end{lstlisting}
2279
2280 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:SimpleDataType} Attributes}
2281
2282 \begingroup\small\begin{bigdescription}
2283 \item[arraysize]
2284 \begin{description}
2285 \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}
2286 \item[Meaning] See vs:DataType.
2287 \item[Occurrence] optional
2288
2289 \end{description}
2290 \item[delim]
2291 \begin{description}
2292 \item[Type] string: \xmlel{xs:string}
2293 \item[Meaning] See vs:DataType.
2294 \item[Occurrence] optional
2295 \item[Default] a space character
2296 \end{description}
2297 \item[extendedType]
2298 \begin{description}
2299 \item[Type] string: \xmlel{xs:string}
2300 \item[Meaning] See vs:DataType.
2301 \item[Occurrence] optional
2302 \end{description}
2303 \item[extendedSchema]
2304 \begin{description}
2305 \item[Type] a URI: \xmlel{xs:anyURI}
2306 \item[Meaning] See vs:DataType.
2307 \item[Occurrence] optional
2308 \end{description}
2309
2310
2311 \end{bigdescription}\endgroup
2312
2313 \endgroup
2314 \end{generated}
2315
2316 % /GENERATED
2317
2318 Since VODataService 1.2, input parameters can use any type system,
2319 where non-DALI-compliant services SHOULD use \xmlel{vs:SimpleDataType}
2320 and DALI-compliant services SHOULD use \xmlel{vs:VOTableType}. To
2321 ensure schema validation catches mistakes, resource record authors are
2322 advised to declare the type system intended using \xmlel{xsi:type}; for
2323 instance, a service accepting a DALI point might declare:
2324
2325 \begin{lstlisting}[language=XML]
2326 <param std="true">
2327 <name>pos</name>
2328 <description>ICRS position of target object</description>
2329 <dataType arraysize="2"
2330 xsi:type="vs:VOTableType"
2331 extendedType="point">double</dataType>
2332 </param>
2333 \end{lstlisting}
2334
2335 The \xmlel{vs:InputParam} class then is a \xmlel{vs:BaseParam}
2336 furnished with additional metadata
2337 defining how to use the parameter and whether or not it is defined in
2338 the standard governing the capability the interface is in (if any):
2339
2340
2341 % GENERATED: !schemadoc VODataService-v1.2.xsd InputParam
2342 \begin{generated}
2343 \begingroup
2344 \renewcommand*\descriptionlabel[1]{%
2345 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Documentation}
2346
2347 \noindent{\small
2348 A description of a service or function parameter having a
2349 fixed data type.
2350 \par}
2351
2352 \noindent{\small
2353 DALI-compliant services should use VOTableType here, others
2354 should use SimpleDataType.
2355 \par}
2356
2357 \vspace{1ex}\noindent\textbf{\xmlel{vs:InputParam} Type Schema Definition}
2358
2359 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2360 <xs:complexType name="InputParam" >
2361 <xs:complexContent >
2362 <xs:extension base="vs:BaseParam" >
2363 <xs:sequence >
2364 <xs:element name="dataType" type="vs:DataType" minOccurs="0" />
2365 </xs:sequence>
2366 <xs:attribute name="use" type="vs:ParamUse" default="optional" />
2367 <xs:attribute name="std" type="xs:boolean" default="true" />
2368 </xs:extension>
2369 </xs:complexContent>
2370 </xs:complexType>
2371 \end{lstlisting}
2372
2373 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:InputParam} Attributes}
2374
2375 \begingroup\small\begin{bigdescription}
2376 \item[use]
2377 \begin{description}
2378 \item[Type] string with controlled vocabulary
2379 \item[Meaning]
2380 An indication of whether this parameter is
2381 required to be provided for the application
2382 or service to work properly.
2383
2384 \item[Occurrence] optional
2385
2386 \item[Terms]\hfil
2387 \begin{longtermsdescription}
2388 \item[required]
2389 The parameter is required for the application or
2390 service to work properly.
2391
2392 \item[optional]
2393 The parameter is optional but supported by the application or
2394 service.
2395
2396 \item[ignored]
2397 The parameter is not supported and thus is ignored by the
2398 application or service.
2399
2400 \end{longtermsdescription}
2401 \item[Default] optional
2402 \end{description}
2403 \item[std]
2404 \begin{description}
2405 \item[Type] boolean (true/false): xs:boolean
2406 \item[Meaning]
2407 If true, the meaning and behavior of this parameter is
2408 reserved and defined by a standard interface. If
2409 false, it represents an implementation-specific
2410 parameter that effectively extends the behavior of the
2411 service or application.
2412
2413 \item[Occurrence] optional
2414 \item[Default] true
2415 \end{description}
2416
2417
2418 \end{bigdescription}\endgroup
2419
2420
2421
2422 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:InputParam} Extension Metadata Elements}
2423
2424 \begingroup\small\begin{bigdescription}\item[Element \xmlel{dataType}]
2425 \begin{description}
2426 \item[Type] a string with optional attributes
2427 \item[Meaning]
2428 A type of data contained in the parameter.
2429
2430 \item[Occurrence] optional
2431
2432 \end{description}
2433
2434
2435 \end{bigdescription}\endgroup
2436
2437 \endgroup
2438 \end{generated}
2439
2440 % /GENERATED
2441
2442
2443 Here is an example for a description
2444 of an input parameter that might appear inside an
2445 \xmlel{vs:ParamHTTP} interface description. As noted in
2446 section~\ref{sect:paramif}, a \xmlel{param}
2447 element uses the \xmlel{vs:InputParam} type to describe itself:
2448
2449 \begin{lstlisting}[language=XML]
2450 <param use="required">
2451 <name> radius </name>
2452 <description>
2453 search radius; returned objects are restricted to fall
2454 within this angular distance of the search position.
2455 </description>
2456 <ucd> phys.angSize </ucd>
2457 <dataType xsi:type="vs:SimpleDataType"> real </dataType>
2458 </param>
2459 \end{lstlisting}
2460
2461 \subsubsection{Table Columns}
2462 \label{sect:columns}
2463
2464
2465 The \xmlel{vs:TableParam} is also derived from
2466 \xmlel{vs:BaseParam}, and is designed for describing a column of
2467 a table.
2468
2469
2470 % GENERATED: !schemadoc VODataService-v1.2.xsd TableParam
2471 \begin{generated}
2472 \begingroup
2473 \renewcommand*\descriptionlabel[1]{%
2474 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:TableParam} Type Schema Documentation}
2475
2476 \noindent{\small
2477 A description of a table parameter having a fixed data type.
2478 \par}
2479
2480 \vspace{1ex}\noindent\textbf{\xmlel{vs:TableParam} Type Schema Definition}
2481
2482 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2483 <xs:complexType name="TableParam" >
2484 <xs:complexContent >
2485 <xs:extension base="vs:BaseParam" >
2486 <xs:sequence >
2487 <xs:element name="dataType" type="vs:TableDataType" minOccurs="0" />
2488 <xs:element name="flag" type="xs:token" minOccurs="0"
2489 maxOccurs="unbounded" />
2490 </xs:sequence>
2491 <xs:attribute name="std" type="xs:boolean" />
2492 </xs:extension>
2493 </xs:complexContent>
2494 </xs:complexType>
2495 \end{lstlisting}
2496
2497 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:TableParam} Attributes}
2498
2499 \begingroup\small\begin{bigdescription}
2500 \item[std]
2501 \begin{description}
2502 \item[Type] boolean (true/false): xs:boolean
2503 \item[Meaning]
2504 If true, the meaning and use of this parameter is
2505 reserved and defined by a standard model. If false,
2506 it represents a parameter specific to the data described
2507 If not provided, then the value is unknown.
2508
2509 \item[Occurrence] optional
2510 \end{description}
2511
2512
2513 \end{bigdescription}\endgroup
2514
2515
2516
2517 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:TableParam} Extension Metadata Elements}
2518
2519 \begingroup\small\begin{bigdescription}\item[Element \xmlel{dataType}]
2520 \begin{description}
2521 \item[Type] \xmlel{vs:DataType} with optional attributes
2522 \item[Meaning]
2523 A type of data contained in the column
2524
2525 \item[Occurrence] optional
2526
2527 \end{description}
2528 \item[Element \xmlel{flag}]
2529 \begin{description}
2530 \item[Type] string: \xmlel{xs:token}
2531 \item[Meaning]
2532 A keyword representing traits of the column.
2533 Recognized values include “indexed”, “primary”, and
2534 “nullable”.
2535
2536 \item[Occurrence] optional; multiple occurrences allowed.
2537 \item[Comment]
2538 See the specification document for definitions
2539 of recognized keywords.
2540
2541
2542 \end{description}
2543
2544
2545 \end{bigdescription}\endgroup
2546
2547 \endgroup
2548 \end{generated}
2549
2550 % /GENERATED
2551
2552
2553 A table column's data type is indicated with the \xmlel{dataType}
2554 element with a name drawn from a standard set of names.
2555 Because \xmlel{dataType}'s
2556 XML type, \xmlel{vs:TableDataType}, is abstract, the
2557 element MUST include an
2558 \xmlel{xsi:type} attribute. As discussed in
2559 sect.~\ref{sect:tbldatatypes}, this SHOULD be
2560 \xmlel{vs:VOTableType} for VODataService 1.2 table columns.
2561
2562 When the tableset describes a set of TAP-accessible tables, the value of
2563 a \xmlel{tableColumn}'s \xmlel{name} child must be in a form immediately
2564 usable for use in ADQL or SQL queries. This corresponds to the analogous
2565 requirement for \tapschema\ and is usually only a problem when delimited
2566 identifiers are used for column names on the relational side. In that
2567 case, the quotes must be part of \xmlel{name}'s value, and the
2568 capitalisation used in the DDL must be preserved.
2569
2570
2571 As examples, here are declarations of a column called ``Dec'' containing
2572 a double-valued declination, of the (deprecated) \verb|size| column
2573 from TAP 1.0 which requires quotes because it otherwise clashes with a
2574 SQL reserved name, and a SIAP 1.0-compatible \verb|wcs_cdmatrix|
2575 column that shows how multidimensional arrays are declared; note that in
2576 the last case, the content of \xmlel{unit} pertains to \emph{elements}
2577 of the array, not the array as a whole.
2578
2579 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2580 <column>
2581 <name> Dec </name>
2582 <description> the J2000 declination of the object </description>
2583 <ucd> pos.eq.dec </ucd>
2584 <dataType xsi:type="vs:VOTableType"> double </dataType>
2585 </column>
2586
2587 <column>
2588 <name>"size"</name>
2589 <description>Length of variable length datatypes</description>
2590 <dataType xsi:type="vs:VOTableType">int</dataType>
2591 <flag>nullable</flag>
2592 </column>
2593
2594 <column>
2595 <name>wcs_cdmatrix</name>
2596 <description>World coordinates at WCS reference pixel</description>
2597 <unit>deg</unit>
2598 <ucd>VOX:WCS_CoordRefValue</ucd>
2599 <dataType arraysize="2x2" xsi:type="vs:VOTableType">double</dataType>
2600 <flag>nullable</flag>
2601 </column>
2602 \end{lstlisting}
2603
2604
2605 \subsubsection{Table Column Data Types}
2606 \label{sect:tbldatatypes}
2607
2608
2609 The VODataService schema defines two type systems that derive from
2610 \xmlel{vs:TableDa\-taType}: \xmlel{vs:VOTableType} and
2611 \xmlel{vs:TAPType}. Following the move to VOTable-compatible type
2612 descriptions in TAP 1.1 \citep{2019ivoa.spec.0927D}, this version of
2613 VODataService deprecates the use of \xmlel{vs:TAPType}. New software
2614 should only generate \xmlel{vs:VOTableType}s in \xmlel{tableset}s.
2615
2616
2617 % GENERATED: !schemadoc VODataService-v1.2.xsd VOTableType
2618 \begin{generated}
2619 \begingroup
2620 \renewcommand*\descriptionlabel[1]{%
2621 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:VOTableType} Type Schema Documentation}
2622
2623 \noindent{\small
2624 A data type supported explicitly by the VOTable format
2625 \par}
2626
2627 \vspace{1ex}\noindent\textbf{\xmlel{vs:VOTableType} Type Schema Definition}
2628
2629 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2630 <xs:complexType name="VOTableType" >
2631 <xs:simpleContent >
2632 <xs:restriction base="vs:TableDataType" >
2633 <xs:enumeration value="boolean" />
2634 <xs:enumeration value="bit" />
2635 <xs:enumeration value="unsignedByte" />
2636 <xs:enumeration value="short" />
2637 <xs:enumeration value="int" />
2638 <xs:enumeration value="long" />
2639 <xs:enumeration value="char" />
2640 <xs:enumeration value="unicodeChar" />
2641 <xs:enumeration value="float" />
2642 <xs:enumeration value="double" />
2643 <xs:enumeration value="floatComplex" />
2644 <xs:enumeration value="doubleComplex" />
2645 <xs:attribute name="arraysize" type="vs:ArrayShape" />
2646 <xs:attribute name="delim" type="xs:string" default=" " />
2647 <xs:attribute name="extendedType" type="xs:string" />
2648 <xs:attribute name="extendedSchema" type="xs:anyURI" />
2649 <xs:anyAttribute namespace="##other" />
2650 </xs:restriction>
2651 </xs:simpleContent>
2652 </xs:complexType>
2653 \end{lstlisting}
2654
2655 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:VOTableType} Attributes}
2656
2657 \begingroup\small\begin{bigdescription}
2658 \item[arraysize]
2659 \begin{description}
2660 \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}
2661 \item[Meaning] See vs:DataType.
2662 \item[Occurrence] optional
2663
2664 \end{description}
2665 \item[delim]
2666 \begin{description}
2667 \item[Type] string: \xmlel{xs:string}
2668 \item[Meaning] See vs:DataType.
2669 \item[Occurrence] optional
2670 \item[Default] a space character
2671 \end{description}
2672 \item[extendedType]
2673 \begin{description}
2674 \item[Type] string: \xmlel{xs:string}
2675 \item[Meaning] See vs:DataType.
2676 \item[Occurrence] optional
2677 \end{description}
2678 \item[extendedSchema]
2679 \begin{description}
2680 \item[Type] a URI: \xmlel{xs:anyURI}
2681 \item[Meaning] See vs:DataType.
2682 \item[Occurrence] optional
2683 \end{description}
2684
2685
2686 \end{bigdescription}\endgroup
2687
2688 \endgroup
2689 \end{generated}
2690
2691 % /GENERATED
2692
2693
2694
2695 When the actual column type is not
2696 well matched to a VOTable data type, authors are
2697 encouraged to use the \xmlel{extendedType} attribute to refer to
2698 a more specific type. This will usually be a VOTable \xmlel{xtype} as
2699 defined by DALI \citep{2017ivoa.spec.0517D}. Using different extended
2700 type schemes is possible by setting \xmlel{extendedSchema} to a
2701 non-empty value; data providers using this extension mechanism should
2702 explain their schema in an IVOA Note.
2703
2704 \appendix
2705
2706 \section{Changes from previous versions}
2707
2708 \subsection{Changes since PR-20190715}
2709
2710 \begin{itemize}
2711 \item dropped \verb|vs:Waveband| and changed waveband to being
2712 controlled by a vocabulary that initially grows a generic Photon and a
2713 Neutrino concept over what the previous Waveband had.
2714 \item table/@nrows is now constrained to be non-negative.
2715 \item Now allowing any vs:DataType element to define vs:InputParams.
2716 In order to still ensure schema validation of type names,
2717 now advising to have an explicit xsi:type in param's dataTypes.
2718 \end{itemize}
2719
2720 \subsection{Changes since WD-20181026}
2721
2722 \begin{itemize}
2723 \item Adding a summary of the discovering data collections EN.
2724 \item Spatial coverage now has a frame attribute.
2725 \item Added a SHOULD requirement on CatalogResources to have a tableset.
2726 \item Restricted interface/@testQuery to zero or one occurrences (this
2727 is because there is no clear semantics to having multiple of those).
2728 \item Sanctioning the use of footprint/@ivo-id to indicate the footprint
2729 standard used (which, of course, totally goes against the semantics of
2730 ServiceReference underlying footprint).
2731 \end{itemize}
2732
2733 \subsection{Changes since REC-1.1}
2734
2735 \begin{itemize}
2736 \item Deprecated STCResourceProfile and replaced it with
2737 \xmlel{spatial}, \xmlel{temporal}, and \xmlel{spectral} elements.
2738 \item Introduced new DataResource and CatalogResource resource types
2739 and wove them into the inheritance hierarchy to CatalogService; these
2740 are to be used for ``dependent'' resources.
2741 \item Deprecated DataCollection and StandardSTC (which are no longer
2742 needed).
2743 \item Added an nrows element to \xmlel{vs:Table}.
2744 \item Required inclusion of quotes for delimited identifiers in a
2745 SQL context.
2746 \item DataType/@arraysize no longer defaults to 1, and the
2747 interpretation of arraysize=1 as a scalar is withdrawn. Use empty
2748 arraysize for scalars now.
2749 \item BaseParam's delim attribute no longer defaults to blank. That
2750 would be very unfortunate with VOTable, where other conventions are in
2751 place (e.g., for string arrays). Now discouraging the use of delim
2752 outside of InputParams.
2753 \item Deprecated TAPType.
2754 \item extendedType is now defined to correspond to VOTable xtypes in the
2755 absence of extendedSchema.
2756 \item No longer requiring unique table names within a tableset;
2757 uniquness is now required within a schema (actually, many services have
2758 been in violation of the old unique-within-tableset rule for a long time
2759 without operational difficulties); but then that's largely a moot point
2760 because for the main uses of tableset, fully qualified names are now
2761 required.
2762 \item Ported source to \ivoatex.
2763 \end{itemize}
2764
2765 \subsection{Changes since PR-20100916}
2766
2767 \begin{itemize}
2768 \item updated status for elevation to Recommendation.
2769 \item cleaned-up mis-labeled and mis-ordered change history.
2770 \end{itemize}
2771
2772 \subsection{Changes since PR-20100914}
2773
2774 \begin{itemize}
2775 \item added change history for PR-20100412.
2776 \item added Note about STC mark-up in 3.2
2777 \item reworded sentence describing content of \xmlel{vs:DataType} in
2778 section 3.5.
2779 \end{itemize}
2780
2781 \subsection{Changes since PR-20100412}
2782
2783 \begin{itemize}
2784 \item fix numerous typos discovered in TCG review
2785 \item added section 1.1 to describe role of standard in the VO
2786 architecture, including diagram.
2787 \item corrected frequency range for the UV waveband
2788 \item corrected links to reference documents
2789 \end{itemize}
2790
2791 \subsection{Changes since PR-20090903}
2792
2793 \begin{itemize}
2794 \item added \xmlel{testQuery}
2795 to \xmlel{vs:ParamHTTP}
2796 \item in text, added explanation of
2797 \xmlel{vs:Format}
2798 \item grammatical clean-up
2799 \end{itemize}
2800
2801 \subsection{Changes since WD-20090508 (v1.10)}
2802
2803 \begin{itemize}
2804 \item corrected errors in example in Introduction
2805 \item added \xmlel{description} and
2806 \xmlel{utype} elements to the
2807 \xmlel{vs:ForeignKey} type for consistency with TAP.
2808 \item changed type names \xmlel{vs:TAP} to
2809 \xmlel{vs:TAPType} and \xmlel{vs:VOTable}
2810 \xmlel{vs:VOTableType}.
2811 \end{itemize}
2812
2813 \bibliography{ivoatex/ivoabib,ivoatex/docrepo,local}
2814
2815 \end{document}

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