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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5935 - (hide annotations)
Tue Feb 23 11:39:08 2021 UTC (2 months, 2 weeks ago) by msdemlei
File MIME type: application/x-tex
File size: 106688 byte(s)
VODataService: Bumping to PR-2021-02-29.

Also, declaring our resclasses PDF properly as a vector figure,
which makes the HTML rendering a lot prettier.


1 msdemlei 5051 \documentclass[11pt,a4paper]{ivoa}
2     \input tthdefs
3 msdemlei 5115 % widen up the display a bit so that 75 column listings still fit on
4     % the page
5 msdemlei 5165 \usepackage[width=14cm,left=4cm]{geometry}
6 msdemlei 5055 \usepackage{listings}
7     \lstloadlanguages{XML}
8     \lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False}
9 msdemlei 5203 \usepackage{amsmath}
10 rplante@ncsa.uiuc.edu 1375
11 msdemlei 5160 \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 msdemlei 5051 \title{VODataService: A VOResource Schema Extension for Describing
24     Collections and Services}
25 rplante@ncsa.uiuc.edu 1375
26 msdemlei 5191 \ivoagroup{Registry}
27 rplante@ncsa.uiuc.edu 1375
28 msdemlei 5051 \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 rplante@ncsa.uiuc.edu 1375
40 msdemlei 5115 \editor{Markus Demleitner}
41 msdemlei 5051 \editor{Ray Plante}
42 rplante@ncsa.uiuc.edu 1375
43 msdemlei 5930 \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 msdemlei 5051 \previousversion[http://www.ivoa.net/Documents/VODataService/20101202]{REC
46     1.1}
47 rplante@ncsa.uiuc.edu 1375
48 msdemlei 5051 \begin{document}
49     \begin{abstract}
50 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5191 VOResource \citep{2018ivoa.spec.0625P} using XML Schema.
55 rplante@ncsa.uiuc.edu 1375 The specialized resource types defined by the VODataService schema
56     allow one to describe how the data underlying the resource cover the
57 msdemlei 5191 sky and the frequency and time axes.
58 msdemlei 5161 VODataService also enables detailed
59 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5051 \end{abstract}
64 rplante@ncsa.uiuc.edu 1375
65 msdemlei 5051 \section*{Acknowledgments}
66 rplante@ncsa.uiuc.edu 1375
67 msdemlei 5051 Versions 1.0 and 1.1 of this document have been developed with support from the
68     National Science Foundation's
69 rplante@ncsa.uiuc.edu 1375 Information Technology Research Program under Cooperative Agreement
70     AST0122449 with The Johns Hopkins University, from the
71 msdemlei 5051 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 rplante@ncsa.uiuc.edu 1375 via its
78 msdemlei 5051 eInfrastructure Science Repositories initiative.
79 rplante@ncsa.uiuc.edu 1375
80 msdemlei 5051 Version 1.2 of this document was developed in part with support from the
81 msdemlei 5165 German federal ministry for research and education's e-inf-astro project (BMBF
82     FKZ 05A17VH2).
83 rplante@ncsa.uiuc.edu 1375
84    
85 msdemlei 5051 \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 rplante@ncsa.uiuc.edu 1375 general term for a collection of federated resources that can be used
93     to conduct astronomical research, education, and outreach.
94 msdemlei 5051 The \href{http://www.ivoa.net}{International
95     Virtual Observatory Alliance (IVOA)} is a global
96 rplante@ncsa.uiuc.edu 1375 collaboration of separately funded projects to develop standards and
97     infrastructure that enable VO applications.
98    
99    
100 msdemlei 5051 \section*{Syntax Notation Using XML Schema}
101 rplante@ncsa.uiuc.edu 1375
102 msdemlei 5191 The eXtensible Markup Language, or XML, is a document syntax for marking
103 msdemlei 5051 textual information with named tags and is defined by \citet{std:XML}.
104     The set of XML tag names and the syntax
105 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5051 known as XML Schema \citep{std:XSD}.
108 rplante@ncsa.uiuc.edu 1375
109 msdemlei 5051 The XML Schemas of VODataService as well as VOResource and its other
110     extensions are
111 msdemlei 5499 available from the IVOA schema
112 msdemlei 5051 repository\footnote{\url{http://www.ivoa.net/xml}} at any time.
113 rplante@ncsa.uiuc.edu 1375 Parts of the schema appear within the main sections of this document;
114 msdemlei 5051 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 rplante@ncsa.uiuc.edu 1375
119     References to specific elements and types defined in the VOResource
120 msdemlei 5499 schema include the namespace prefix \xmlel{vr} as in
121 msdemlei 5191 \xmlel{vr:Resource} (a type defined in the VOResource schema).
122    
123 msdemlei 5051 \section{Introduction}
124 rplante@ncsa.uiuc.edu 1375
125 msdemlei 5115 The VOResource standard \citep{2018ivoa.spec.0625P} provides a means of
126 msdemlei 5161 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 msdemlei 5051 VOResource uses XML Schema \citep{std:XSD} to define
129 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5191 schema or other extensions.
135 rplante@ncsa.uiuc.edu 1375
136 msdemlei 5191 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 msdemlei 5509 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 msdemlei 5191
146 msdemlei 5509
147 msdemlei 5051 \subsection{The Role in the IVOA Architecture}
148 rplante@ncsa.uiuc.edu 1375
149 msdemlei 5061 \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 msdemlei 5191 Fig.~\ref{fig:archdiag} shows the role VODataService plays within the
157 msdemlei 5935 IVOA Architecture \citep{2010ivoa.rept.1123A}.
158 msdemlei 5061
159 msdemlei 5191 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 msdemlei 5061
163 msdemlei 5191 \begin{description}
164 msdemlei 5203 \item[VOResource, v1.1 \citep{2018ivoa.spec.0625P}] VOResource gives
165 msdemlei 5191 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 msdemlei 5499 from version 1 of the IVOA data model for Space-Time Coordinates. The
169 msdemlei 5191 updated mechanism has no such dependence any more.
170     \end{description}
171 msdemlei 5061
172 msdemlei 5191 VODataService is closely related to the following other VO standards:
173 rplante@ncsa.uiuc.edu 1375
174 msdemlei 5191 \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 msdemlei 5203 defines the ParamHTTP interface type currently used in the capabilities of most
178 msdemlei 5191 standard protocols.
179 msdemlei 5931 \item[RegTAP, v1.1 \citep{2019ivoa.spec.1011D}] RegTAP maps the concepts
180 msdemlei 5203 defined here into a relational structure. In that sense it is the
181 msdemlei 5931 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 msdemlei 5191 \end{description}
186    
187 msdemlei 5051 \subsection{Purpose}
188 rplante@ncsa.uiuc.edu 1375
189 msdemlei 5051
190 rplante@ncsa.uiuc.edu 1375 The purpose of this extension is to define common XML Schema
191 msdemlei 5203 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 rplante@ncsa.uiuc.edu 1375
201 msdemlei 5192 Resource records using VODataService types are commonly used to register
202 rplante@ncsa.uiuc.edu 1375 services that support standard IVOA data access layer protocols such
203 msdemlei 5056 as Simple Image Access \citep{2015ivoa.spec.1223D} and Simple Cone Search
204 msdemlei 5192 \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 rplante@ncsa.uiuc.edu 1375 define the protocol-specific metadata (encapsulated as a standard
209 msdemlei 5056 \emph{capability} from VOResource), the general service
210 msdemlei 5192 resource description shares the common data concepts such as
211 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5051
218    
219 msdemlei 5056 As a legal extension of VOResource, the use
220 rplante@ncsa.uiuc.edu 1375 of VODataService is subject to the rules and recommendations for XML
221 msdemlei 5056 \citep{std:XML}, XML Schema \citep{std:XSD},
222 rplante@ncsa.uiuc.edu 1375 and VOResource itself.
223    
224 msdemlei 5165 \subsection{Additional Use Cases for Version 1.2}
225 rplante@ncsa.uiuc.edu 1375
226 msdemlei 5165 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 msdemlei 5203 A few of the changes in version 1.2 are necessary for consistency with other standards
232 msdemlei 5165 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 msdemlei 5203 \paragraph{What services have data for the Crab nebula covering the
239     H$\boldsymbol\alpha$
240 msdemlei 5165 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 msdemlei 5203 which, however, was never properly standardised or widely adopted. In the current
243 msdemlei 5165 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 msdemlei 5501 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 msdemlei 5165
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 msdemlei 5499 the IVOA Note on discovering data collections \citep{2019ivoa.rept.0520D} for
261 msdemlei 5165 details. To better support the scheme proposed there, version 1.2 adds
262 msdemlei 5187 the \xmlel{vs:DataResource} and \xmlel{vs:CatalogResource} types
263     that identify a resource as data-like but
264 msdemlei 5509 permits the addition of various capabilities to the record (which
265 msdemlei 5165 \xmlel{vs:DataCollection} did not). An analogous use case would be
266 msdemlei 5187 ``Find all TAP services publishing tables from Gaia DR2''.
267 msdemlei 5165
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 msdemlei 5192 children, the ``large-scale'' part is much harder to operationalize.
271 msdemlei 5165 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 msdemlei 5509
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 msdemlei 5165 \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 msdemlei 5509 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 msdemlei 5165
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 msdemlei 5509 statistics like histograms and the percentage of NULL values.
297 msdemlei 5165
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 msdemlei 5509 in the Registry.
308 msdemlei 5165
309     \paragraph{Facilitate discovery of full DALI services.} The issue here
310     is that DALI forsees synchronous and asynchronous endpoints as the
311 msdemlei 5203 standard case for many protocols -- it already is standard for TAP.
312 msdemlei 5931 Also, several auxiliary endpoints (mostly defined in VOSI) are declared as
313 msdemlei 5509 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 msdemlei 5165
321    
322    
323 msdemlei 5051 \section{The VODataService Data Model}
324 msdemlei 5509 \label{sect:model}
325 msdemlei 5051
326    
327 rplante@ncsa.uiuc.edu 1375 The VODataService extension in general enables the description of two
328 msdemlei 5203 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 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5193 \lstinputlisting[language=XML,basicstyle=\footnotesize,numbers=left]{ipac-resource.xml}
341 rplante@ncsa.uiuc.edu 1375
342     This example illustrates some of the features of the VODataService
343     extension:
344 msdemlei 5051
345 msdemlei 5055 \begin{enumerate}
346 msdemlei 5193 \item The specific type of resource indicated by
347 msdemlei 5051 the value of the \xmlel{xsi:type} attribute; in this case
348     \xmlel{vs:CatalogService} indicates that this is
349 msdemlei 5193 describing a service that accesses tabular data (line 1).
350 msdemlei 5203 \item The extra namespace declaration for
351 msdemlei 5193 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 msdemlei 5115 VODataService type \xmlel{vs:ParamHTTP}; this
357 msdemlei 5193 type can indicate input arguments the service supports (line
358     40ff.)
359     \item A description of the
360 msdemlei 5112 coverage, including quantitative coverage
361 msdemlei 5193 plus waveband keywords (line 62ff.)
362     \item A description of the table that is returned
363     by the service (line 73ff.)
364 msdemlei 5055 \end{enumerate}
365 rplante@ncsa.uiuc.edu 1375
366 msdemlei 5051 \subsection{The Schema Namespace and Location}
367 rplante@ncsa.uiuc.edu 1375
368 msdemlei 5051
369 rplante@ncsa.uiuc.edu 1375 The namespace associated with VODataService extensions is
370 msdemlei 5051 $$\mbox{\texttt{http://www.ivoa.net/xml/VODataService/v1.1}}.$$
371 msdemlei 5155 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 msdemlei 5203 \verb|1.1| is also used for schema versions 1.2, 1.3, and so forth.
378 rplante@ncsa.uiuc.edu 1375
379 msdemlei 5155 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 msdemlei 5051
388 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5193 \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 rplante@ncsa.uiuc.edu 1375 recommends using the VODataService namespace URI as its location URL
395 msdemlei 5204 (as illustrated in the example above), as in
396     \begin{verbatim}
397 msdemlei 5051 xsi:schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1
398     http://www.ivoa.net/xml/VODataService/v1.1"
399 msdemlei 5204 \end{verbatim}
400 rplante@ncsa.uiuc.edu 1375
401 msdemlei 5155 The canonical prefix for VODataService is \xmlel{vs}; this means, in
402     particular, that in non-XML contexts (e.g., relational mappings
403 msdemlei 5193 like RegTAP) the VODataService types \emph{must} be qualified with
404 msdemlei 5509 vs:.
405 msdemlei 5155
406 msdemlei 5561 As recommended by the VOResource standard, the
407 msdemlei 5115 VODataService schema sets \xmlel{element\-Form\-Default} to \emph{unqualified}.
408 msdemlei 5155 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 msdemlei 5051 \xmlel{xsi:type} attribute.
413 rplante@ncsa.uiuc.edu 1375
414    
415 msdemlei 5051 \subsection{Summary of Metadata Concepts}
416     \label{sect:summ}
417    
418    
419 msdemlei 5187 VODataService defines several resource types and some auxiliary classes
420     necessary to describe resources of these new types.
421 rplante@ncsa.uiuc.edu 1375
422 msdemlei 5187 \subsubsection{Auxiliary Classes}
423 msdemlei 5051
424 msdemlei 5187 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 msdemlei 5931 (e.g., ``Optical''), and it can contain a link to a footprint endpoint and an
429 msdemlei 5187 indication of the spatial resolution within a service.
430 rplante@ncsa.uiuc.edu 1375
431 msdemlei 5187 VODataService has several classes for the declaration of the tabular
432 msdemlei 5204 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 msdemlei 5187 \xmlel{vs:TableSchema} instances. These have some very basic metadata
439     (name, title, description, utype) and otherwise contain \xmlel{vs:Table}
440 msdemlei 5193 instances. These in turn have simple metadata, but mainly give column
441 msdemlei 5187 metadata (including UCDs and units) in \xmlel{vs:TableParam}-typed
442 msdemlei 5193 children. These are the basis for enabling discovery queries like
443 msdemlei 5187 ``find all resources having redshifts and far infrared fluxes''.
444 rplante@ncsa.uiuc.edu 1375
445 msdemlei 5187 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 msdemlei 5499 sect.~\ref{sect:discoverdata}.
450 rplante@ncsa.uiuc.edu 1375
451 msdemlei 5193 VODataService further defines a specialized interface type
452 msdemlei 5187 (inheriting from \xmlel{vr:Interface}) called
453 msdemlei 5193 \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 msdemlei 5187 user interfaces from VOSI capabilities responses.
460 msdemlei 5051
461 msdemlei 5187 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 msdemlei 5931 \xmlel{vs:SimpleDataType} (for ParamHTTP parameters on non-DALI
466     interfaces) and
467 msdemlei 5187 \xmlel{vs:VOTableType} (for table columns) should be used.
468 rplante@ncsa.uiuc.edu 1375
469 msdemlei 5187 \subsubsection{VODataService Resource Classes}
470 rplante@ncsa.uiuc.edu 1375
471 msdemlei 5187 \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 msdemlei 5051
478 msdemlei 5204 While no common VO service discovery pattern relies on the XSD type of the
479 msdemlei 5187 resource,\footnote{Of course, in non-service discovery (e.g., authorities
480 msdemlei 5193 or standards), resource types are important.} resource
481     record authors should
482     nevertheless choose appropriate types for their resources. At the
483 msdemlei 5204 very least, this helps Registry maintenance.
484 rplante@ncsa.uiuc.edu 1375
485 msdemlei 5187 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 msdemlei 5193 example for this would be a collection of files on an FTP server. CatalogX,
491 msdemlei 5187 on the other hand, has an associated tableset. That does not mean that
492 msdemlei 5499 it is limited to what is conventionally thought of as a ``catalogue'',
493 msdemlei 5204 i.e., a table of data on astronomical objects. On the
494 msdemlei 5193 contrary, CatalogX should also be used for collections of images,
495 msdemlei 5187 spectra, time series, etc, as long as their metadata is sufficiently
496 msdemlei 5931 structured. That a data collection ist published through the standard
497     IVOA discovery protocols (ObsCore,
498     SIAP, SSAP) certainly is a strong indication that this requirement is
499     satisfied.
500 msdemlei 5051
501 msdemlei 5187 The horizontal distinction (XResource vs.~XService) is somewhat more
502 msdemlei 5499 subtle and will be discussed in sect.~\ref{sect:discoverdata}.
503 msdemlei 5051
504 msdemlei 5193 Two further resource classes defined VODataService 1.1,
505     \xmlel{vs:DataCollection} and \xmlel{vs:StandardSTC},
506     are deprecated in version 1.2.
507 msdemlei 5187 Resource record authors are requested to migrate or discard resource
508 msdemlei 5193 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 rplante@ncsa.uiuc.edu 1375
512 msdemlei 5499 \subsubsection{Discovering Data Within Other Services}
513 msdemlei 5509 \label{sect:discoverdata}
514 msdemlei 5051
515 msdemlei 5499 The content models of CatalogResource and CatalogService are identical.
516     To understand why the two classes are present nevertheless, a short
517 msdemlei 5561 historical excursion is in order. A full treatment of this is found in
518 msdemlei 5499 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 msdemlei 5051 \section{The VODataService Metadata}
612     \label{sect:metadata}
613    
614    
615 rplante@ncsa.uiuc.edu 1375 This section enumerates the types and elements defined in the
616 msdemlei 5509 VODataService extension schema and describes their meaning.
617 rplante@ncsa.uiuc.edu 1375
618    
619 msdemlei 5194 \subsection{VODataService Resource Types}
620 msdemlei 5051 \label{sect:resext}
621 rplante@ncsa.uiuc.edu 1375
622 msdemlei 5187 \subsubsection{DataResource}
623     \label{sect:DataResource}
624 msdemlei 5051
625 msdemlei 5509 The \xmlel{vs:DataResource} resource type is used to describe a
626 msdemlei 5187 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 msdemlei 5509 astronomical catalogues) should use \xmlel{vs:CatalogResource}.
631 msdemlei 5051
632 msdemlei 5193 The type is derived from \xmlel{vr:Service}, which means that instances
633     can have
634 msdemlei 5187 capabilities. For \xmlel{vs:DataResource}, only auxiliary capabilities
635 msdemlei 5204 (e.g., DataServices serving multiple DataResources) or plain capabilities
636 msdemlei 5187 with \xmlel{vr:WebBrowser} interfaces should be given. Resources with a
637 msdemlei 5193 primary access mode dedicated to the resource's data content should use
638 msdemlei 5187 \xmlel{vs:DataService}-typed resources.
639 rplante@ncsa.uiuc.edu 1375
640 msdemlei 5193 In addition to \xmlel{vr:Service}'s content, DataResource adds
641     elements for declaring the observing facilities and/or instruments used
642 msdemlei 5509 to obtain the data, and it supports the declaration of
643     the physical coverage of data via the \xmlel{coverage}
644 msdemlei 5193 element.
645 rplante@ncsa.uiuc.edu 1375
646 msdemlei 5187 % GENERATED: !schemadoc VODataService-v1.2.xsd DataResource
647 msdemlei 5193 \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 msdemlei 5204 common underlying tabular schema (e.g., an inhomogeneous archive).
659 msdemlei 5193 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 msdemlei 5509 The observatory or facility used to collect the data
687 msdemlei 5193 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 msdemlei 5509 The instrument used to collect the data contain or
697 msdemlei 5193 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 msdemlei 5187 % /GENERATED
720 rplante@ncsa.uiuc.edu 1375
721 msdemlei 5187 \subsubsection{DataService}
722 msdemlei 5057
723 msdemlei 5187 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 msdemlei 5193 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 msdemlei 5187 metadata should pertain to the service itself rather than any specific
730     data collection served by it.
731 msdemlei 5057
732 msdemlei 5509 As with \xmlel{vs:CatalogResource}, instances SHOULD
733 msdemlei 5561 declare the metadata of the table(s) underlying the service or
734 msdemlei 5509 delivered by it in a \xmlel{tableset} element.
735    
736 msdemlei 5204 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 msdemlei 5057
741 msdemlei 5193 DataService's content model is exactly the one of
742 msdemlei 5509 \xmlel{vs:DataResource}; please refer to sect.~\ref{sect:DataResource}
743     for the motivation of this duplication.
744 msdemlei 5057
745    
746    
747    
748 msdemlei 5187 \subsubsection{CatalogResource}
749     \label{sect:CatalogResource}
750 msdemlei 5057
751    
752 msdemlei 5931 The \xmlel{vs:CatalogResource} resource type is used to describe a
753 msdemlei 5187 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 msdemlei 5509 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 msdemlei 5057
760 msdemlei 5187 As with \xmlel{vs:DataResource}, this type should only be used if all
761     capabilities declared in the resource are either auxiliary or
762 msdemlei 5509 nonstandard. This is typically the case for catalogues or data
763 msdemlei 5204 collections within larger TAP, ObsTAP, or perhaps SIAP services. When
764 msdemlei 5193 a service only publishes a single resource, use the
765     \xmlel{vs:CatalogService} type.
766 msdemlei 5057
767    
768 msdemlei 5187 % GENERATED: !schemadoc VODataService-v1.2.xsd CatalogResource
769 msdemlei 5057 \begin{generated}
770     \begingroup
771     \renewcommand*\descriptionlabel[1]{%
772 msdemlei 5193 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vs:CatalogResource} Type Schema Documentation}
773 msdemlei 5057
774     \noindent{\small
775 msdemlei 5193 A resource giving astronomical data in tabular form.
776 msdemlei 5057 \par}
777    
778     \noindent{\small
779 msdemlei 5509 While this includes classical astronomical catalogues,
780 msdemlei 5193 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 msdemlei 5057 \par}
784    
785 msdemlei 5193 \vspace{1ex}\noindent\textbf{\xmlel{vs:CatalogResource} Type Schema Definition}
786 msdemlei 5057
787     \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
788 msdemlei 5193 <xs:complexType name="CatalogResource" >
789 msdemlei 5057 <xs:complexContent >
790 msdemlei 5193 <xs:extension base="vs:DataResource" >
791 msdemlei 5057 <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 msdemlei 5193 \vspace{0.5ex}\noindent\textbf{\xmlel{vs:CatalogResource} Extension Metadata Elements}
809 msdemlei 5057
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 msdemlei 5051 % /GENERATED
832 rplante@ncsa.uiuc.edu 1375
833 msdemlei 5187
834     \subsubsection{CatalogService}
835    
836 msdemlei 5509 The \xmlel{vs:CatalogService} resource type is used to describe a
837 msdemlei 5187 service publishing astronomical data or metadata based on tabular
838 msdemlei 5193 representations. Its relationship to \xmlel{vs:CatalogResource}
839     is as between \xmlel{vs:DataResource}
840 msdemlei 5187 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 msdemlei 5204 This is the type that should be used for one-resource VO
848 msdemlei 5187 services.
849    
850 msdemlei 5193 CatalogService's content model is exactly the one of
851 msdemlei 5509 \xmlel{vs:CatalogResource}; please refer to sect.~\ref{sect:CatalogResource}
852     for the motivation of this duplication.
853 msdemlei 5187
854     \subsubsection{DataCollection}
855     \label{sect:datacollection}
856    
857     The \xmlel{vs:DataCollection} type is deprecated and should no longer be
858 msdemlei 5193 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 msdemlei 5204 records should be migrated to records of type \xmlel{vs:DataResource} or
867 msdemlei 5193 \xmlel{vs:CatalogResource} as appropriate. If \xmlel{accessURL}
868     children are present in the
869 msdemlei 5204 \xmlel{vs:DataCollection}\/s,
870 msdemlei 5193 they can be replaced with a plain capability with a
871 msdemlei 5187 \xmlel{vr:WebBrowser}-typed interface.
872    
873 msdemlei 5193 This type may be removed from the schema when all resource records using
874     it have vanished from the VO Registry.
875 msdemlei 5187
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 msdemlei 5193 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 msdemlei 5187
885 msdemlei 5191
886    
887 msdemlei 5187 \subsection{Coverage in Space, Time, and Spectrum}
888 msdemlei 5191 \label{sect:cover}
889 msdemlei 5187
890 msdemlei 5112 The \xmlel{vs:Coverage} type summarily describes how the data served is
891     distributed on the
892 msdemlei 5867 sky, in energy, and in time.
893 rplante@ncsa.uiuc.edu 1375
894 msdemlei 5867 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 msdemlei 5112 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 msdemlei 5194 and the underlying standard, STC-X \citep{note:stcx}, never proceeded to become
906 msdemlei 5112 a recommendation. Hence, this version of VODataService deprecates the
907     use of \xmlel{STCResourceProfile}.
908 rplante@ncsa.uiuc.edu 1375
909 msdemlei 5112 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 rplante@ncsa.uiuc.edu 1375
913 msdemlei 5112 Spatial coverage is conveyed as a MOC. To enable easy embedding into
914     resource records written in VOResource (i.e., XML),
915 msdemlei 5931 VODataService uses the string serialisation defined in section 2.3.2 of
916     \citet{2019ivoa.spec.1007F}.
917 msdemlei 5112
918 msdemlei 5509 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 msdemlei 5204 ICRS. If a resource's native coordinates are given for another frame (e.g.,
923 msdemlei 5194 Galactic or FK4 for some equinox), it is the resource record author's
924     responsibility to convert the spatial coverage into the ICRS.
925 msdemlei 5112
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 msdemlei 5192 significant increase of the size of the serialized MOC. We suggest a
930 msdemlei 5112 ``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 msdemlei 5930 \nolinkurl{ivo://ivoa.net/std/moc} to declare a URL giving a
938 msdemlei 5510 footprint in one of the approved MOC serialisations and of arbitrary
939     level and size.
940 msdemlei 5112
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 msdemlei 5204 uses wavelengths of electromagnetic waves in vacuum), spectral limits are
958 msdemlei 5194 given in Joules of messenger energy. This is intended to allow seamless
959 msdemlei 5112 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 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd Coverage
967 msdemlei 5057 \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 msdemlei 5501 <xs:element name="spatial" type="vs:SpatialCoverage" minOccurs="0" />
985 msdemlei 5160 <xs:element name="temporal" type="vs:FloatInterval" minOccurs="0"
986 msdemlei 5112 maxOccurs="unbounded" />
987 msdemlei 5160 <xs:element name="spectral" type="vs:FloatInterval" minOccurs="0"
988 msdemlei 5112 maxOccurs="unbounded" />
989 msdemlei 5057 <xs:element name="footprint" type="vs:ServiceReference" minOccurs="0" />
990 msdemlei 5867 <xs:element name="waveband" type="xs:token" minOccurs="0"
991 msdemlei 5057 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 msdemlei 5565 \begingroup\small\begin{bigdescription}\item[Element \xmlel{stc:STCResourceProfile}]
1000    
1001 msdemlei 5112 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 msdemlei 5057
1006 msdemlei 5112
1007 msdemlei 5565 This element is imported from another schema. See
1008     there for details.\item[Element \xmlel{spatial}]
1009 msdemlei 5112 \begin{description}
1010 msdemlei 5501 \item[Type] a string with optional attributes
1011 msdemlei 5112 \item[Meaning]
1012 msdemlei 5192 An ASCII-serialized MOC defining the spatial coverage
1013 msdemlei 5112 of the resource.
1014    
1015     \item[Occurrence] optional
1016 msdemlei 5057 \item[Comment]
1017 msdemlei 5509 The MOC is to be understood in the ICRS reference frame
1018     unless a frame attribute is given.
1019 msdemlei 5112 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 msdemlei 5057
1025    
1026     \end{description}
1027 msdemlei 5112 \item[Element \xmlel{temporal}]
1028     \begin{description}
1029 msdemlei 5186 \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 msdemlei 5112 \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 msdemlei 5160
1036 msdemlei 5112 \item[Comment]
1037     This is written as for VOTable tabledata (i.e.,
1038 msdemlei 5565 whitespace-separated C-style floating point literals), as
1039     in “47847.2 51370.2”.
1040 msdemlei 5112 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 msdemlei 5186 \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 msdemlei 5112 \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 msdemlei 5160
1056 msdemlei 5112 \item[Comment]
1057     This is written as for VOTable tabledata (i.e.,
1058 msdemlei 5509 whitespace-separated C-style floating point literals).
1059 msdemlei 5112 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 msdemlei 5186 would be specified as “2.72e-19 4.14e-19”
1067 msdemlei 5112
1068    
1069     \end{description}
1070 msdemlei 5057 \item[Element \xmlel{footprint}]
1071     \begin{description}
1072     \item[Type] a URI with optional attributes
1073     \item[Meaning]
1074 msdemlei 5509 A reference to a footprint service for retrieving
1075 msdemlei 5057 precise and up-to-date description of coverage.
1076    
1077     \item[Occurrence] optional
1078     \item[Comment]
1079 msdemlei 5510 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 msdemlei 5057
1088    
1089     \end{description}
1090     \item[Element \xmlel{waveband}]
1091     \begin{description}
1092 msdemlei 5867 \item[Type] string: \xmlel{xs:token}
1093 msdemlei 5057 \item[Meaning]
1094 msdemlei 5867 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 msdemlei 5057
1099     \item[Occurrence] optional; multiple occurrences allowed.
1100 msdemlei 5509 \item[Comment]
1101 msdemlei 5867 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 msdemlei 5509
1107 msdemlei 5057
1108     \end{description}
1109     \item[Element \xmlel{regionOfRegard}]
1110     \begin{description}
1111     \item[Type] floating-point number: \xmlel{xs:float}
1112     \item[Meaning]
1113 msdemlei 5509 A single numeric value representing the angle, given
1114 msdemlei 5057 in decimal degrees, by which a positional query
1115 msdemlei 5156 against this resource should be “blurred” in order
1116 msdemlei 5057 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 msdemlei 5509 of object catalogues RoR should normally be the
1124 msdemlei 5057 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 msdemlei 5051 % /GENERATED
1138 rplante@ncsa.uiuc.edu 1375
1139 msdemlei 5501 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 msdemlei 5187
1145    
1146 msdemlei 5501 % 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 msdemlei 5051 \subsection{Tabular Data}
1199     \label{sect:table}
1200 rplante@ncsa.uiuc.edu 1375
1201 msdemlei 5051
1202     The \xmlel{vs:TableSet} type can be used
1203 rplante@ncsa.uiuc.edu 1375 to describe a set of tables that are part of a single resource and can
1204 msdemlei 5121 be considered functionally all located at a single site. While there is
1205 msdemlei 5194 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 msdemlei 5121 tables.
1209 rplante@ncsa.uiuc.edu 1375
1210    
1211    
1212 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd TableSet
1213 msdemlei 5057 \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 msdemlei 5195 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 msdemlei 5057 </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 msdemlei 5509 A named description of a group of logically related tables.
1246 msdemlei 5057
1247     \item[Occurrence] required; multiple occurrences allowed.
1248     \item[Comment]
1249 msdemlei 5156 The name given by the “name” child element must
1250 msdemlei 5057 be unique within this TableSet instance. If there is
1251 msdemlei 5509 only one schema in this set and/or there is no locally
1252 msdemlei 5057 appropriate name to provide, the name can be set to
1253 msdemlei 5156 “default”.
1254 msdemlei 5057
1255     \item[Comment]
1256     This aggregation does not need to map to an
1257 msdemlei 5509 actual database, catalogue, or schema, though the
1258 msdemlei 5057 publisher may choose to aggregate along such
1259 msdemlei 5509 designations. Particular service protocols may
1260     require stricter patterns.
1261 msdemlei 5057
1262    
1263     \end{description}
1264    
1265    
1266     \end{bigdescription}\endgroup
1267    
1268     \endgroup
1269     \end{generated}
1270    
1271 msdemlei 5051 % /GENERATED
1272 rplante@ncsa.uiuc.edu 1375
1273 msdemlei 5051
1274 msdemlei 5509 The \xmlel{vs:TableSchema} type groups
1275     tables that are logically related.
1276 msdemlei 5194 For example, a single
1277 msdemlei 5561 resource may provide access to several major astronomical catalogues
1278 msdemlei 5509 (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 msdemlei 5051 separate \xmlel{schema} element, using the elements from
1281 msdemlei 5930 the \xmlel{vs:TableSchema} type.
1282 rplante@ncsa.uiuc.edu 1375
1283    
1284 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd TableSchema
1285 msdemlei 5057 \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 msdemlei 5509 A detailed description of a logically related group of tables.
1292 msdemlei 5057 \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 msdemlei 5509 A name for the group of tables.
1318 msdemlei 5057
1319     \item[Occurrence] required
1320     \item[Comment]
1321 msdemlei 5509 This is used to uniquely identify the group of tables among
1322     several groups. If no title is given, this
1323 msdemlei 5057 name can be used for display purposes.
1324    
1325     \item[Comment]
1326     If there is no appropriate logical name associated with
1327 msdemlei 5509 this group, the name should be explicitly set to
1328 msdemlei 5156 “default”.
1329 msdemlei 5057
1330    
1331     \end{description}
1332     \item[Element \xmlel{title}]
1333     \begin{description}
1334     \item[Type] string: \xmlel{xs:token}
1335     \item[Meaning]
1336 msdemlei 5509 A descriptive, human-interpretable name for the group of
1337     tables.
1338 msdemlei 5057
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 msdemlei 5156 multiple schemas in the context (e.g., within a
1344 msdemlei 5057 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 msdemlei 5509 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 msdemlei 5057
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 msdemlei 5509 An identifier for a concept in a data model that
1365 msdemlei 5057 the data in this schema as a whole represent.
1366    
1367     \item[Occurrence] optional
1368     \item[Comment]
1369 msdemlei 5184 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 msdemlei 5057
1373    
1374     \end{description}
1375     \item[Element \xmlel{table}]
1376     \begin{description}
1377     \item[Type] composite: \xmlel{vs:Table}
1378     \item[Meaning]
1379 msdemlei 5509 A description of one table.
1380 msdemlei 5057
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 msdemlei 5051 % /GENERATED
1392 rplante@ncsa.uiuc.edu 1375
1393    
1394 msdemlei 5051 Each table in a schema is described in detail using the
1395     \xmlel{vs:Table} type.
1396 rplante@ncsa.uiuc.edu 1375
1397    
1398    
1399 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd Table
1400 msdemlei 5057 \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 msdemlei 5930 <xs:element name="nrows" type="xs:nonNegativeInteger" minOccurs="0"
1413 msdemlei 5121 maxOccurs="1" />
1414 msdemlei 5057 <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 msdemlei 5509 A name for the role this table plays. Recognized
1432 msdemlei 5156 values include “output”, indicating this table is output
1433 msdemlei 5930 from a query; “base\_table”, indicating a table
1434 msdemlei 5057 whose records represent the main subjects of its
1435 msdemlei 5156 schema; and “view”, indicating that the table represents
1436 msdemlei 5057 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 msdemlei 5509 The fully qualified name of the table. This name
1454     should include all catalogue or schema prefixes
1455 msdemlei 5057 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 msdemlei 5509 catalogue and schema qualifiers are delimited from the
1464 msdemlei 5057 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 msdemlei 5509 A descriptive, human-interpretable name for the table.
1473 msdemlei 5057
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 msdemlei 5509 A free-text description of the table's contents
1486 msdemlei 5057
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 msdemlei 5509 An identifier for a concept in a data model that
1495 msdemlei 5057 the data in this table represent.
1496    
1497     \item[Occurrence] optional
1498     \item[Comment]
1499 msdemlei 5184 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 msdemlei 5057
1503    
1504     \end{description}
1505 msdemlei 5121 \item[Element \xmlel{nrows}]
1506     \begin{description}
1507 msdemlei 5930 \item[Type] \xmlel{xs:nonNegativeInteger}
1508 msdemlei 5121 \item[Meaning]
1509 msdemlei 5509 The size of the table in rows.
1510 msdemlei 5121
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 msdemlei 5057 \item[Element \xmlel{column}]
1520     \begin{description}
1521     \item[Type] composite: \xmlel{vs:TableParam}
1522     \item[Meaning]
1523 msdemlei 5509 A description of a table column.
1524 msdemlei 5057
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 msdemlei 5509 A description of a foreign keys, one or more columns
1533 msdemlei 5057 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 msdemlei 5051 % /GENERATED
1547 rplante@ncsa.uiuc.edu 1375
1548    
1549    
1550    
1551     Each column in a table can be described using the
1552 msdemlei 5051 \xmlel{vs:TableParam} type which is described in
1553     section~\ref{sect:param}. The foreign keys in the table that
1554 rplante@ncsa.uiuc.edu 1375 can be used to join it with another table can be described with the
1555 msdemlei 5051 \xmlel{vs:ForeignKey} type (section~\ref{sect:fkey}).
1556 rplante@ncsa.uiuc.edu 1375 A foreign key description should only refer to tables described within
1557     the current table set.
1558    
1559 msdemlei 5194 When the table set describes a set of TAP-accessible tables, the value of
1560 msdemlei 5160 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 msdemlei 5194 requirement for \tapschema. This means that all qualifications (schema,
1563 msdemlei 5509 catalogue) must be present, but also that when delimited
1564 msdemlei 5194 identifiers are used as table names on the relational side,
1565     the quotes must be part of \xmlel{name}'s value, and the
1566 msdemlei 5160 capitalisation used in the DDL must be preserved.
1567 rplante@ncsa.uiuc.edu 1375
1568    
1569 msdemlei 5051 The \xmlel{vs:Table} also provides an attribute for indicating
1570     the role a table plays in the schema.
1571 rplante@ncsa.uiuc.edu 1375
1572    
1573    
1574    
1575    
1576 msdemlei 5051 \subsubsection{Unique Names for Tables}
1577     \label{sect:unique}
1578 rplante@ncsa.uiuc.edu 1375
1579 msdemlei 5051
1580     The definitions of the \xmlel{tableset} elements used in
1581     the \xmlel{vs:DataCollection} and
1582 msdemlei 5115 \xmlel{vs:Catalog\-Ser\-vice} types
1583 rplante@ncsa.uiuc.edu 1375 constrain certain names to be unique. In particular, all schema names
1584 msdemlei 5051 within a \xmlel{tableset} element must be unique, and all
1585 msdemlei 5194 table names within a \xmlel{schema} element must be
1586 msdemlei 5509 unique. A schema and table may share a common name, such as
1587     ``default''. These constraints make it possible to uniquely locate
1588 rplante@ncsa.uiuc.edu 1375 the description of a schema or table within a VOResource description.
1589    
1590    
1591 msdemlei 5051 \subsubsection{Foreign Keys}
1592     \label{sect:fkey}
1593    
1594    
1595 msdemlei 5509 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 rplante@ncsa.uiuc.edu 1375 table. A foreign key is a set of columns that map to a corresponding
1598     set of columns in another table.
1599    
1600    
1601 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd ForeignKey
1602 msdemlei 5057 \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 msdemlei 5509 A description of the mapping a foreign key -- a set of
1609     columns from one table -- to columns in another table.
1610 msdemlei 5057 \par}
1611    
1612     \noindent{\small
1613 msdemlei 5509 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 msdemlei 5057 \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 msdemlei 5509 The fully qualified name (including catalogue and schema, as
1639 msdemlei 5057 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 msdemlei 5509 A pair of column names, one from this table and one
1650 msdemlei 5057 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 msdemlei 5509 A free-text description of what this key points to
1661 msdemlei 5057 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 msdemlei 5509 An identifier for a concept in a data model that
1671 msdemlei 5057 the association enabled by this key represents.
1672    
1673     \item[Occurrence] optional
1674     \item[Comment]
1675 msdemlei 5184 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 msdemlei 5057
1679    
1680     \end{description}
1681    
1682    
1683     \end{bigdescription}\endgroup
1684    
1685     \endgroup
1686     \end{generated}
1687    
1688 msdemlei 5051 % /GENERATED
1689    
1690    
1691 rplante@ncsa.uiuc.edu 1375 In this model, the source of the foreign
1692 msdemlei 5509 key is the current table being described (i.e., represented by the
1693 msdemlei 5051 \xmlel{table} element that contains the
1694     \xmlel{vs:ForeignKey} description, and thus does not need to be
1695 rplante@ncsa.uiuc.edu 1375 named explicitly). The key that is described points to the table
1696 msdemlei 5051 given by the \xmlel{targetTable} child element. Each child
1697     \xmlel{fkColumn} element then gives a pair of columns, one
1698 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5051 \subsubsection{Extending Table Metadata}
1707     \label{sect:tblext}
1708 rplante@ncsa.uiuc.edu 1375
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 msdemlei 5055 \begin{enumerate}
1716 msdemlei 5051 \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 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5056 \citep{std:XSD} and the VOResource specification.
1724 rplante@ncsa.uiuc.edu 1375
1725 msdemlei 5051 \item Apply a globally-defined attribute from a schema other than
1726 rplante@ncsa.uiuc.edu 1375 VODataService (i.e. from a namespace other than
1727 msdemlei 5195 \url{http://www.ivoa.net/xml/VODataService/v1.1}) to any of the
1728 msdemlei 5051 \xmlel{tableset}, \xmlel{schema},
1729     \xmlel{table}, and/or \xmlel{column}
1730     elements.
1731 rplante@ncsa.uiuc.edu 1375
1732 msdemlei 5051 \item When the extended metadata is specific to how the table data is
1733 rplante@ncsa.uiuc.edu 1375 accessed via a particular service protocol, then the new
1734 msdemlei 5051 metadata can be incorporated into a specific capability
1735 msdemlei 5056 extension (as described in the VOResource specification).
1736     This extension may make use of the
1737 msdemlei 5051 various names within the \xmlel{tableset} to
1738     indicate where the extension metadata apply.
1739 rplante@ncsa.uiuc.edu 1375
1740 msdemlei 5051 \item Use the \xmlel{extendedType} attribute of the
1741     \xmlel{dataType} element (see
1742 msdemlei 5509 section~\ref{sect:tbldatatypes})
1743 rplante@ncsa.uiuc.edu 1375 to indicate a more specific data type then those defined by the
1744 msdemlei 5051 \xmlel{vs:TableParam} type.
1745 msdemlei 5055 \end{enumerate}
1746 rplante@ncsa.uiuc.edu 1375
1747 msdemlei 5051 \subsection{Interface Type Extension: ParamHTTP}
1748     \label{sect:paramif}
1749 rplante@ncsa.uiuc.edu 1375
1750 msdemlei 5051
1751     The \xmlel{vs:ParamHTTP} type is a specialized service interface
1752     description that extends the VOResource \xmlel{vr:Interface} type
1753 msdemlei 5056 (as recommended by VOResource 1.1, section 2.2). It
1754 msdemlei 5195 describes a service interface that is invoked over HTTP via a GET or a
1755 msdemlei 5056 POST in which the inputs are parameters
1756 msdemlei 5195 encoded in multipart/form-data or application/x-www-form-urlencoded
1757     containers.
1758 rplante@ncsa.uiuc.edu 1375
1759 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd ParamHTTP
1760 msdemlei 5057 \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 msdemlei 5509 the service/referenceURL element.
1773 msdemlei 5057 \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 msdemlei 5509 maxOccurs="1" />
1790 msdemlei 5057 </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 msdemlei 5930 \item[Terms]\hfil
1807 msdemlei 5057 \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 msdemlei 5509 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 msdemlei 5057
1820    
1821     \end{description}
1822     \item[Element \xmlel{resultType}]
1823     \begin{description}
1824     \item[Type] string: \xmlel{xs:token}
1825     \item[Meaning]
1826 msdemlei 5509 The MIME media type of a document returned in
1827     the HTTP response.
1828 msdemlei 5057
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 msdemlei 5509 A description of a input parameter that can be
1837 msdemlei 5057 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 msdemlei 5509 An ampersand-delimited list of arguments that
1847 msdemlei 5057 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 msdemlei 5509 \item[Occurrence] optional
1852 msdemlei 5057 \item[Comment]
1853     When the interface supports GET, then the full
1854 msdemlei 5509 query URL is formed by the concatenation of the
1855 msdemlei 5057 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 msdemlei 5051 % /GENERATED
1868 rplante@ncsa.uiuc.edu 1375
1869     The extension metadata defined in the schema definition above are all
1870 msdemlei 5051 optional. Nevertheless, even when an \xmlel{interface}
1871 rplante@ncsa.uiuc.edu 1375 instance does not include any of these extended child elements, the
1872 msdemlei 5051 use of \verb|xsi:type="vs:ParamHTTP"| indicates that the interface
1873     accessed via the URL given by the \xmlel{accessURL}
1874 rplante@ncsa.uiuc.edu 1375 element complies with the general parameter-based protocol described
1875 msdemlei 5930 in this section.
1876 rplante@ncsa.uiuc.edu 1375
1877 msdemlei 5930 % resultType stinks when we have DALI RESPONSEFORMAT. Let's think
1878     % about fixing this in 1.3.
1879 rplante@ncsa.uiuc.edu 1375
1880 msdemlei 5051
1881    
1882    
1883    
1884 msdemlei 5930
1885 msdemlei 5509 An important intended use of the \xmlel{vs:ParamHTTP} type is
1886 rplante@ncsa.uiuc.edu 1375 describing the interface of an IVOA standard service protocol
1887 msdemlei 5051 of the ``simple'' variety, such as the Simple Image Access Protocol
1888 msdemlei 5056 \citep{2015ivoa.spec.1223D}. In particular, it is recommended that
1889 rplante@ncsa.uiuc.edu 1375 specifications that define how a standard service is registered in a
1890 msdemlei 5051 registry \emph{require} the use of the \xmlel{vs:ParamHTTP}
1891 rplante@ncsa.uiuc.edu 1375 interface type when it is applicable.
1892    
1893 msdemlei 5051
1894    
1895 rplante@ncsa.uiuc.edu 1375 Normally, a VOResource
1896     description indicates its support for a standard protocol with
1897 msdemlei 5051 \xmlel{capability} element having a
1898     \xmlel{standardID} attribute set to specific URI representing the
1899 rplante@ncsa.uiuc.edu 1375 standard. The standard will usually spell out the HTTP query type,
1900 msdemlei 5051 the returned media type, and input parameters required for compliance;
1901     therefore, it is not necessary that the \xmlel{vs:ParamHTTP}
1902 rplante@ncsa.uiuc.edu 1375 description provide any of the optional extended metadata, as they are
1903 msdemlei 5051 already implied by the \xmlel{standardID}. The description need
1904 rplante@ncsa.uiuc.edu 1375 only reflect the optional or locally unique features of the
1905     interface. In particular, description may include
1906    
1907 msdemlei 5051
1908     \begin{itemize}
1909     \item a \xmlel{queryType} element for a type that is not
1910 rplante@ncsa.uiuc.edu 1375 required by the standard (as long as the required query type is
1911 msdemlei 5051 supported as well),
1912 rplante@ncsa.uiuc.edu 1375
1913 msdemlei 5160 \item \xmlel{param}\/ elements for any optional parameters
1914 msdemlei 5051 or local extended parameters (when allowed by the standard).
1915     \end{itemize}
1916 rplante@ncsa.uiuc.edu 1375
1917 msdemlei 5051
1918 msdemlei 5509 Listing required parameters is allowed, even when
1919 rplante@ncsa.uiuc.edu 1375 describing a standard interface as long as these are consistent with
1920 msdemlei 5051 the service specification and the corresponding \xmlel{param}
1921 msdemlei 5509 elements include the attribute \verb|std="true"| (see
1922     section~\ref{sect:inputparam}). The \xmlel{param}
1923 rplante@ncsa.uiuc.edu 1375 elements for custom parameters that are not part of the standard (but
1924     are rather local customizations) should include the attribute
1925 msdemlei 5051 \verb|std="false"|.
1926 rplante@ncsa.uiuc.edu 1375
1927    
1928    
1929    
1930    
1931 msdemlei 5051 \subsection{Data Parameters}
1932     \label{sect:param}
1933    
1934    
1935 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5509 types describe a parameter in terms of elementary metadata
1939     including name, data type, and meaning.
1940 rplante@ncsa.uiuc.edu 1375
1941 msdemlei 5051
1942 msdemlei 5204 All the VODataService parameter types derive from the base type
1943 msdemlei 5051 \xmlel{vs:BaseParam} which defines all the common parameter
1944 rplante@ncsa.uiuc.edu 1375 metadata except the data type.
1945    
1946    
1947 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd BaseParam
1948 msdemlei 5057 \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 msdemlei 5509 A description of a parameter that places no restriction on
1955 msdemlei 5057 the parameter's data type.
1956     \par}
1957    
1958     \noindent{\small
1959     As the parameter's data type is usually important, schemas
1960 msdemlei 5509 normally employ a sub-class of this type
1961 msdemlei 5057 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 msdemlei 5509 The name of the parameter or column.
1986 msdemlei 5057
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 msdemlei 5509 A free-text description of a parameter's or column's
1995     contents.
1996 msdemlei 5057
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 msdemlei 5509 The unit associated with the values in the parameter
2005     or column.
2006 msdemlei 5057
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 msdemlei 5509 The name of a unified content descriptor that
2015     describes the scientific content of the parameter.
2016 msdemlei 5057
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 msdemlei 5930 SIA-UCD.
2023 msdemlei 5057
2024    
2025     \end{description}
2026     \item[Element \xmlel{utype}]
2027     \begin{description}
2028     \item[Type] string: \xmlel{xs:token}
2029     \item[Meaning]
2030 msdemlei 5509 An identifier for a concept in a data model that
2031 msdemlei 5057 the data in this schema represent.
2032    
2033     \item[Occurrence] optional
2034     \item[Comment]
2035 msdemlei 5184 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 msdemlei 5057
2039    
2040     \end{description}
2041    
2042    
2043     \end{bigdescription}\endgroup
2044    
2045     \endgroup
2046     \end{generated}
2047    
2048 msdemlei 5051 % /GENERATED
2049 rplante@ncsa.uiuc.edu 1375
2050 msdemlei 5051 Leaving the data type metadatum out of \xmlel{vs:BaseParam}
2051 rplante@ncsa.uiuc.edu 1375 allows the different kinds of parameters derived from
2052 msdemlei 5051 \xmlel{vs:BaseParam} to restrict the allowed data types to
2053 rplante@ncsa.uiuc.edu 1375 specific sets. The subsections below describe the different data
2054     types associated with input parameters
2055 msdemlei 5051 (\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 rplante@ncsa.uiuc.edu 1375
2060    
2061 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd DataType
2062 msdemlei 5057 \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 msdemlei 5509 A type (in the computer language sense) associated with a
2069 msdemlei 5057 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 msdemlei 5151 <xs:attribute name="arraysize" type="vs:ArrayShape" />
2084 msdemlei 5195 <xs:attribute name="delim" type="xs:string" />
2085 msdemlei 5057 <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 msdemlei 5184 \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}
2099 msdemlei 5057 \item[Meaning]
2100 msdemlei 5509 The shape of the array that constitutes the value.
2101 msdemlei 5057
2102     \item[Occurrence] optional
2103    
2104     \item[Comment]
2105 msdemlei 5151 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 msdemlei 5057
2111     \end{description}
2112     \item[delim]
2113     \begin{description}
2114     \item[Type] string: \xmlel{xs:string}
2115     \item[Meaning]
2116 msdemlei 5509 A string that is used to delimit elements of an array
2117 msdemlei 5197 value in InputParams.
2118 msdemlei 5057
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 msdemlei 5156 the delimiter (e.g., “1, 5” when delim=“,”).
2125 msdemlei 5057
2126     \item[Comment]
2127 msdemlei 5195 This should not be used for VOTable types; there,
2128     VOTable (typcially TABLEDATA) conventions for writing
2129     arrays are binding.
2130 msdemlei 5057
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 msdemlei 5153 type. extendedTypes without an extendedSchema
2151     mean VOTable xtypes as defined by DALI.
2152 msdemlei 5057
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 msdemlei 5153 extendedType attribute is not present. A missing
2165     extendedSchema indicates that extendedType is a
2166     VOTable xtype.
2167 msdemlei 5057
2168     \end{description}
2169    
2170    
2171     \end{bigdescription}\endgroup
2172    
2173     \endgroup
2174     \end{generated}
2175    
2176 msdemlei 5051 % /GENERATED
2177    
2178     The content of an element of type \xmlel{vs:DataType} is the name
2179 rplante@ncsa.uiuc.edu 1375 of the data type for the current parameter. When the element is explicitly
2180 msdemlei 5051 a \xmlel{vs:DataType} (as opposed to one of its derived types),
2181 rplante@ncsa.uiuc.edu 1375 there are no restrictions on the names that may be included.
2182    
2183 msdemlei 5051
2184    
2185 rplante@ncsa.uiuc.edu 1375 A data type description can be augmented via a common set of
2186 msdemlei 5509 \xmlel{vs:DataType} attributes. The
2187 msdemlei 5051 \xmlel{arraysize} attribute indicates the parameter is an array
2188 rplante@ncsa.uiuc.edu 1375 of values of the named type. Its value describes the shape of the
2189 msdemlei 5197 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 rplante@ncsa.uiuc.edu 1375
2195 msdemlei 5051
2196    
2197 rplante@ncsa.uiuc.edu 1375 More descriptive information about the type can be provided via
2198 msdemlei 5051 \xmlel{extendedType} and \xmlel{extendedSchema}, which
2199 msdemlei 5509 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 msdemlei 5930 arraysize \verb|*|, as supported by all VOTable readers. VOTable readers
2204 msdemlei 5509 interpreting the timestamp xtype, however, can turn this string into a
2205     timestamp value native to its clients. Such readers will interpret
2206 msdemlei 5930 a VOTable \xmlel{FIELD}'s \xmlel{xtype} attribute.
2207     Such information is reflected in \xmlel{extendedType}.
2208 msdemlei 5509
2209     Arbitrary information can also be
2210 rplante@ncsa.uiuc.edu 1375 provided via any prefix-qualified, globally defined attribute drawn
2211     from an XML Schema other than VODataService (by virtue of the
2212 msdemlei 5051 \xmlel{xs:anyAttribute} specification present
2213     on \xmlel{vs:DataType}).
2214 rplante@ncsa.uiuc.edu 1375
2215    
2216    
2217    
2218    
2219     Note that in the derived parameter description types described below,
2220 msdemlei 5051 the \xmlel{dataType} element is optional. Its absence
2221     from the parameter description does \emph{not} mean that the
2222 rplante@ncsa.uiuc.edu 1375 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 msdemlei 5051 type, the \xmlel{vs:BaseParam} type can be used directly when the
2226 rplante@ncsa.uiuc.edu 1375 context permits.
2227    
2228    
2229 msdemlei 5051 \subsubsection{Input Parameters}
2230     \label{sect:inputparam}
2231    
2232    
2233 rplante@ncsa.uiuc.edu 1375 Actual parameters are normally described with types derived from
2234 msdemlei 5051 \xmlel{vs:BaseParam}. The \xmlel{vs:InputParam} is intended
2235 msdemlei 5930 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 msdemlei 5561 sufficient for describing an input parameter to a simple REST-like
2239 msdemlei 5509 service or a function in a weakly-typed language. They are defined
2240     in \xmlel{vs:SimpleDataType}:
2241 rplante@ncsa.uiuc.edu 1375
2242 msdemlei 5509 % 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 rplante@ncsa.uiuc.edu 1375
2248 msdemlei 5509 \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 msdemlei 5565 \item[Default] a space character
2296 msdemlei 5509 \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 msdemlei 5930 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 msdemlei 5931 ensure schema validation catches mistakes, resource record authors are
2322 msdemlei 5930 advised to declare the type system intended using \xmlel{xsi:type}; for
2323 msdemlei 5931 instance, a service accepting a DALI point might declare:
2324 msdemlei 5930
2325     \begin{lstlisting}[language=XML]
2326     <param std="true">
2327 msdemlei 5931 <name>pos</name>
2328 msdemlei 5930 <description>ICRS position of target object</description>
2329 msdemlei 5931 <dataType arraysize="2"
2330 msdemlei 5930 xsi:type="vs:VOTableType"
2331 msdemlei 5931 extendedType="point">double</dataType>
2332 msdemlei 5930 </param>
2333     \end{lstlisting}
2334    
2335     The \xmlel{vs:InputParam} class then is a \xmlel{vs:BaseParam}
2336     furnished with additional metadata
2337 msdemlei 5509 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 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd InputParam
2342 msdemlei 5057 \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 msdemlei 5509 A description of a service or function parameter having a
2349 msdemlei 5057 fixed data type.
2350     \par}
2351    
2352     \noindent{\small
2353 msdemlei 5931 DALI-compliant services should use VOTableType here, others
2354     should use SimpleDataType.
2355 msdemlei 5057 \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 msdemlei 5930 <xs:element name="dataType" type="vs:DataType" minOccurs="0" />
2365 msdemlei 5057 </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 msdemlei 5930 \item[Terms]\hfil
2387 msdemlei 5057 \begin{longtermsdescription}
2388     \item[required]
2389 msdemlei 5509 The parameter is required for the application or
2390 msdemlei 5057 service to work properly.
2391    
2392     \item[optional]
2393 msdemlei 5509 The parameter is optional but supported by the application or
2394 msdemlei 5057 service.
2395    
2396     \item[ignored]
2397 msdemlei 5509 The parameter is not supported and thus is ignored by the
2398 msdemlei 5057 application or service.
2399    
2400     \end{longtermsdescription}
2401 msdemlei 5565 \item[Default] optional
2402 msdemlei 5057 \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 msdemlei 5565 \item[Default] true
2415 msdemlei 5057 \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 msdemlei 5930 \item[Type] a string with optional attributes
2427 msdemlei 5057 \item[Meaning]
2428 msdemlei 5930 A type of data contained in the parameter.
2429 msdemlei 5057
2430     \item[Occurrence] optional
2431    
2432     \end{description}
2433    
2434    
2435     \end{bigdescription}\endgroup
2436    
2437     \endgroup
2438     \end{generated}
2439    
2440 msdemlei 5051 % /GENERATED
2441 rplante@ncsa.uiuc.edu 1375
2442 msdemlei 5051
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 rplante@ncsa.uiuc.edu 1375
2449 msdemlei 5051 \begin{lstlisting}[language=XML]
2450     <param use="required">
2451     <name> radius </name>
2452     <description>
2453 rplante@ncsa.uiuc.edu 1375 search radius; returned objects are restricted to fall
2454     within this angular distance of the search position.
2455 msdemlei 5051 </description>
2456     <ucd> phys.angSize </ucd>
2457 msdemlei 5931 <dataType xsi:type="vs:SimpleDataType"> real </dataType>
2458 msdemlei 5051 </param>
2459     \end{lstlisting}
2460 rplante@ncsa.uiuc.edu 1375
2461 msdemlei 5051 \subsubsection{Table Columns}
2462     \label{sect:columns}
2463 rplante@ncsa.uiuc.edu 1375
2464 msdemlei 5051
2465     The \xmlel{vs:TableParam} is also derived from
2466     \xmlel{vs:BaseParam}, and is designed for describing a column of
2467 rplante@ncsa.uiuc.edu 1375 a table.
2468    
2469    
2470 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd TableParam
2471 msdemlei 5057 \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 msdemlei 5509 A description of a table parameter having a fixed data type.
2478 msdemlei 5057 \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 msdemlei 5509 it represents a parameter specific to the data described
2507     If not provided, then the value is unknown.
2508 msdemlei 5057
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 msdemlei 5509 A type of data contained in the column
2524 msdemlei 5057
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 msdemlei 5509 A keyword representing traits of the column.
2533 msdemlei 5156 Recognized values include “indexed”, “primary”, and
2534     “nullable”.
2535 msdemlei 5057
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 msdemlei 5051 % /GENERATED
2551 rplante@ncsa.uiuc.edu 1375
2552    
2553 msdemlei 5051 A table column's data type is indicated with the \xmlel{dataType}
2554 msdemlei 5160 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 msdemlei 5509 sect.~\ref{sect:tbldatatypes}, this SHOULD be
2560 msdemlei 5160 \xmlel{vs:VOTableType} for VODataService 1.2 table columns.
2561 rplante@ncsa.uiuc.edu 1375
2562 msdemlei 5160 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 mbt 5183 requirement for \tapschema\ and is usually only a problem when delimited
2566 msdemlei 5160 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 rplante@ncsa.uiuc.edu 1375
2570    
2571 msdemlei 5160 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 msdemlei 5509 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 msdemlei 5160
2579 msdemlei 5197 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2580 msdemlei 5051 <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 msdemlei 5160
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 msdemlei 5051 \end{lstlisting}
2603 rplante@ncsa.uiuc.edu 1375
2604    
2605 msdemlei 5051 \subsubsection{Table Column Data Types}
2606 msdemlei 5115 \label{sect:tbldatatypes}
2607 rplante@ncsa.uiuc.edu 1375
2608 msdemlei 5051
2609 msdemlei 5509 The VODataService schema defines two type systems that derive from
2610     \xmlel{vs:TableDa\-taType}: \xmlel{vs:VOTableType} and
2611 msdemlei 5152 \xmlel{vs:TAPType}. Following the move to VOTable-compatible type
2612 msdemlei 5930 descriptions in TAP 1.1 \citep{2019ivoa.spec.0927D}, this version of
2613 msdemlei 5152 VODataService deprecates the use of \xmlel{vs:TAPType}. New software
2614     should only generate \xmlel{vs:VOTableType}s in \xmlel{tableset}s.
2615 rplante@ncsa.uiuc.edu 1375
2616    
2617 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd VOTableType
2618 msdemlei 5057 \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 msdemlei 5509 A data type supported explicitly by the VOTable format
2625 msdemlei 5057 \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 msdemlei 5151 <xs:attribute name="arraysize" type="vs:ArrayShape" />
2646 msdemlei 5057 <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 msdemlei 5184 \item[Type] string of the form: \emph{([0-9]+x)*[0-9]*[0-9*]}
2661 msdemlei 5509 \item[Meaning] See vs:DataType.
2662 msdemlei 5057 \item[Occurrence] optional
2663    
2664     \end{description}
2665     \item[delim]
2666     \begin{description}
2667     \item[Type] string: \xmlel{xs:string}
2668 msdemlei 5509 \item[Meaning] See vs:DataType.
2669 msdemlei 5057 \item[Occurrence] optional
2670 msdemlei 5565 \item[Default] a space character
2671 msdemlei 5057 \end{description}
2672     \item[extendedType]
2673     \begin{description}
2674     \item[Type] string: \xmlel{xs:string}
2675 msdemlei 5509 \item[Meaning] See vs:DataType.
2676 msdemlei 5057 \item[Occurrence] optional
2677     \end{description}
2678     \item[extendedSchema]
2679     \begin{description}
2680     \item[Type] a URI: \xmlel{xs:anyURI}
2681 msdemlei 5509 \item[Meaning] See vs:DataType.
2682 msdemlei 5057 \item[Occurrence] optional
2683     \end{description}
2684    
2685    
2686     \end{bigdescription}\endgroup
2687    
2688     \endgroup
2689     \end{generated}
2690    
2691 msdemlei 5051 % /GENERATED
2692 rplante@ncsa.uiuc.edu 1375
2693 msdemlei 5057
2694    
2695 msdemlei 5152 When the actual column type is not
2696     well matched to a VOTable data type, authors are
2697 msdemlei 5051 encouraged to use the \xmlel{extendedType} attribute to refer to
2698 msdemlei 5153 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 rplante@ncsa.uiuc.edu 1375
2704 msdemlei 5051 \appendix
2705 rplante@ncsa.uiuc.edu 1375
2706 msdemlei 5051 \section{Changes from previous versions}
2707 rplante@ncsa.uiuc.edu 1375
2708 msdemlei 5565 \subsection{Changes since PR-20190715}
2709    
2710     \begin{itemize}
2711 msdemlei 5930 \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 msdemlei 5565 \item table/@nrows is now constrained to be non-negative.
2715 msdemlei 5930 \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 msdemlei 5565 \end{itemize}
2719    
2720 msdemlei 5501 \subsection{Changes since WD-20181026}
2721 rplante@ncsa.uiuc.edu 1375
2722 msdemlei 5051 \begin{itemize}
2723 msdemlei 5509 \item Adding a summary of the discovering data collections EN.
2724 msdemlei 5501 \item Spatial coverage now has a frame attribute.
2725 msdemlei 5509 \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 msdemlei 5510 \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 msdemlei 5501 \end{itemize}
2732    
2733     \subsection{Changes since REC-1.1}
2734    
2735     \begin{itemize}
2736 msdemlei 5187 \item Deprecated STCResourceProfile and replaced it with
2737 msdemlei 5112 \xmlel{spatial}, \xmlel{temporal}, and \xmlel{spectral} elements.
2738 msdemlei 5187 \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 msdemlei 5160 SQL context.
2746 msdemlei 5151 \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 msdemlei 5195 \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 msdemlei 5187 \item Deprecated TAPType.
2754 msdemlei 5509 \item extendedType is now defined to correspond to VOTable xtypes in the
2755     absence of extendedSchema.
2756 msdemlei 5194 \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 msdemlei 5509 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 msdemlei 5051 \item Ported source to \ivoatex.
2763     \end{itemize}
2764 rplante@ncsa.uiuc.edu 1375
2765 msdemlei 5051 \subsection{Changes since PR-20100916}
2766 rplante@ncsa.uiuc.edu 1375
2767 msdemlei 5051 \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 rplante@ncsa.uiuc.edu 1375
2772 msdemlei 5051 \subsection{Changes since PR-20100914}
2773 rplante@ncsa.uiuc.edu 1375
2774 msdemlei 5051 \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 rplante@ncsa.uiuc.edu 1375
2781 msdemlei 5051 \subsection{Changes since PR-20100412}
2782 rplante@ncsa.uiuc.edu 1375
2783 msdemlei 5051 \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 rplante@ncsa.uiuc.edu 1375
2791 msdemlei 5051 \subsection{Changes since PR-20090903}
2792 rplante@ncsa.uiuc.edu 1375
2793 msdemlei 5051 \begin{itemize}
2794 msdemlei 5055 \item added \xmlel{testQuery}
2795 msdemlei 5051 to \xmlel{vs:ParamHTTP}
2796 msdemlei 5055 \item in text, added explanation of
2797 msdemlei 5051 \xmlel{vs:Format}
2798     \item grammatical clean-up
2799     \end{itemize}
2800 rplante@ncsa.uiuc.edu 1375
2801 msdemlei 5051 \subsection{Changes since WD-20090508 (v1.10)}
2802    
2803     \begin{itemize}
2804 msdemlei 5055 \item corrected errors in example in Introduction
2805 msdemlei 5051 \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 msdemlei 5165 \bibliography{ivoatex/ivoabib,ivoatex/docrepo,local}
2814 msdemlei 5056
2815 msdemlei 5055 \end{document}

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