/[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 5197 - (hide annotations)
Thu Oct 25 14:47:15 2018 UTC (2 years, 9 months ago) by msdemlei
File MIME type: application/x-tex
File size: 97157 byte(s)
VODataService: minor editorial changes in sect. 3.5.


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

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