/[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 5055 - (hide annotations)
Fri Jun 22 13:59:25 2018 UTC (3 years, 1 month ago) by msdemlei
File MIME type: application/x-tex
File size: 51250 byte(s)
VODataService: Typo fixes for TeX buildability.


1 msdemlei 5051 \documentclass[11pt,a4paper]{ivoa}
2     \input tthdefs
3 msdemlei 5055 \usepackage{listings}
4     \lstloadlanguages{XML}
5     \lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False}
6     \usepackage{todonotes}
7 rplante@ncsa.uiuc.edu 1375
8 msdemlei 5051 \title{VODataService: A VOResource Schema Extension for Describing
9     Collections and Services}
10 rplante@ncsa.uiuc.edu 1375
11 msdemlei 5051 \ivoagroup{registry}
12 rplante@ncsa.uiuc.edu 1375
13 msdemlei 5051 \author[http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante]{Raymond Plante}
14     \author[http://www.ivoa.net/twiki/bin/view/IVOA/MarkusDemleitner]{Markus Demleitner}
15     \author[http://www.ivoa.net/twiki/bin/view/IVOA/AurelienStebe]{Aurélien Stébé}
16     \author[http://www.ivoa.net/twiki/bin/view/IVOA/KevinBenson]{Kevin Benson}
17     \author[http://www.ivoa.net/twiki/bin/view/IVOA/PatrickDowler]{Patrick Dowler}
18     \author[http://www.ivoa.net/twiki/bin/view/IVOA/MatthewGraham]{Matthew Graham}
19     \author[http://www.ivoa.net/twiki/bin/view/IVOA/GretchenGreene]{Gretchen Greene}
20     \author[http://www.ivoa.net/twiki/bin/view/IVOA/PaulHarrison]{Paul Harrison}
21     \author[http://www.ivoa.net/twiki/bin/view/IVOA/GerardLemson]{Gerard Lemson}
22     \author[http://www.ivoa.net/twiki/bin/view/IVOA/TonyLinde]{Tony Linde}
23     \author[http://www.ivoa.net/twiki/bin/view/IVOA/GuyRixon]{Guy Rixon}
24 rplante@ncsa.uiuc.edu 1375
25 msdemlei 5051 \editor{Ray Plante}
26     \editor{Markus Demleitner}
27 rplante@ncsa.uiuc.edu 1375
28 msdemlei 5051 \previousversion[http://www.ivoa.net/Documents/VODataService/20101202]{REC
29     1.1}
30     \previousversion[http://www.ivoa.net/Documents/VODataService/20100916]{PR-20100916}
31     \previousversion[http://www.ivoa.net/Documents/VODataService/20100914]{PR-20100914}
32     \previousversion[http://www.ivoa.net/Documents/VODataService/20100412]{PR-20100412}
33     \previousversion[http://www.ivoa.net/Documents/VODataService/20090903]{PR-20090903}
34     \previousversion[http://www.ivoa.net/Documents/WD/ReR/VODataService-20090508.html]{WD-20090508}
35    
36 rplante@ncsa.uiuc.edu 1375
37 msdemlei 5051 \begin{document}
38     \begin{abstract}
39 rplante@ncsa.uiuc.edu 1375 VODataService refers to an XML encoding standard for a specialized
40     extension of the IVOA Resource Metadata that is useful for describing
41     data collections and the services that access them. It is defined as
42     an extension of the core resource metadata encoding standard known as
43 msdemlei 5051 VOResource \citep{2008ivoa.spec.0222P} using XML Schema.
44 rplante@ncsa.uiuc.edu 1375 The specialized resource types defined by the VODataService schema
45     allow one to describe how the data underlying the resource cover the
46     sky as well as cover frequency and time. This coverage description
47 msdemlei 5051 leverages heavily the Space-Time Coordinates (STC) standard
48     schema\todo{Fix this}. VODataService also enables detailed
49 rplante@ncsa.uiuc.edu 1375 descriptions of tables that includes information useful to the
50     discovery of tabular data. It is intended that the VODataService data
51     types will be particularly useful in describing services that support
52     standard IVOA service protocols.
53 msdemlei 5051 \end{abstract}
54 rplante@ncsa.uiuc.edu 1375
55 msdemlei 5051 \section*{Acknowledgments}
56 rplante@ncsa.uiuc.edu 1375
57 msdemlei 5051 Versions 1.0 and 1.1 of this document have been developed with support from the
58     National Science Foundation's
59 rplante@ncsa.uiuc.edu 1375 Information Technology Research Program under Cooperative Agreement
60     AST0122449 with The Johns Hopkins University, from the
61 msdemlei 5051 UK Particle Physics and Astronomy
62     Research Council (PPARC), from the European Commission's (EC)
63     Sixth
64     Framework Programme via the
65     Optical Infrared Coordination Network (OPTICON), and from EC's
66     Seventh Framework Programme
67 rplante@ncsa.uiuc.edu 1375 via its
68 msdemlei 5051 eInfrastructure Science Repositories initiative.
69 rplante@ncsa.uiuc.edu 1375
70 msdemlei 5051 Version 1.2 of this document was developed in part with support from the
71     German federal ministry for research and education's e-inf-astro (BMBF
72     FKZ 05A17VH2)
73 rplante@ncsa.uiuc.edu 1375
74    
75 msdemlei 5051 \section*{Conformance-related definitions}
76    
77     The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
78     ``OPTIONAL'' (in upper or lower case) used in this document are to be
79     interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
80    
81     The \emph{Virtual Observatory (VO)} is a
82 rplante@ncsa.uiuc.edu 1375 general term for a collection of federated resources that can be used
83     to conduct astronomical research, education, and outreach.
84 msdemlei 5051 The \href{http://www.ivoa.net}{International
85     Virtual Observatory Alliance (IVOA)} is a global
86 rplante@ncsa.uiuc.edu 1375 collaboration of separately funded projects to develop standards and
87     infrastructure that enable VO applications.
88    
89    
90 msdemlei 5051 \section*{Syntax Notation Using XML Schema}
91 rplante@ncsa.uiuc.edu 1375
92 msdemlei 5051 The eXtensible Markup Language, or XML, is document syntax for marking
93     textual information with named tags and is defined by \citet{std:XML}.
94     The set of XML tag names and the syntax
95 rplante@ncsa.uiuc.edu 1375 rules for their use is referred to as the document schema. One way to
96     formally define a schema for XML documents is using the W3C standard
97 msdemlei 5051 known as XML Schema \citep{std:XSD}.
98 rplante@ncsa.uiuc.edu 1375
99 msdemlei 5051 The XML Schemas of VODataService as well as VOResource and its other
100     extensions are
101     available from the IVOA document
102     repository\footnote{\url{http://www.ivoa.net/xml}} at any time.
103 rplante@ncsa.uiuc.edu 1375 Parts of the schema appear within the main sections of this document;
104 msdemlei 5051 however, documentation nodes have been left out for the sake of brevity.
105     Where the content of the pieces of schema embedded in this text
106     diverges from the schema document in the IVOA document
107     repository, the version in the schema repository is authoritative.
108 rplante@ncsa.uiuc.edu 1375
109     References to specific elements and types defined in the VOResource
110 msdemlei 5051 schema include the namespaces prefix \xmlel{vr} as in
111     \xmlel{vr:Resource} (a type defined in the VOResource schema; the
112     recommended namespace prefix for VODataService as per Registry
113     Interfaces 1.1 \citep{registry interfaces 1.1}, sect.~2.2, is \xmlel{vs}.
114 rplante@ncsa.uiuc.edu 1375
115 msdemlei 5051 \section{Introduction}
116 rplante@ncsa.uiuc.edu 1375
117 msdemlei 5051 The VOResource standard \citep{2008ivoa.spec.0222P} provides a means of
118     encoding IVOA Resource Metadata\todo{decouple from RM} in XML.
119     VOResource uses XML Schema \citep{std:XSD} to define
120 rplante@ncsa.uiuc.edu 1375 most of the XML syntax rules (while a few of the syntax rules are
121     outside the scope of Schema). VOResource also describes mechanisms
122     for creating extensions to the core VOResource metadata. This allows
123     for the standardization of new metadata for describing specialized
124     kinds of resources in a modular way without deprecating the core
125     schema or other extensions. This document defines one such extension
126 msdemlei 5055 referred to as VODataService.
127 rplante@ncsa.uiuc.edu 1375
128 msdemlei 5051 \subsection{The Role in the IVOA Architecture}
129 rplante@ncsa.uiuc.edu 1375
130 msdemlei 5051 The IVOA Architecture \citep{note:VOARCH} provides a high-level
131 rplante@ncsa.uiuc.edu 1375 view of how IVOA standards work together to connect users and
132     applications with providers of data and services, as depicted in the
133 msdemlei 5051 diagram in Fig. 1.\todo{Fix}
134 rplante@ncsa.uiuc.edu 1375
135     In this architecture, users can leverage a variety of tools (from the
136     User Layer) to discover archives and services of interest (represented
137     in the Resource Layer); registries provide the means for this
138     discovery. A registry is a repository of descriptions of resources
139     that can be searched based on the metadata in those descriptions. The
140 msdemlei 5051 Resource Metadata standard \citep{RM} defines the core
141 rplante@ncsa.uiuc.edu 1375 concepts used in the resource descriptions, and the VOResource
142 msdemlei 5051 standard defines the XML format. As an
143 rplante@ncsa.uiuc.edu 1375 extension of VOResource, the VODataService standard, defined in this
144     document, specifically supports descriptions of data collections and
145     services.
146    
147 msdemlei 5051 \subsection{Purpose}
148 rplante@ncsa.uiuc.edu 1375
149 msdemlei 5051
150 rplante@ncsa.uiuc.edu 1375 The purpose of this extension is to define common XML Schema
151 msdemlei 5051 types -- particularly new resource types -- that are useful for describing
152 rplante@ncsa.uiuc.edu 1375 data collections and services that access data. In particular, it
153 msdemlei 5051 allows one to describe the data's \emph{coverage}: the parts of the
154 rplante@ncsa.uiuc.edu 1375 sky with which the data are associated and the time and frequency ranges that
155     were observed or modeled to create the data. It also allows one to
156     describe tables in detail. In particular, one can describe each of
157     the columns of a table--providing, for example, its name, type, UCD
158 msdemlei 5051 \citep{UCD},
159 rplante@ncsa.uiuc.edu 1375 and textual description. When this metadata is part of a resource
160 msdemlei 5051 description in a registry \citep{VOR}, it becomes possible
161 rplante@ncsa.uiuc.edu 1375 to discover tables that contain particular kinds of data.
162    
163 msdemlei 5051
164    
165 rplante@ncsa.uiuc.edu 1375 It is intended that VODataService will be central to describing
166     services that support standard IVOA data access layer protocols such
167 msdemlei 5051 as Simple Image Access \citep{SIA} and Simple Cone Search
168     \citep{SCS}. While other VOResource extensions would
169 rplante@ncsa.uiuc.edu 1375 define the protocol-specific metadata (encapsulated as a standard
170 msdemlei 5051 \emph{capability} \citep{VOR}), the general service
171 rplante@ncsa.uiuc.edu 1375 resource description would share the common data concepts such as
172     coverage and tabular data. Note, however, that a service described
173     using the VODataService schema need not support any standard
174     protocols. With the VODataService extension schema plus the core
175     VOResource schema, it is possible to describe a custom service
176     interface that accesses data.
177    
178 msdemlei 5051
179    
180     As a legal extension of VOResource \citep{VOR}, the use
181 rplante@ncsa.uiuc.edu 1375 of VODataService is subject to the rules and recommendations for XML
182 msdemlei 5051 \citep{xml}, XML Schema \citep{schema},
183 rplante@ncsa.uiuc.edu 1375 and VOResource itself.
184    
185    
186 msdemlei 5051 \section{The VODataService Data Model}
187    
188    
189 rplante@ncsa.uiuc.edu 1375 The VODataService extension in general enables the description of two
190     types of resources: data collections and services that access data.
191     Here's an example of a VOResource document (abbreviated for the
192     purposes of illustration) that describes a service from the NASA
193     Extragalactic Database (NED) that provides measured redshifts for a
194     given object.
195    
196    
197    
198 msdemlei 5051 \begin{lstlisting}[language=XML]
199     <ri:Resource xmlns=""
200     xsi:type="vs:CatalogService" status="active"
201 rplante@ncsa.uiuc.edu 1375 updated="2008-04-29T14:51:54" created="2005-10-14T01:46:00"
202     xmlns:ri="http://www.ivoa.net/xml/RegistryInterface/v1.0"
203     xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
204 msdemlei 5051 xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
205 rplante@ncsa.uiuc.edu 1375 xmlns:stc="http://www.ivoa.net/xml/STC/stc-v1.30.xsd"
206 msdemlei 5051 xmlns:xlink="http://www.w3.org/1999/xlink"
207 rplante@ncsa.uiuc.edu 1375 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
208 msdemlei 5051 xsi:schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0
209 rplante@ncsa.uiuc.edu 1375 http://www.ivoa.net/xml/VOResource/v1.0
210     http://www.ivoa.net/xml/VODataService/v1.1
211     http://www.ivoa.net/xml/VODataService/v1.1
212     http://www.ivoa.net/xml/STC/stc-v1.30.xsd
213 msdemlei 5051 http://www.ivoa.net/xml/STC/stc-v1.30.xsd">
214 rplante@ncsa.uiuc.edu 1375
215 msdemlei 5051 <title>The NASA/IPAC Extragalactic Database</title>
216     <shortName>NED_redshift</shortName>
217     <identifier>ivo://ned.ipac/Redshift_By_Object_Name</identifier>
218     <curation>
219     <publisher>The NASA/IPAC Extragalactic Database</publisher>
220     <contact>
221     <name>Olga Pevunova</name>
222     <email>contact@datacenter.edu</email>
223     </contact>
224     </curation>
225     <content>
226     <subject>redshift</subject>
227     <subject>galaxies</subject>
228     <description>
229 rplante@ncsa.uiuc.edu 1375 NED is built around a master list of extragalactic objects for
230     which cross-identifications of names have been established,
231     accurate positions and redshifts entered to the extent possible,
232     and some basic data collected. This service will return recorded
233     redshifts for a given object.
234 msdemlei 5051 </description>
235     <referenceURL>http://nedwww.ipac.caltech.edu/help/data_help.html#zdat</referenceURL>
236     <type>BasicData</type>
237     <contentLevel>Research</contentLevel>
238     </content>
239 rplante@ncsa.uiuc.edu 1375
240 msdemlei 5051 <capability>
241     <interface xsi:type="vs:ParamHTTP">
242     <accessURL use="base">
243 rplante@ncsa.uiuc.edu 1375 http://nedwww.ipac.caltech.edu/cgi-bin/nph-datasearch?search_type=Redshifts&amp;amp;
244 msdemlei 5051 </accessURL>
245     <queryType>GET</queryType>
246     <resultType>application/xml+votable</resultType>
247     <param use="required">
248     <name>objname</name>
249     <description>Name of object</description>
250     <dataType>string</dataType>
251     </param>
252     <param use="required">
253     <name>of</name>
254     <description>Output format parameter, must be "xml_main" for VOTable output.</description>
255     <dataType>string</dataType>
256     </param>
257     </interface>
258     </capability>
259 rplante@ncsa.uiuc.edu 1375
260 msdemlei 5051 <coverage>
261     <stc:STCResourceProfile>
262     <stc:AstroCoordSystem xlink:type="simple"
263 rplante@ncsa.uiuc.edu 1375 xlink:href="ivo://STClib/CoordSys#UTC-FK5-TOPO"
264 msdemlei 5051 id="UTC-FK5-TOPO"/>
265     <stc:AstroCoordArea coord_system_id="UTC-FK5-TOPO">
266     <stc:AllSky/>
267     </stc:AstroCoordArea>
268     </stc:STCResourceProfile>
269 rplante@ncsa.uiuc.edu 1375
270 msdemlei 5051 <waveband>Radio</waveband>
271     <waveband>Optical</waveband>
272     </coverage>
273 rplante@ncsa.uiuc.edu 1375
274 msdemlei 5051 <tableset>
275     <schema>
276     <name>default</name>
277     <table type="output">
278     <name>default</name>
279     <column>
280     <name>No.</name>
281     <description>
282 rplante@ncsa.uiuc.edu 1375 A sequential data-point number applicable to this list only.
283 msdemlei 5051 </description>
284     <ucd>meta.number</ucd>
285     <dataType xsi:type="vs:VOTableType">int</dataType>
286     </column>
287     <column>
288     <name>Name in Publication</name>
289     <description>
290 rplante@ncsa.uiuc.edu 1375 The object's name in NED's standard format, of the object to which the data apply.
291 msdemlei 5051 </description>
292     <ucd>meta.id;name</ucd>
293     <dataType xsi:type="vs:VOTableType">string</dataType>
294     </column>
295     <column>
296     <name>Published Velocity</name>
297     <description>
298 rplante@ncsa.uiuc.edu 1375 The radial velocity , derived from derived from the shift of some spectral feature, in km/sec
299 msdemlei 5051 </description>
300     <unit>km/sec</unit>
301     <ucd>src.spect.dopplerVeloc</ucd>
302     <dataType xsi:type="vs:VOTableType">int</dataType>
303     </column>
304     </table>
305     </schema>
306     </tableset>
307     </ri:Resource>
308     \end{lstlisting}
309 rplante@ncsa.uiuc.edu 1375
310     This example illustrates some of the features of the VODataService
311     extension:
312 msdemlei 5051
313 msdemlei 5055 \begin{enumerate}
314 msdemlei 5051 \item the extra namespaces associated with
315 rplante@ncsa.uiuc.edu 1375 VODataService metadata; if STC coverage information
316 msdemlei 5051 \citep{STC} is not
317     included, then only the VODataService namespaced is needed.
318     \item the specific type of resource indicated by
319     the value of the \xmlel{xsi:type} attribute; in this case
320     \xmlel{vs:CatalogService} indicates that this is
321     describing a service that accesses tabular data.
322     \item the location of the VOResource-related schema
323     documents used by this description,
324     \item the core VOResource metadata,
325     \item an interface described by the
326     VODataService interface type, \xmlel{vs:ParamHTTP}; this
327     type can indicate input arguments it supports.
328     \item a description of the
329     coverage, including an STC
330     description plus waveband keywords.
331     \item a description of the table that is returned
332     by the service.
333 msdemlei 5055 \end{enumerate}
334 rplante@ncsa.uiuc.edu 1375
335 msdemlei 5051 \subsection{The Schema Namespace and Location}
336 rplante@ncsa.uiuc.edu 1375
337 msdemlei 5051
338 rplante@ncsa.uiuc.edu 1375 The namespace associated with VODataService extensions is
339 msdemlei 5051 $$\mbox{\texttt{http://www.ivoa.net/xml/VODataService/v1.1}}.$$
340 rplante@ncsa.uiuc.edu 1375 Just like the namespace URI for the VOResource schema, the
341     VODataService namespace URI can be interpreted as a URL. Resolving it
342 msdemlei 5051 will return the XML Schema document
343     that defines the VODataService schema.\todo{explain constant ns vs.
344     v1.1}
345 rplante@ncsa.uiuc.edu 1375
346 msdemlei 5051
347    
348 rplante@ncsa.uiuc.edu 1375 Authors of VOResource instance documents may choose to
349     provide a location for the VOResource XML Schema document and its
350     extensions using the
351 msdemlei 5051 \xmlel{xsi:schemaLocation}</a> attribute. While the choice of
352 rplante@ncsa.uiuc.edu 1375 the location value is the choice of the author, this specification
353     recommends using the VODataService namespace URI as its location URL
354     (as illustrated in the example above), as in,
355    
356 msdemlei 5051 \begin{lstlisting}[language=XML]
357     xsi:schemaLocation="http://www.ivoa.net/xml/VODataService/v1.1
358     http://www.ivoa.net/xml/VODataService/v1.1"
359     \end{lstlisting}
360 rplante@ncsa.uiuc.edu 1375
361 msdemlei 5051
362     \begin{admonition}
363     The IVOA Registry Interface standard \citep{RI}
364     actually \emph{requires} that the VOResource records it
365 rplante@ncsa.uiuc.edu 1375 shares with other registries provide location URLs via
366 msdemlei 5051 \xmlel{xsi:schemaLocation} for the VOResource schema and
367 rplante@ncsa.uiuc.edu 1375 all legal extension schemas that are used in the records. This
368 msdemlei 5051 rule would apply to the VODataService schema.
369     \end{admonition}
370 rplante@ncsa.uiuc.edu 1375
371 msdemlei 5051
372     The prefix, \xmlel{vs}, is used by convention as the prefix
373 rplante@ncsa.uiuc.edu 1375 defined for the VODataService schema; however, instance documents may
374     use any prefix. In applications where common use of prefixes is
375 msdemlei 5055 recommended (such as with the Registry Interfaces specification),
376     use of the \xmlel{vs} prefix is recommended.
377 msdemlei 5051 Note also that in this document, the \xmlel{vr} prefix is used to
378 rplante@ncsa.uiuc.edu 1375 label, as shorthand, a type or element name that is defined in the
379 msdemlei 5051 VOResource schema, as in \xmlel{vr:Resource}.
380 rplante@ncsa.uiuc.edu 1375
381 msdemlei 5051
382    
383     \begin{admonition}
384     (todo: remove this; doesn't really apply any more; and there *really*
385     shouldn't be any VODS 1.0 around any more)
386    
387     One reason one may \emph{not} be able to use \xmlel{vs}
388 rplante@ncsa.uiuc.edu 1375 to represent the VODataService schema, version 1.1, is because
389     it is already in defined to represent VODataService v1.0 and
390     cannot be overridden. At this writing, there are no IVOA
391     applications in which this is the case. Consult
392 msdemlei 5055 appendix~\ref{vods10-compat} for more details on
393 rplante@ncsa.uiuc.edu 1375 compatibility issues.</dd>
394 msdemlei 5051 \end{admonition}
395 rplante@ncsa.uiuc.edu 1375
396 msdemlei 5051
397     As recommend by the VOResource standard \citep{VOR}, the
398     VODataService schema sets \xmlel{elementFormDefault="unqualified"}.
399 rplante@ncsa.uiuc.edu 1375 This means that it is not necessary to qualify element names defined
400     in this schema with a namespace prefix (as there are no global
401     elements defined). The only place it is usually needed is as a
402     qualifier to a VODataService type name given as the value of an
403 msdemlei 5051 \xmlel{xsi:type} attribute.
404 rplante@ncsa.uiuc.edu 1375
405    
406 msdemlei 5051 \subsection{Summary of Metadata Concepts}
407     \label{sect:summ}
408    
409    
410 rplante@ncsa.uiuc.edu 1375 The VODataService extension defines four new types of resources. Two inherit
411 msdemlei 5051 directly from \xmlel{vr:Resource}:
412 rplante@ncsa.uiuc.edu 1375
413 msdemlei 5051
414     \begin{bigdescription}
415     \item[\xmlel{vs:DataCollection}]
416     This resource declares the existence of a collection of data, what
417 rplante@ncsa.uiuc.edu 1375 it represents, and how to get it. The access to the data may be
418     limited to a human-readable web page (given by
419 msdemlei 5051 \xmlel{content/referenceURL}); however, if the
420 rplante@ncsa.uiuc.edu 1375 contents of the collection are available statically via a
421     URL (e.g. an FTP URL to a directory containing all the files),
422     that URL can be provided. It can also provide pointers to
423     other IVOA registered services that can be used to access the data.
424 msdemlei 5051 \todo{deprecate}
425 rplante@ncsa.uiuc.edu 1375
426 msdemlei 5051 \item[\xmlel{vs:StandardSTC}]
427     This resource type declares one or more coordinate systems described
428     using STC \citep{STC} such that each can be
429 rplante@ncsa.uiuc.edu 1375 assigned a globally unique identifier (based on the IVOA
430     identifier for the resource record itself). This identifier
431     can then be referenced in any other STC description in lieu of
432     a fully described coordinate system. Coordinate systems
433     described in this way become reusable standards once they are
434 msdemlei 5051 registered in an IVOA registry.\todo{deprecate/remove}
435     \end{bigdescription}
436 rplante@ncsa.uiuc.edu 1375
437     The other two resource types represent specialized services:
438    
439 msdemlei 5051
440     \begin{bigdescription}
441     \item[\xmlel{vs:DataService}]
442     Inheriting from \xmlel{vr:Service}, this type is for
443 rplante@ncsa.uiuc.edu 1375 services that access astronomical data. It adds the ability to
444 msdemlei 5051 describe the data's coverage of the
445     sky, frequency, and time.
446 rplante@ncsa.uiuc.edu 1375
447 msdemlei 5051 \item[\xmlel{vs:CatalogService}]
448     Inheriting from \xmlel{vs:DataService}, this type
449 rplante@ncsa.uiuc.edu 1375 specifically refers to a service that accesses tabular data.
450     In addition to the coverage information, this type adds the
451     ability to describe the tables and their columns. This is
452 msdemlei 5051 intended for describing services that support the ``simple'' IVOA
453 rplante@ncsa.uiuc.edu 1375 data access layer protocols such as Simple Image Access
454 msdemlei 5051 \citep{SIA} and Simple Cone Search
455     \citep{SCS}.
456 msdemlei 5055 \end{bigdescription}
457 rplante@ncsa.uiuc.edu 1375
458 msdemlei 5051
459     In general, \xmlel{coverage} refers to
460 rplante@ncsa.uiuc.edu 1375 the extent that data samples the measurement range of the sky (space),
461     frequency, and time. The coverage metadata (encoded via the
462 msdemlei 5051 \xmlel{vs:Coverage} type) has two parts. The first part
463 rplante@ncsa.uiuc.edu 1375 allows a full STC profile description (via the imported STC element,
464 msdemlei 5051 \xmlel{stc:STCResourceProfile})\todo{deprecate}. The second part
465 rplante@ncsa.uiuc.edu 1375 captures key coverage metadata defined in the IVOA Resource Metadata
466 msdemlei 5051 standard \citep{RM}. The RM-derived coverage elements can
467 rplante@ncsa.uiuc.edu 1375 be considered summarizing metadata for many of the details that
468 msdemlei 5051 \emph{may} appear within the STC description, and enables simpler
469 rplante@ncsa.uiuc.edu 1375 searching of high-level coverage information.
470    
471 msdemlei 5051
472    
473 rplante@ncsa.uiuc.edu 1375 The detailed STC profile contained within the
474 msdemlei 5051 \xmlel{stc:STCResourceProfile} element is capable of
475 rplante@ncsa.uiuc.edu 1375 describing coverage not only in space, time, and frequency but also
476     velocity and redshift. The profile contains up to three types of
477 msdemlei 5051 component descriptions (\citep{STC}, section 4.1):
478 rplante@ncsa.uiuc.edu 1375 coordinate systems, coordinate values, and coordinate areas or ranges.
479     The first component describes the coordinate systems to which coordinate
480     values, areas, and regions are referenced. While any arbitrary
481     system can be described in this first part, it is expected that most
482     VODataService instances will provide a simple pointer to a predefined
483 msdemlei 5051 system in a registered \xmlel{vs:StandardSTC} record (using the
484     mechanism summarized in section~\ref{todo} below). The coordinate values
485 rplante@ncsa.uiuc.edu 1375 part will usually be used to describe the coordinate resolution,
486     errors, or typical sizes. The coordinate areas part describes actual
487     regions or ranges covered by the resource in any of the given
488     coordinate systems.
489    
490 msdemlei 5051
491     Table descriptions appear within a single \xmlel{tableset}
492 rplante@ncsa.uiuc.edu 1375 element. This element can in turn can contain one or more
493 msdemlei 5051 \xmlel{schema} element in which each schema
494 rplante@ncsa.uiuc.edu 1375 represents a set of logically related tables. It is not required that
495     that the schema grouping match the underlying database's
496 msdemlei 5051 \emph{catalogs} or \emph{schemas} (as defined in
497     \citep{SQLGuide}), though it may. In some cases,
498 rplante@ncsa.uiuc.edu 1375 such as when describing the table that is returned from an SIA
499 msdemlei 5051 service, the terms \emph{catalog} and \emph{schema} may have
500 rplante@ncsa.uiuc.edu 1375 little relevance; in this case, the table can be considered part of a
501 msdemlei 5051 sole ``default'' schema.
502 rplante@ncsa.uiuc.edu 1375
503 msdemlei 5051
504    
505 rplante@ncsa.uiuc.edu 1375 For each table in a schema, one can describe each of the columns,
506 msdemlei 5051 providing such information as its name, type, UCD \citep{UCD},
507 rplante@ncsa.uiuc.edu 1375 units, and a textual description. Providing this information makes it
508     possible to select a resource based on the kind data contained in its
509     tables.
510    
511 msdemlei 5051
512    
513 rplante@ncsa.uiuc.edu 1375 Finally, the VODataService defines specialized interface type
514 msdemlei 5051 (inheriting from \xmlel{vr:Interface}) called
515     \xmlel{vs:ParamHTTP}. This type is used to describe the commonly
516 rplante@ncsa.uiuc.edu 1375 used interface that is invoked over HTTP as either a GET or a POST
517 msdemlei 5051 \citep{HTTP} in which the arguments are encoded as
518     \emph{name=value} pairs. In addition to the access URL, it can
519 rplante@ncsa.uiuc.edu 1375 include not only the mime-type of the returned response, it can also
520     enumerate the input arguments that are supported by the service
521     implementation. Much like table columns, one can indicate for each
522     argument the name, the UCD, the data type, the units, whether it is
523     required, and a textual description of the argument. Note that this does
524     not capture any interdependencies between arguments. For example, it
525     cannot indicate if one argument only makes sense in the presence of
526     another argument.
527    
528    
529 msdemlei 5051 \section{The VODataService Metadata}
530     \label{sect:metadata}
531    
532    
533 rplante@ncsa.uiuc.edu 1375 This section enumerates the types and elements defined in the
534     VODataService extension schema and describes their meaning. Where a
535 msdemlei 5051 term matches a term in the RM, its meaning is given
536 rplante@ncsa.uiuc.edu 1375 in terms of the RM definition.
537    
538    
539 msdemlei 5051 \subsection{Resource Type Extensions}
540     \label{sect:resext}
541 rplante@ncsa.uiuc.edu 1375
542 msdemlei 5051 \subsubsection{DataCollection}
543     \label{sect:datacollection}
544    
545    
546     A \emph{data collection}, which is describable with the
547     \xmlel{vs:DataCollection} resource type, is a logical
548 rplante@ncsa.uiuc.edu 1375 group of data comprising one or more accessible
549     datasets. A collection can contain any combination of images,
550     spectra, catalogs, time-series, or other data. (In contrast, we talk
551 msdemlei 5051 about a \emph{dataset} as being a set of digitally-encoded
552     data that is normally accessible as a single unit -- e.g., a file.)
553 rplante@ncsa.uiuc.edu 1375
554    
555    
556 msdemlei 5051 The \xmlel{vs:DataCollection} type adds seven additional metadata
557     elements beyond the core VOResource metadata \citep{VOR}.
558 rplante@ncsa.uiuc.edu 1375
559 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd DataCollection
560     % /GENERATED
561 rplante@ncsa.uiuc.edu 1375
562 msdemlei 5051 The definition of the \xmlel{tableset} element forces certain
563 rplante@ncsa.uiuc.edu 1375 names within its description to be unique; these constraints are explained
564 msdemlei 5051 further in section~\ref{sect:unique}.
565 rplante@ncsa.uiuc.edu 1375
566 msdemlei 5051
567    
568     All of the child elements except \xmlel{tableset} derive
569     from RM terms. Four of the elements -- \xmlel{facility},
570     \xmlel{instrument}, \xmlel{rights}\todo{no, that's no longer RM in
571     VOResource},
572     and \xmlel{accessURL}--are reuses of elements defined in
573 rplante@ncsa.uiuc.edu 1375 the core VOResource schema, sharing the same syntax and similar
574 msdemlei 5051 semantics. In particular, the meanings of \xmlel{facility}
575     and \xmlel{instrument} in the context of
576     \xmlel{vs:DataCollection} are different from that in
577     \xmlel{vr:Organisation} only in that in the former type, they refer
578 rplante@ncsa.uiuc.edu 1375 to the origin of the data.
579    
580    
581    
582 msdemlei 5051 The \xmlel{vs:Format} type is used for
583     providing a value to the \xmlel{format} element:
584 rplante@ncsa.uiuc.edu 1375
585 msdemlei 5051
586     % GENERATED: !schemadoc VODataService-v1.2.xsd Format
587     % /GENERATED
588    
589    
590     The \xmlel{isMIMEType} attribute
591 rplante@ncsa.uiuc.edu 1375 provides a flag to indicate if the value represents an actual
592     MIME-type: if it is, this attribute should be explicitly set to
593 msdemlei 5051 \texttt{true}.
594 rplante@ncsa.uiuc.edu 1375
595    
596    
597    
598 msdemlei 5051 See section~\ref{sect:table} for a specification of
599     the \xmlel{vs:TableSet} type for describing tables.
600    
601    
602     \subsubsection{StandardSTC}
603     \label{sect:standardstc}
604    
605    
606     The \xmlel{vs:StandardSTC} resource type is used to register standard
607 rplante@ncsa.uiuc.edu 1375 coordinate systems, positions, or regions using the Space-Time
608 msdemlei 5051 Coordinate (STC, \citep{STC}) standard schema so that
609 rplante@ncsa.uiuc.edu 1375 they can by uniquely referenced by name by other resource descriptions
610     or applications. This resource type extends the core metadata with a
611 msdemlei 5051 single element, \xmlel{stcDefinitions}, which contains
612 rplante@ncsa.uiuc.edu 1375 the STC definitions.
613    
614    
615 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd StandardSTC
616    
617     % /GENERATED
618    
619    
620 rplante@ncsa.uiuc.edu 1375 The curation metadata that is part of the core VODataService should
621     generally refer to the publishing organization and persons that are
622     responsible for defining the systems, updating the definitions as
623     needed, and responding to user questions about the definitions. The
624     content metadata, in particular the textual contents of the
625 msdemlei 5051 \xmlel{description} element, should describe the purpose
626 rplante@ncsa.uiuc.edu 1375 of the definition and where references to the defined systems,
627     positions, or regions may be used.
628    
629    
630 msdemlei 5051 The content of the \xmlel{stcDefinitions} element is
631 rplante@ncsa.uiuc.edu 1375 controlled by the STC schema. Because that schema uses the
632 msdemlei 5051 \verb|elementFormDefault="true"| and most of the STC elements
633     are defined to be global,
634     \xmlel{stcDefinitions} child elements must be qualified
635 rplante@ncsa.uiuc.edu 1375 as being in the STC namespace
636     (http://www.ivoa.net/xml/STC/stc-v1.30.xsd), by either setting the
637 msdemlei 5051 default namespace (via the \xmlel{xmlns} attribute) or via
638 rplante@ncsa.uiuc.edu 1375 explicit qualification via a prefix (see example).
639    
640    
641 msdemlei 5051 \subsubsection{DataService}
642     DataService">
643 rplante@ncsa.uiuc.edu 1375
644    
645 msdemlei 5051 The \xmlel{vs:DataService} resource type is for describing a
646 rplante@ncsa.uiuc.edu 1375 service that provides access to astronomical data. This service adds
647     to the core VOResource service metadata the ability to associate an
648     observing facility and/or instrument with the data as well as describe
649 msdemlei 5051 the coordinate coverage of data via its child \xmlel{coverage}
650 rplante@ncsa.uiuc.edu 1375 element. Note that while these elements are all optional, a resource
651     of this type still implies access to astronomical data.
652    
653    
654 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd DataService
655     % /GENERATED
656 rplante@ncsa.uiuc.edu 1375
657 msdemlei 5051 The use and meaning of the \xmlel{facility} and
658     \xmlel{instrument} elements are the same as for
659     \xmlel{vs:DataCollection}.
660 rplante@ncsa.uiuc.edu 1375
661    
662    
663 msdemlei 5051 \subsubsection{CatalogService}
664     \label{sect:catalogservice}
665    
666    
667     The \xmlel{vs:CatalogService} resource type is for describing a
668 rplante@ncsa.uiuc.edu 1375 service that interacts with astronomical data through one or more
669 msdemlei 5051 specified tables. Because it extends the \xmlel{vs:DataService}
670 rplante@ncsa.uiuc.edu 1375 type, a catalog service can have a coverage description as well. The
671     tabular data may optionally be described via a
672 msdemlei 5051 \xmlel{tableset} element.
673 rplante@ncsa.uiuc.edu 1375
674    
675    
676 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd CatalogService
677     % /GENERATED
678 rplante@ncsa.uiuc.edu 1375
679 msdemlei 5051 The definition of \xmlel{tableset} element forces certain
680 rplante@ncsa.uiuc.edu 1375 names within its description to be unique; these constraints are explained
681 msdemlei 5051 further in section~\ref{sect:unique}.
682 rplante@ncsa.uiuc.edu 1375
683 msdemlei 5051 \subsection{Coverage}
684     \label{sect:cover}
685 rplante@ncsa.uiuc.edu 1375
686    
687 msdemlei 5051 The \xmlel{vs:Coverage} type describes how the data samples the
688 rplante@ncsa.uiuc.edu 1375 sky, frequency, and time.
689    
690    
691    
692 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd Coverage
693     % /GENERATED
694 rplante@ncsa.uiuc.edu 1375
695     A detailed, systematic description of coverage is provided via the
696 msdemlei 5051 child \xmlel{stc:STCResourceProfile} element, taken from
697     the STC schema, version 1.3, with the namespace,
698     \xmlel{http://www.ivoa.net/xml/STC/stc-v1.30.xsd} (hereafter
699     referred using the \xmlel{stc:} prefix). This element is defined
700 rplante@ncsa.uiuc.edu 1375 in the STC schema as a global element; furthermore, the STC schema
701 msdemlei 5051 sets its global \verb|elementFormDefault="qualified"|.
702     Consequently, the \xmlel{stc:STCResourceProfile} element
703 rplante@ncsa.uiuc.edu 1375 and all its child elements must be qualified as part of the STC
704 msdemlei 5051 namespace as required by XML Schema.
705 rplante@ncsa.uiuc.edu 1375 In applications where common use of XML prefixes is required or
706 msdemlei 5051 encouraged (e.g. the IVOA Registry Interfaces \citep{RI}),
707     use of the \xmlel{stc:} prefix to represent the STC namespace is
708 rplante@ncsa.uiuc.edu 1375 encouraged.
709    
710 msdemlei 5051
711     \begin{admonition}
712     The STC scheme provides rich mark-up for expressing the
713 rplante@ncsa.uiuc.edu 1375 details of the coverage. In particular, the mark-up is quite
714     flexible in the units that can be used. For example, spectral
715     coverage can be given in terms of frequency, wavelength, or
716     energy. While it is recommended that the overall description
717 msdemlei 5051 given in the \xmlel{stc:STCResourceProfile} be
718 rplante@ncsa.uiuc.edu 1375 fairly general and approximate, leveraging the richness for a
719 msdemlei 5051 detailed description is allowed.
720     \end{admonition}
721 rplante@ncsa.uiuc.edu 1375
722 msdemlei 5051
723    
724 rplante@ncsa.uiuc.edu 1375 The remaining elements provide some summary information about the
725     coverage.
726    
727    
728    
729 msdemlei 5051 \begin{admonition}{Note on Footprint Service}
730     The \xmlel{footprint} element has been defined in
731 rplante@ncsa.uiuc.edu 1375 anticipation of a future standard IVOA footprint service
732     protocol that can be used to respond to detailed spatial
733     overlap queries. Consequently, in the future, applications may
734     be able to assume the protocol that footprint service URL
735     supports. When an application is unable to make any
736     assumptions, the IVOA Identifier given by the attribute should
737     be resolved and the returned resource description should be
738     searched for a recognized footprint service capability.</dd>
739 msdemlei 5051 \end{admonition}
740 rplante@ncsa.uiuc.edu 1375
741 msdemlei 5051 \subsection{Tabular Data}
742     \label{sect:table}
743 rplante@ncsa.uiuc.edu 1375
744 msdemlei 5051
745     The \xmlel{vs:TableSet} type can be used
746 rplante@ncsa.uiuc.edu 1375 to describe a set of tables that are part of a single resource and can
747     be consider functionally all located at a single site.
748    
749    
750    
751 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd TableSet
752     % /GENERATED
753 rplante@ncsa.uiuc.edu 1375
754 msdemlei 5051
755     The \xmlel{vs:TableSchema} type collects
756 rplante@ncsa.uiuc.edu 1375 tables together that are logically related. For example, a single
757     resource may provide access several major astronomical catalogs
758     (e.g. SDSS, 2MASS, and FIRST) from one site, enabling high-performance
759     cross-correlations between them. Each catalog can be described in a
760 msdemlei 5051 separate \xmlel{schema} element, using the elements from
761     the \xmlel{vs:TableSchema} type.
762 rplante@ncsa.uiuc.edu 1375
763    
764    
765 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd TableSchema
766     % /GENERATED
767 rplante@ncsa.uiuc.edu 1375
768    
769 msdemlei 5051 Each table in a schema is described in detail using the
770     \xmlel{vs:Table} type.
771 rplante@ncsa.uiuc.edu 1375
772    
773    
774 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd Table
775     % /GENERATED
776 rplante@ncsa.uiuc.edu 1375
777    
778    
779    
780     Each column in a table can be described using the
781 msdemlei 5051 \xmlel{vs:TableParam} type which is described in
782     section~\ref{sect:param}. The foreign keys in the table that
783 rplante@ncsa.uiuc.edu 1375 can be used to join it with another table can be described with the
784 msdemlei 5051 \xmlel{vs:ForeignKey} type (section~\ref{sect:fkey}).
785 rplante@ncsa.uiuc.edu 1375 A foreign key description should only refer to tables described within
786     the current table set.
787    
788    
789    
790 msdemlei 5051 The \xmlel{vs:Table} also provides an attribute for indicating
791     the role a table plays in the schema.
792 rplante@ncsa.uiuc.edu 1375
793    
794    
795    
796    
797 msdemlei 5051 \subsubsection{Unique Names for Tables}
798     \label{sect:unique}
799 rplante@ncsa.uiuc.edu 1375
800 msdemlei 5051
801     The definitions of the \xmlel{tableset} elements used in
802     the \xmlel{vs:DataCollection} and
803     \xmlel{vs:CatalogService} types
804 rplante@ncsa.uiuc.edu 1375 constrain certain names to be unique. In particular, all schema names
805 msdemlei 5051 within a \xmlel{tableset} element must be unique, and all
806     table names within a \xmlel{tableset} element must be
807 rplante@ncsa.uiuc.edu 1375 unique. (A schema and table may share a common name, such as
808 msdemlei 5051 ``default''.) These constraints makes it possible to uniquely locate
809 rplante@ncsa.uiuc.edu 1375 the description of a schema or table within a VOResource description.
810    
811    
812 msdemlei 5051 \begin{admonition}{Remark}
813     The uniqueness constraints for names
814 rplante@ncsa.uiuc.edu 1375 within table sets guarantee that when the following XPath queries are
815 msdemlei 5051 applied to a \xmlel{tableset} element, zero or one node
816 rplante@ncsa.uiuc.edu 1375 only will be returned:
817    
818 msdemlei 5051 \begin{itemize}
819     \item\verb|schema[@name="default"]|
820     \item\verb|schema/table[@name="default"]|
821     \end{itemize}
822 msdemlei 5055 \end{admonition}
823 msdemlei 5051
824 rplante@ncsa.uiuc.edu 1375 Name uniqueness is only required when the table set description is
825     part of a VOResource description. The name uniqueness rules
826 msdemlei 5051 \emph{should} also be applied to other uses of the
827     \xmlel{vs:TableSet} element outside of a VOResource
828 rplante@ncsa.uiuc.edu 1375 description.
829    
830    
831 msdemlei 5051 \subsubsection{Foreign Keys}
832     \label{sect:fkey}
833    
834    
835     The \xmlel{vs:ForeignKey} type allows one to describe foreign
836 rplante@ncsa.uiuc.edu 1375 keys in a table that allow it to be joined effectively with another
837     table. A foreign key is a set of columns that map to a corresponding
838     set of columns in another table.
839    
840    
841 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd ForeignKey
842     % /GENERATED
843    
844    
845 rplante@ncsa.uiuc.edu 1375 In this model, the source of the foreign
846     key is the current table being described (i.e. represented by the
847 msdemlei 5051 \xmlel{table} element that contains the
848     \xmlel{vs:ForeignKey} description, and thus does not need to be
849 rplante@ncsa.uiuc.edu 1375 named explicitly). The key that is described points to the table
850 msdemlei 5051 given by the \xmlel{targetTable} child element. Each child
851     \xmlel{fkColumn} element then gives a pair of columns, one
852 rplante@ncsa.uiuc.edu 1375 from the source table and one from the target table, that can be
853     constrained to be equal in a query that joins the two tables.
854    
855    
856    
857    
858    
859    
860 msdemlei 5051 \subsubsection{Extending Table Metadata}
861     \label{sect:tblext}
862 rplante@ncsa.uiuc.edu 1375
863     It is envisioned that it may be useful in the future to provide richer
864     metadata for describing tables within a VOResource description than
865     what are defined in this document. This document recommends the
866     use of the following extension mechanisms when richer descriptions are
867     desired:
868    
869 msdemlei 5055 \begin{enumerate}
870 msdemlei 5051 \item Use extended types by applying the \xmlel{xsi:type}
871     attribute to the \xmlel{tableset},
872     \xmlel{schema}, \xmlel{table},
873     \xmlel{column} and/or
874     \xmlel{dataType} elements. The values provided in the
875 rplante@ncsa.uiuc.edu 1375 attributes must refer to an XML type legally extended from the types
876     associated with these elements according to the rules of XML Schema
877 msdemlei 5051 \citep{schema} and the VOResource specification
878     \citep{VOR}.
879 rplante@ncsa.uiuc.edu 1375
880 msdemlei 5051 \item Apply a globally-defined attribute from a schema other than
881 rplante@ncsa.uiuc.edu 1375 VODataService (i.e. from a namespace other than
882 msdemlei 5051 \url{http://www.ivoa.net/xml/VODataService/v1.1} to any of the
883     \xmlel{tableset}, \xmlel{schema},
884     \xmlel{table}, and/or \xmlel{column}
885     elements.
886 rplante@ncsa.uiuc.edu 1375
887 msdemlei 5051 \item When the extended metadata is specific to how the table data is
888 rplante@ncsa.uiuc.edu 1375 accessed via a particular service protocol, then the new
889 msdemlei 5051 metadata can be incorporated into a specific capability
890     extension (as described in the VOResource specification
891     \citep{VOR}). This extension may make use of the
892     various names within the \xmlel{tableset} to
893     indicate where the extension metadata apply.
894 rplante@ncsa.uiuc.edu 1375
895 msdemlei 5051 \item Use the \xmlel{extendedType} attribute of the
896     \xmlel{dataType} element (see
897     section~\ref{sect:tbldatatypes}).
898 rplante@ncsa.uiuc.edu 1375 to indicate a more specific data type then those defined by the
899 msdemlei 5051 \xmlel{vs:TableParam} type.
900 msdemlei 5055 \end{enumerate}
901 rplante@ncsa.uiuc.edu 1375
902 msdemlei 5051 \subsection{Interface Type Extension: ParamHTTP}
903     \label{sect:paramif}
904 rplante@ncsa.uiuc.edu 1375
905 msdemlei 5051
906     The \xmlel{vs:ParamHTTP} type is a specialized service interface
907     description that extends the VOResource \xmlel{vr:Interface} type
908     (as recommended by \citep{VOR}, section 2.3.2\todo{check}). It
909 rplante@ncsa.uiuc.edu 1375 describes a service interface that is invoke over HTTP via a GET or a
910 msdemlei 5051 POST \citep{HTTP} in which the inputs are parameters
911     encoded as \emph{name=value} pairs, delimited by ampersands
912     (\verb|&|) and URL-encoded \citep{URI}. When
913 rplante@ncsa.uiuc.edu 1375 the service is invoked as a GET service, this input list is appended
914     to a base URL (where the result must form a legal URL. Usually, the
915 msdemlei 5051 URL contains a question mark (\verb|?|) setting off a list of
916     URL arguments to the URL.
917 rplante@ncsa.uiuc.edu 1375
918    
919 msdemlei 5051
920 rplante@ncsa.uiuc.edu 1375 When the service is invoked as a POST, the encoded list of parameters
921     are uploaded to the service as the HTTP Message Body.
922    
923    
924 msdemlei 5051 The \xmlel{vs:ParamHTTP} type is intended for (but not limited
925 rplante@ncsa.uiuc.edu 1375 to) use in describing an interface within a VOResource description of
926 msdemlei 5051 a service capability (as described in \citep{VOR},
927     section 2.2.2\todo{check}); that is, it can be invoked via the
928     \xmlel{xsi:type} attribute on an \xmlel{interface}
929 rplante@ncsa.uiuc.edu 1375 element.
930    
931    
932 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd ParamHTTP
933     % /GENERATED
934 rplante@ncsa.uiuc.edu 1375
935     The extension metadata defined in the schema definition above are all
936 msdemlei 5051 optional. Nevertheless, even when an \xmlel{interface}
937 rplante@ncsa.uiuc.edu 1375 instance does not include any of these extended child elements, the
938 msdemlei 5051 use of \verb|xsi:type="vs:ParamHTTP"| indicates that the interface
939     accessed via the URL given by the \xmlel{accessURL}
940 rplante@ncsa.uiuc.edu 1375 element complies with the general parameter-based protocol described
941     in this section.
942    
943    
944 msdemlei 5051
945    
946    
947    
948     A important intended use of the \xmlel{vs:ParamHTTP} type is
949 rplante@ncsa.uiuc.edu 1375 describing the interface of an IVOA standard service protocol
950 msdemlei 5051 of the ``simple'' variety, such as the Simple Image Access Protocol
951     \citep{SIA}. In particular, it is recommended that
952 rplante@ncsa.uiuc.edu 1375 specifications that define how a standard service is registered in a
953 msdemlei 5051 registry \emph{require} the use of the \xmlel{vs:ParamHTTP}
954 rplante@ncsa.uiuc.edu 1375 interface type when it is applicable.
955    
956 msdemlei 5051
957    
958 rplante@ncsa.uiuc.edu 1375 Normally, a VOResource
959     description indicates its support for a standard protocol with
960 msdemlei 5051 \xmlel{capability} element having a
961     \xmlel{standardID} attribute set to specific URI representing the
962 rplante@ncsa.uiuc.edu 1375 standard. The standard will usually spell out the HTTP query type,
963 msdemlei 5051 the returned media type, and input parameters required for compliance;
964     therefore, it is not necessary that the \xmlel{vs:ParamHTTP}
965 rplante@ncsa.uiuc.edu 1375 description provide any of the optional extended metadata, as they are
966 msdemlei 5051 already implied by the \xmlel{standardID}. The description need
967 rplante@ncsa.uiuc.edu 1375 only reflect the optional or locally unique features of the
968     interface. In particular, description may include
969    
970 msdemlei 5051
971     \begin{itemize}
972     \item a \xmlel{queryType} element for a type that is not
973 rplante@ncsa.uiuc.edu 1375 required by the standard (as long as the required query type is
974 msdemlei 5051 supported as well),
975 rplante@ncsa.uiuc.edu 1375
976 msdemlei 5051 \item \xmlel{param} elements for any optional parameters
977     or local extended parameters (when allowed by the standard).
978     \end{itemize}
979 rplante@ncsa.uiuc.edu 1375
980 msdemlei 5051
981 rplante@ncsa.uiuc.edu 1375 Of course, listing required parameters is always allowed, even when
982     describing a standard interface as long as these are consistent with
983 msdemlei 5051 the service specification and the corresponding \xmlel{param}
984     elements include the attribute \verb|use="required"| (see
985 msdemlei 5055 section~\ref{sect:inputparam}. The \xmlel{param}
986 rplante@ncsa.uiuc.edu 1375 elements for custom parameters that are not part of the standard (but
987     are rather local customizations) should include the attribute
988 msdemlei 5051 \verb|std="false"|.
989 rplante@ncsa.uiuc.edu 1375
990    
991    
992    
993    
994 msdemlei 5051 \subsection{Data Parameters}
995     \label{sect:param}
996    
997    
998 rplante@ncsa.uiuc.edu 1375 The VODataService schema provides several element types for describing
999     different kinds of data parameters used in datasets and services,
1000     including service input parameters and table columns. The parameter
1001     types allow one to fully describe a parameter in terms of metadata
1002     that includes name, data type, and meaning.
1003    
1004 msdemlei 5051
1005 rplante@ncsa.uiuc.edu 1375 All the VODataService parameter types derive from a base type called
1006 msdemlei 5051 \xmlel{vs:BaseParam} which defines all the common parameter
1007 rplante@ncsa.uiuc.edu 1375 metadata except the data type.
1008    
1009    
1010 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd BaseParam
1011     % /GENERATED
1012 rplante@ncsa.uiuc.edu 1375
1013 msdemlei 5051 Leaving the data type metadatum out of \xmlel{vs:BaseParam}
1014 rplante@ncsa.uiuc.edu 1375 allows the different kinds of parameters derived from
1015 msdemlei 5051 \xmlel{vs:BaseParam} to restrict the allowed data types to
1016 rplante@ncsa.uiuc.edu 1375 specific sets. The subsections below describe the different data
1017     types associated with input parameters
1018 msdemlei 5051 (\xmlel{vs:InputParam}) and table
1019     columns (\xmlel{vs:TableParam}). The
1020     XML types associated with their \xmlel{dataType} elements
1021     derive from a common parent, \xmlel{vs:DataType}.
1022 rplante@ncsa.uiuc.edu 1375
1023    
1024 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd DataType
1025     % /GENERATED
1026    
1027     The content of an element of type \xmlel{vs:DataType} is the name
1028 rplante@ncsa.uiuc.edu 1375 of the data type for the current parameter. When the element is explicitly
1029 msdemlei 5051 a \xmlel{vs:DataType} (as opposed to one of its derived types),
1030 rplante@ncsa.uiuc.edu 1375 there are no restrictions on the names that may be included.
1031    
1032 msdemlei 5051
1033    
1034 rplante@ncsa.uiuc.edu 1375 A data type description can be augmented via a common set of
1035 msdemlei 5051 \xmlel{vs:DataType} attributes, defined below. The
1036     \xmlel{arraysize} attribute indicates the parameter is an array
1037 rplante@ncsa.uiuc.edu 1375 of values of the named type. Its value describes the shape of the
1038 msdemlei 5051 array, and the \xmlel{delim} attribute may be used to indicate
1039 rplante@ncsa.uiuc.edu 1375 the delimiter that should appear between elements of an array value.
1040     Depending on the application context, these attribute may not be
1041     enough to effectively parse the array values, in which case more
1042     information must be brought to bear either through assumptions about
1043 msdemlei 5051 a particular derived \xmlel{vs:DataType} or through additional
1044 rplante@ncsa.uiuc.edu 1375 attributes.
1045    
1046 msdemlei 5051
1047    
1048 rplante@ncsa.uiuc.edu 1375 More descriptive information about the type can be provided via
1049 msdemlei 5051 \xmlel{extendedType} and \xmlel{extendedSchema}, which
1050     provide an alternate data type name. It is expected that this name
1051 rplante@ncsa.uiuc.edu 1375 will only be understood by a special subset of applications. The name
1052     given in the element content, then, represents a more commonly
1053     understood "fall-back" type. Arbitrary information can also be
1054     provided via any prefix-qualified, globally defined attribute drawn
1055     from an XML Schema other than VODataService (by virtue of the
1056 msdemlei 5051 \xmlel{xs:anyAttribute} specification present
1057     on \xmlel{vs:DataType}).
1058 rplante@ncsa.uiuc.edu 1375
1059    
1060    
1061    
1062    
1063     Note that in the derived parameter description types described below,
1064 msdemlei 5051 the \xmlel{dataType} element is optional. Its absence
1065     from the parameter description does \emph{not} mean that the
1066 rplante@ncsa.uiuc.edu 1375 parameter can support any data type; rather, it means that the data
1067     type simply has not been provided (which may limit what an application
1068     can do with the parameter). If a parameter can truly support any data
1069 msdemlei 5051 type, the \xmlel{vs:BaseParam} type can be used directly when the
1070 rplante@ncsa.uiuc.edu 1375 context permits.
1071    
1072    
1073 msdemlei 5051 \subsubsection{Input Parameters}
1074     \label{sect:inputparam}
1075    
1076    
1077 rplante@ncsa.uiuc.edu 1375 Actual parameters are normally described with types derived from
1078 msdemlei 5051 \xmlel{vs:BaseParam}. The \xmlel{vs:InputParam} is intended
1079 rplante@ncsa.uiuc.edu 1375 for describing an input parameter to a service or function. The
1080     allowed data type names (given in the metadata table below) do not
1081     imply a size or precise format; rather, they are intended to be
1082     sufficient for describing an input paramter to a simple REST-like
1083     service or a function in a weakly-typed (e.g. scripting) language.
1084    
1085    
1086 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd InputParam
1087     % /GENERATED
1088 rplante@ncsa.uiuc.edu 1375
1089 msdemlei 5051
1090     By fixing the \xmlel{dataType} child element to that of the
1091     \xmlel{vs:SimpleDataType}, the possible types are restricted to
1092 rplante@ncsa.uiuc.edu 1375 predefined set appropriate for input parameters.
1093    
1094    
1095 msdemlei 5051
1096     The \xmlel{vs:InputParam} type accepts two attributes that
1097 rplante@ncsa.uiuc.edu 1375 indicate the role that the parameter plays as input to the service or
1098 msdemlei 5051 function.
1099 rplante@ncsa.uiuc.edu 1375
1100    
1101 msdemlei 5051 Here is an example for a description
1102     of an input parameter that might appear inside an
1103     \xmlel{vs:ParamHTTP} interface description. As noted in
1104     section~\ref{sect:paramif}, a \xmlel{param}
1105     element uses the \xmlel{vs:InputParam} type to describe itself:
1106 rplante@ncsa.uiuc.edu 1375
1107 msdemlei 5051 \begin{lstlisting}[language=XML]
1108     <param use="required">
1109     <name> radius </name>
1110     <description>
1111 rplante@ncsa.uiuc.edu 1375 search radius; returned objects are restricted to fall
1112     within this angular distance of the search position.
1113 msdemlei 5051 </description>
1114     <ucd> phys.angSize </ucd>
1115     <dataType> real </dataType>
1116     </param>
1117     \end{lstlisting}
1118 rplante@ncsa.uiuc.edu 1375
1119 msdemlei 5051 \subsubsection{Table Columns}
1120     \label{sect:columns}
1121 rplante@ncsa.uiuc.edu 1375
1122 msdemlei 5051
1123     The \xmlel{vs:TableParam} is also derived from
1124     \xmlel{vs:BaseParam}, and is designed for describing a column of
1125 rplante@ncsa.uiuc.edu 1375 a table.
1126    
1127    
1128 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd TableParam
1129     % /GENERATED
1130 rplante@ncsa.uiuc.edu 1375
1131    
1132 msdemlei 5051 A table column's data type is indicated with the \xmlel{dataType}
1133 rplante@ncsa.uiuc.edu 1375 element with a name drawn from a standard set of names. The
1134 msdemlei 5051 \xmlel{vs:TableParam} type is not restricted to a single standard
1135 rplante@ncsa.uiuc.edu 1375 set, and the VODataService schema defines two standard sets: one
1136 msdemlei 5051 corresponding to VOTable data types \citep{VOTable}
1137 rplante@ncsa.uiuc.edu 1375 and one for Table Access Protocol types. Because
1138 msdemlei 5051 its XML type, \xmlel{vs:TableDataType} is abstract, the
1139     \xmlel{dataType} element MUST include an
1140     \xmlel{xsi:type} attribute to indicate which standard set of type
1141 rplante@ncsa.uiuc.edu 1375 names is being used.
1142    
1143    
1144 msdemlei 5051 As an example, here is a declination column called ``Dec'' and is
1145     defined to have the VOTable-defined type double:
1146 rplante@ncsa.uiuc.edu 1375
1147 msdemlei 5051 \begin{lstlisting}[language=XML]
1148     <column>
1149     <name> Dec </name>
1150     <description> the J2000 declination of the object </description>
1151     <ucd> pos.eq.dec </ucd>
1152     <dataType xsi:type="vs:VOTableType"> double </dataType>
1153     </column>
1154     \end{lstlisting}
1155 rplante@ncsa.uiuc.edu 1375
1156    
1157 msdemlei 5051 \subsubsection{Table Column Data Types}
1158     \label{tbldatatypes}
1159 rplante@ncsa.uiuc.edu 1375
1160 msdemlei 5051
1161 rplante@ncsa.uiuc.edu 1375 The VODataService schema defines two XML types that derive from
1162 msdemlei 5051 \xmlel{vs:TableDataType}: \xmlel{vs:VOTableType} and
1163     \xmlel{vs:TAPType}.
1164 rplante@ncsa.uiuc.edu 1375
1165    
1166 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd VOTableType
1167     % /GENERATED
1168 rplante@ncsa.uiuc.edu 1375
1169 msdemlei 5051 % GENERATED: !schemadoc VODataService-v1.2.xsd TAPType
1170     % /GENERATED
1171 rplante@ncsa.uiuc.edu 1375
1172    
1173    
1174 msdemlei 5051
1175     The \xmlel{vs:TAPType} XML type provides an additional attribute,
1176     \xmlel{size}, corresponding to the \verb|"size"| column from the
1177 msdemlei 5055 TAP\_SCHEMA.columns defined by the TAP standard
1178 msdemlei 5051 \citep{TAP}.\todo{deprecate}
1179    
1180    
1181    
1182    
1183     Examples for column definitions:
1184     A representation of a string type using the
1185     \xmlel{vs:VOTableType} set of types:
1186    
1187     \begin{lstlisting}
1188     <column>
1189     <name> id </name>
1190     <description> the object identifier </description>
1191     <ucd> meta.id </ucd>
1192     <dataType xsi:type="vs:VOTableType" arraysize="*"> char </dataType>
1193     </column>
1194     \end{lstlisting}
1195    
1196     The same column described using the
1197     \xmlel{vs:TAPType} set of types:\todo{deprecate this}
1198    
1199     \begin{lstlisting}
1200     <column>
1201     <name> id </name>
1202     <description> the object identifier </description>
1203     <ucd> meta.id </ucd>
1204     <dataType xsi:type="vs:TAPType"> VARCHAR </dataType>
1205     </column>
1206     \end{lstlisting}
1207    
1208     The same column again described using the
1209     \xmlel{vs:TAPType} set of types, assuming a fixed-length
1210     string:\todo{deprecate this}
1211    
1212     \begin{lstlisting}
1213     <column>
1214     <name> id </name>
1215     <description> the object identifier </description>
1216     <ucd> meta.id </ucd>
1217     <dataType xsi:type="vs:TAPType" size="8" > CHAR </dataType>
1218     </column>
1219     \end{lstlisting}
1220    
1221    
1222    
1223     In general, the \xmlel{vs:TableParam}'s \xmlel{dataType}
1224 rplante@ncsa.uiuc.edu 1375 can support any non-abstract type legally derived from
1225 msdemlei 5051 \xmlel{vs:TableDataType}. However, in the context of a
1226     \xmlel{vs:DataCollection} or \xmlel{vs:CatalogService}
1227 rplante@ncsa.uiuc.edu 1375 resource description, it is strongly recommended that either
1228 msdemlei 5051 \xmlel{vs:VOTableType} or \xmlel{vs:TAPType} (or some other IVOA
1229     standard type derived from \xmlel{vs:TableDataType}) be used to
1230 rplante@ncsa.uiuc.edu 1375 ensure maximum interoperability. When the actual column type is not
1231     well matched to a type from one of these standard sets, authors are
1232 msdemlei 5051 encouraged to use the \xmlel{extendedType} attribute to refer to
1233 rplante@ncsa.uiuc.edu 1375 a more specific type. Note that the TAP standard
1234 msdemlei 5051 \citep{TAP} defines an explicit mapping between
1235 msdemlei 5055 TAP\_SCHEMA types and VOTable types. Thus, in the context of a
1236 msdemlei 5051 \xmlel{vs:CatalogService} resource description that supports a
1237 rplante@ncsa.uiuc.edu 1375 TAP capability (perhaps in addition to other catalog services like
1238 msdemlei 5051 Simple Cone Search \citep{SCS}), use of the
1239     \xmlel{vs:TAPType} data type is preferred.
1240 rplante@ncsa.uiuc.edu 1375
1241 msdemlei 5051
1242    
1243     \begin{admonition}{Note}
1244     The motivation for providing two standard data type sets,
1245     \xmlel{vs:VOTableType} and \xmlel{vs:TAPType}, is to maximize
1246 rplante@ncsa.uiuc.edu 1375 the ease of generating the table description, particular as
1247 msdemlei 5051 part of the VO Standard Interface \citep{VOSI}
1248 rplante@ncsa.uiuc.edu 1375 and for legacy services. The table description for
1249 msdemlei 5051 ``stand-alone'' SIA, SCS, and SSA services can be readily
1250     generated using the \xmlel{vs:VOTableType} data types from
1251 rplante@ncsa.uiuc.edu 1375 these interface's respective metadata queries. Newer services
1252     supporting TAP could generate its description using its
1253 msdemlei 5055 TAP\_SCHEMA queries.
1254 rplante@ncsa.uiuc.edu 1375
1255 msdemlei 5051
1256 rplante@ncsa.uiuc.edu 1375 The motivation for specifying a column's data type using the
1257 msdemlei 5051 \xmlel{xsi:type} mechanism is mainly to allow for the
1258 rplante@ncsa.uiuc.edu 1375 possibility that the official TAP data types will evolve. This
1259     allows the IVOA to define new data type sets without updating
1260     the VODataService standard. Using non-IVOA-standardized data
1261     type names is expected to undermine interoperability and so is
1262     therefore discouraged.
1263 msdemlei 5051 \end{admonition}
1264 rplante@ncsa.uiuc.edu 1375
1265 msdemlei 5051 \appendix
1266 rplante@ncsa.uiuc.edu 1375
1267 msdemlei 5051 \section{Compatibility Issues with VODataService 1.0}
1268 msdemlei 5055 \label{vods10-compat}
1269 rplante@ncsa.uiuc.edu 1375
1270     The working draft version 1.0 of the VODataService schema has been in
1271 msdemlei 5051 use in IVOA registries since about 2008\todo{Do we want to keep this?
1272     I'd say no}. It is expected that
1273 rplante@ncsa.uiuc.edu 1375 registries will migrate over to version 1.1 gradually and during the
1274     transition, there may well be instances of both v1.1 and v1.0 in the
1275     same registry. While the metadata structures are the mostly the same
1276     (particularly the core VOResource metadata), it is worth enumerating
1277     where they are different as this can affect how queries against
1278     differing metadata are formed.
1279    
1280 msdemlei 5051 \begin{itemize}
1281     \item In v1.1, \xmlel{schema} replaces v1.0's
1282     \xmlel{catalog}.
1283 rplante@ncsa.uiuc.edu 1375
1284 msdemlei 5051 \item In v1.0, the root element of a table description in a
1285     \xmlel{vs:DataCollection} was
1286     \xmlel{catalog}. Consequently, a
1287     \xmlel{table} element in a v1.1 record is one
1288     level lower than in v1.0.
1289 rplante@ncsa.uiuc.edu 1375
1290 msdemlei 5051 \item In v1.0, the root element of a table description in a
1291     \xmlel{vs:CatalogService} was
1292     \xmlel{table}. Consequently, a
1293     \xmlel{table} element in a v1.1 record is one
1294     level lower than in v1.0.
1295 rplante@ncsa.uiuc.edu 1375
1296 msdemlei 5051 \item Version 1.1's \xmlel{vs:Coverage} type now
1297     contains a \xmlel{regionOfRegard} element. In
1298 rplante@ncsa.uiuc.edu 1375 v1.0, this metadatum was only available via
1299 msdemlei 5051 \xmlel{coverage/stc:STCResourceProfile/stc:AstroCoord/stc:Size}.
1300    
1301 rplante@ncsa.uiuc.edu 1375
1302 msdemlei 5051 \item Version 1.1's \xmlel{vs:TableParam} (for describing table
1303     columns) adds \xmlel{utype} and
1304     \xmlel{flag} elements. The v1.1
1305     \xmlel{vs:InputParam} adds a \xmlel{utype}
1306     element.
1307 rplante@ncsa.uiuc.edu 1375
1308 msdemlei 5051 \end{itemize}
1309 rplante@ncsa.uiuc.edu 1375
1310    
1311 msdemlei 5051 \section{Changes from previous versions}
1312 rplante@ncsa.uiuc.edu 1375
1313 msdemlei 5051 \subsection{Changes from REC-1.1}
1314 rplante@ncsa.uiuc.edu 1375
1315 msdemlei 5051 \begin{itemize}
1316     \item Ported source to \ivoatex.
1317     \end{itemize}
1318 rplante@ncsa.uiuc.edu 1375
1319 msdemlei 5051 \subsection{Changes since PR-20100916}
1320 rplante@ncsa.uiuc.edu 1375
1321 msdemlei 5051 \begin{itemize}
1322     \item updated status for elevation to Recommendation.
1323     \item cleaned-up mis-labeled and mis-ordered change history.
1324     \end{itemize}
1325 rplante@ncsa.uiuc.edu 1375
1326 msdemlei 5051 \subsection{Changes since PR-20100914}
1327 rplante@ncsa.uiuc.edu 1375
1328 msdemlei 5051 \begin{itemize}
1329     \item added change history for PR-20100412.
1330     \item added Note about STC mark-up in 3.2
1331     \item reworded sentence describing content of \xmlel{vs:DataType} in
1332     section 3.5.
1333     \end{itemize}
1334 rplante@ncsa.uiuc.edu 1375
1335 msdemlei 5051 \subsection{Changes since PR-20100412}
1336 rplante@ncsa.uiuc.edu 1375
1337 msdemlei 5051 \begin{itemize}
1338     \item fix numerous typos discovered in TCG review
1339     \item added section 1.1 to describe role of standard in the VO
1340     architecture, including diagram.
1341     \item corrected frequency range for the UV waveband
1342     \item corrected links to reference documents
1343     \end{itemize}
1344 rplante@ncsa.uiuc.edu 1375
1345 msdemlei 5051 \subsection{Changes since PR-20090903}
1346 rplante@ncsa.uiuc.edu 1375
1347 msdemlei 5051 \begin{itemize}
1348 msdemlei 5055 \item added \xmlel{testQuery}
1349 msdemlei 5051 to \xmlel{vs:ParamHTTP}
1350 msdemlei 5055 \item in text, added explanation of
1351 msdemlei 5051 \xmlel{vs:Format}
1352     \item grammatical clean-up
1353     \end{itemize}
1354 rplante@ncsa.uiuc.edu 1375
1355 msdemlei 5051 \subsection{Changes since WD-20090508 (v1.10)}
1356    
1357     \begin{itemize}
1358 msdemlei 5055 \item corrected errors in example in Introduction
1359 msdemlei 5051 \item added \xmlel{description} and
1360     \xmlel{utype} elements to the
1361     \xmlel{vs:ForeignKey} type for consistency with TAP.
1362     \item changed type names \xmlel{vs:TAP} to
1363     \xmlel{vs:TAPType} and \xmlel{vs:VOTable}
1364     \xmlel{vs:VOTableType}.
1365     \end{itemize}
1366    
1367 msdemlei 5055 \end{document}

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