/[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 5930 - (hide annotations)
Tue Feb 23 09:45:51 2021 UTC (5 months, 1 week ago) by msdemlei
File MIME type: application/x-tex
File size: 106504 byte(s)
Now allowing any vs:DataType element to define vs:InputParams.  This
will no longer check the controlled vocabularies of SimpleDataType.
Therefore, added advice to have an explicit xsi:type in param's dataTypes.

Also, removing a few other todo notes that nobody wanted to tackle.


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

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