/[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 5115 - (hide annotations)
Thu Aug 23 11:10:38 2018 UTC (2 years, 11 months ago) by msdemlei
File MIME type: application/x-tex
File size: 93765 byte(s)
VODataService: some minor touchups.

Also, making me the "executive" editor for now.


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

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