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

Contents of /trunk/projects/registry/SimpleDALRegExt/SimpleDALRegExt.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5738 - (show annotations)
Tue Feb 25 07:23:07 2020 UTC (6 months, 4 weeks ago) by msdemlei
File MIME type: application/x-tex
File size: 87083 byte(s)
SimpleDALRegExt: Fixing author list typo, Delago -> Delgado.


1 \documentclass[11pt,a4paper]{ivoa}
2 % we widen up the page a bit so schema fragments with 80 chars/line
3 % don't cause overfull hboxes.
4 \usepackage[scale=0.75]{geometry}
5 \input tthdefs
6
7 \usepackage{listings}
8 \lstloadlanguages{XML}
9 \lstset{flexiblecolumns=true,tagstyle=\ttfamily, showstringspaces=False}
10
11 \title{Describing Simple Data Access Services}
12
13 \ivoagroup{Registry}
14
15 \author[http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante]{Raymond
16 Plante}
17 \author[http://www.ivoa.net/twiki/bin/view/IVOA/MarkusDemleitner]{Markus
18 Demleitner}
19 \author[http://www.ivoa.net/twiki/bin/view/IVOA/JesusDelgado]{Jesus Delgado}
20 \author[http://www.ivoa.net/twiki/bin/view/IVOA/PaulHarrison]{Paul Harrison}
21 \author[http://www.ivoa.net/twiki/bin/view/IVOA/DougTody]{Doug Tody}
22
23 \editor{Markus Demleitner}
24
25 \previousversion[http://ivoa.net/documents/SimpleDALRegExt/20170530/]{
26 REC-1.1}
27 \previousversion[http://ivoa.net/documents/SimpleDALRegExt/20160525/]{
28 WD-20160525}
29 \previousversion[http://www.ivoa.net/Documents/SimpleDALRegExt/20131005/]{
30 REC-1.0}
31
32 \begin{document}
33 \SVN$Rev$
34 \SVN$Date$
35 \SVN$URL$
36
37 \begin{abstract}
38 An application that queries or consumes descriptions of VO resources
39 must be able to recognize a resource's support for standard IVOA
40 protocols. This specification describes how to describe a service that
41 supports any of the four typed data access protocols -- Simple Cone
42 Search (SCS), Simple Image Access (SIA), Simple Spectral Access (SSA),
43 Simple Line Access (SLA) -- using the VOResource XML encoding standard. A
44 key part of this specification is the set of VOResource XML extension
45 schemas that define new metadata that are specific to those protocols.
46 This document describes rules for describing such
47 services within the context of IVOA Registries and data discovery as
48 well as the VO Support Interfaces (VOSI) and service self-description.
49 In particular, this document spells out the essential mark-up needed to
50 identify support for a standard protocol and the base URL required to
51 access the interface that supports that protocol.
52 \end{abstract}
53
54
55 \section*{Acknowledgements}
56
57 This document has been developed with support from the National
58 Science Foundation's Information Technology Research Program under
59 Cooperative Agreement AST0122449 with The Johns Hopkins University,
60 from the UK Particle Physics and Astronomy Research Council
61 (PPARC), from the Eurpean Commission's Sixth Framework Program
62 via the Optical Infrared Coordination Network (OPTICON), and from
63 BMBF grant 05A14VHA (GAVO).
64
65
66 \section*{Syntax Notation Using XML Schema}
67
68 The Extensible Markup Language, or XML, is document syntax for marking
69 textual information with named tags and is defined by the World Wide
70 Web Consortium (W3C) Recommendation, XML 1.0 \citep{std:XML}. The set of
71 XML tag names and the syntax rules for their use is referred to as the
72 document schema. One way to formally define a schema for XML documents
73 is using the W3C standard known as XML Schema \citep{std:XSD}
74
75 This document defines the VOResource schema using XML Schema. The full
76 Schema documents are kept on the IVOA schema
77 repository\footnote{\url{http://ivoa.net/xml/}}. The files given
78 there are authoritative and override XML schema fragments contained
79 in specification in case of conflicts.
80 Note that the schema files in the IVOA repository can change
81 over time according to the
82 rules laid down in \citet{note:schemaversioning}.
83
84 Reference to specific elements and types defined in the VOResource
85 schema include the namespaces prefix, \xmlel{vr:}, as in
86 \xmlel{vr:Resource}.
87 Reference to specific elements and
88 types defined in the VODataService extension schema include the
89 namespaces prefix, \xmlel{vs:}, as in \xmlel{vs:ParamHTTP}.
90 Use of the \xmlel{vs:} prefix in compliant instance
91 documents is strongly recommended, particularly in the applications
92 that involve IVOA Registries \citep{2009ivoa.spec.1104B}.
93 \section{Introduction}
94
95 Four data access service protocols play a key role in discovering data
96 in the VO:
97
98 \begin{itemize}
99 \item Simple Cone Search \citep{2008ivoa.specQ0222P} -- searches a catalog for sources or
100 observations that are within a given distance of a sky position.
101 \item Simple Image Access \citep{2015ivoa.spec.1223D} -- searches an
102 archive for spatially resolved data (like images and cubes)
103 that overlap a given region of sky.
104 \item Simple Spectral Access \citep{2012ivoa.spec.0210T} -- searches an archive for spectra
105 of positions within a given region of sky.
106 \item Simple Line Access \citep{2010ivoa.specQ1209O} -- searches a catalog specializing in
107 descriptions of spectral line transitions.
108 \end{itemize}
109
110 They are called ``simple'' because a typical query can be formed using
111 only a few search parameters encoded into a URL (i.e., an HTTP GET
112 request). Their power for data discovery comes from the ability of an
113 application to form a single query according to the rules of one of
114 these protocols and send it to multiple services selected, say, for
115 their relevence to a scientific topic which support that protocol. The
116 results collected from those services, in effect then, represent all
117 the relevent data of that type known to the VO. Thus, the key for an
118 application wishing to do a comprehensive search of the VO is to
119 discover all of the services that support the particular standard
120 protocol.
121
122 Service discovery in the VO is done via a searchable registry as
123 described by the Registry Interfaces standard
124 \citep{2009ivoa.spec.1104B} -- i.e., a searchable repository of descriptions of resources in
125 VO. These descriptions are comprised of common standard metadata as
126 specified in the Resource Metadata document
127 \citep{2007ivoa.spec.0302H} that capture information about what a resource contains or
128 does and who provides it. A standard registry encodes these
129 descriptions using the VOResource XML Schema \citep{2008ivoa.spec.0222P}. Service
130 resources in particular include capability metadata that describe the
131 functionality it supports along with interface metadata that describe
132 how to access that functionality. It is within the capability metadata
133 that it is possible to indicate support for a particular standard
134 protocol.
135
136 Capability metadata play an important role beyond just identifying
137 support for a standard interface. More generally, they describe how the
138 service behaves, and if applications are to make use of this
139 information in an automated way, the behavior must be described using
140 standardized metadata. In general, the metadata necessary for
141 describing that behavior will be specific to the particular kind of
142 service. In the case of a standard protocol, in which it is common that
143 some variation in behavior is allowed while still being in compliance,
144 it can be important to an application to know how a service complies
145 with the standard for two reasons:
146
147 \begin{enumerate}
148 \item The application may wish to search for and select services that
149 support a particular protocol feature. For example, an application
150 may wish to find image services that can create cut-outs
151 on-the-fly.
152 \item The application may wish to plan its use of the service according
153 its limitations, such as the maximum region of sky that can be
154 searched in one query.
155 \end{enumerate}
156
157 It is important to note that the relevent behavioral differences
158 between separate services that support a common protocol--and thus the
159 metadata used to describe those behaviors--will be specific to that
160 protocol. That is, for example, the ability to create image cut-outs is
161 irrelevent to the Simple Cone Search protocol. Consequently, it is
162 necessary to define protocol-specific metadata to adequately describe a
163 service's support for that protocol. This document defines such
164 capability metadata for SCS, SIA, SSA, and SLA.
165
166 This document describes for each of the standard data access
167 protocols -- SCS, SIA, SSA, and SLA -- precisely how to describe a service
168 that supports one of the protocols in terms of the VOResource XML
169 encoding standard. This specification is intended to be
170 applicable wherever VOResource records are used, but in particular, it
171 is intended as the standard for encoding resource descriptions within
172 an IVOA-compliant registry and for encoding capability
173 metadata available through the VO Support Interfaces VOSI
174 \citep{2011ivoa.spec.0531G}.
175
176 \subsection{The Role in IVOA Architecture}
177
178
179 \begin{figure}
180 \centering
181 \includegraphics[width=0.9\textwidth]{role_diagram.pdf}
182 \caption{SimpleDALRegExt in the IVOA Architecture}
183 \label{fig:archdiag}
184 \end{figure}
185
186 The IVOA Architecture \citep{note:VOARCH} provides a high-level view of how IVOA
187 standards work together to connect users and applications with
188 providers of data and services, as depicted in the diagram in
189 Fig.~\ref{fig:archdiag}.
190
191 In this architecture, data access protocols provide the means for users
192 (via the User Layer) to access data from archives. Of particular
193 importance are the standard protocols, SCS, SIA, SSA, and SLA, which
194 allow a generic user tool to find data in any archive that supports
195 those protocols. Registries provide to tools in the User Layer a means
196 to discover which archives support the standard protocols. A registry
197 is a repository of descriptions of resources, such as standard
198 services, that can be searched based on the metadata in those
199 descriptions.
200
201 The Registry enables applications in the User Layer to discover archives
202 in the Resource Layer and the services they provide for accessing data,
203 particularly those that support the standard data access protocols like
204 SIAP, SCS, SSAP, and SLAP (illustrated on the right). The registry
205 metadata model standards (in blue text and boxes on the left) give
206 structure to the information that enables that discovery. In
207 particular, the SimpleDALRegExt standard defines the metadata used to
208 describe standard data access services of the types listed on the right.
209
210
211 Resource descriptions have a well-defined structure: the core concepts
212 are defined in the Resource Metadata standard \citep{2007ivoa.spec.0302H}, and the format
213 is defined by the VOResource XML standard \citep{2008ivoa.spec.0222P}. Additional
214 metadata specialized to describe a specific kind of service are defined
215 via extensions to the VOResource core XML Schema. SimpleDALRegExt is
216 one such extension specifically for describing SCS, SIA, SSA, and SLA
217 services in the registry.
218
219
220 \subsection{Dependencies on Other Standards}
221
222 This specification relies directly on other IVOA standards in the
223 following ways:
224
225 \begin{bigdescription}
226 \item[VOResource, v1.03 \citep{2008ivoa.spec.0222P}]
227 Descriptions of services that support the standard protocols are
228 encoded using the VOResource XML Schema. The protocol-specific
229 schemas defined in this document are extensions of the
230 VOResource core schema.
231
232 \item[Typed DAL Protocols]
233 The standards Simple Cone Search, v1.03 \citep{2008ivoa.specQ0222P},
234 Simple Image Access, v1.0 \citep{2009ivoa.spec.1111H},
235 Simple Image Access, v2.0 \citep{2015ivoa.spec.1223D},
236 Simple Spectral Access, v1.04 \citep{2012ivoa.spec.0210T}, and
237 Simple Line Access, v1.0 \citep{2010ivoa.specQ1209O}
238 describe the metadata concepts that should be included in a
239 description of a service that supports the specification.
240 We expect future versions of these standards to provide their
241 own metadata schemes. Unless they do, however, the relevant
242 metadata scheme from this document should be used.
243
244 \item[VODataService, v1.1 \citep{2010ivoa.spec.1202P}]
245 The interface to the standard protocol functionality is
246 described with a specialized Interface type, vs:ParamHTTP, which
247 is defined in the VODataService XML Schema, an extension to
248 VOResource. This document also recommends describing the service
249 using VODataService resource type,
250 \xmlel{vs:CatalogDataService}.
251 \end{bigdescription}
252
253 This specification refers to other IVOA standards:
254
255 \begin{bigdescription}
256 \item[Registry Interfaces, v1.0 \citep{2009ivoa.spec.1104B}]
257 A registry that is compliant with both this specification and
258 the Registry Interfaces standard will encode service resource
259 descriptions according to the recommendations in this document.
260
261 \item[VO Support Interfaces, v1.0 \citep{2011ivoa.spec.0531G}]
262 A service that supports one of the target protocols as well as
263 the capability metadata retrieval method defined by VOSI
264 is compliant with this specification if
265 the capability metadata are encoded according the
266 recommendations in this document.
267 \end{bigdescription}
268
269 Unlike with the previously mentioned specifications, this specification
270 may apply to later versions of the RI and VOSI standards.
271
272 \section{The Common Data Model for Simple DAL Services}
273 \label{sect:dm}
274
275 This section describes common requirements for describing the target
276 DAL services as VOResource records.
277
278 To be recognized as a service, the DAL service resource must be
279 described as a resource type of \xmlel{vr:Service} (defined in the VOResource
280 schema) or one of its legal sub-types. As specified in the
281 VOResource specification, the resource type is set by setting
282 the \xmlel{xsi:type} attribute on the element representing the root of the
283 VOResource record to the namespace-qualified resource type name.
284
285 As the
286 DAL services respond to queries with tables of available data products,
287 their Registry records will typically be of the resource type
288 \xmlel{vs:CatalogService} (defined
289 in the VODataService extension schema). In this case, record
290 authors are encouraged to include a full description of the columns in
291 the table returned in query response (assuming full verbosity). The
292 \xmlel{vs:CatalogService} resource type also allows the record to provide sky
293 coverage information which authors are also encouraged to provide; an
294 exception to this would be for pure SLA services as the spectral line
295 catalogs they serve are not strictly sky observations.
296
297 The VOResource record must include a \xmlel{capability} element that
298 describes the services support for the DAL protocol. The contents of the
299 element is described in section~\ref{sect:describing}. In all cases, the
300 value of the \xmlel{capability} element's \xmlel{standardID}
301 unambiguously identifies the service's support for the particular DAL
302 protocol. The resource may include other \xmlel{capability} elements to
303 describe support for other protocols.
304
305 Note that, by the IVOA Identifiers standard \citep{2016ivoa.spec.0523D},
306 the scheme, authority, and path parts of ivoids must be compared
307 case-insensitively. That means that clients comparing standardIDs
308 obtained from, for instance, a VOSI capability endpoint, must normalise
309 them. The recommended normalisation is simply lowercasing them.
310
311 \begin{admonition}{Note}
312 In VO practice, many clients still discover the standard endpoints by looking
313 for \xmlel{capability} elements with the \xmlel{standardID} of the
314 protocol they are interested in and then locating a
315 \xmlel{vs:ParamHTTP}-typed \xmlel{interface} in it without regard for it
316 being marked up with \verb|role="std"|. While this practice should
317 cease in the years following 2019, and new clients have no reason to do
318 so any more, Resource record authors
319 should, for the time being, not include non-standard \xmlel{vs:ParamHTTP}
320 interfaces in capabilities with the \xmlel{standardID}s defined here.
321 \end{admonition}
322
323 The \xmlel{capability} element describing support for the DAL protocol
324 must include a child \xmlel{interface} element that describes support
325 for the required DAL interface; the \xmlel{xsi:type} attribute on that element
326 must be set to \xmlel{vs:ParamHTTP}, and the role attribute must be set
327 to \texttt{"std"}. A \xmlel{accessURL} element within that
328 \xmlel{interface} must be set to the base URL, as defined in the DAL
329 protocol specification, that provides access to the standard DAL
330 protocol. It is not necessary to provide the \xmlel{use} attribute to the
331 \xmlel{accessURL} element (as its value can be assumed); however, when
332 it is provided, it must be set to \texttt{"base"}. Similarly, it is not
333 necessary to provide the \xmlel{interface} element with
334 \xmlel{queryType} or \xmlel{resultType} elements; however, when
335 provided, their values should be \texttt{"GET"} and
336 \texttt{"application/x-votable+xml"}, respectively. The
337 \xmlel{vs:ParamHTTP} allows one to describe input parameters supported
338 by the service; description authors are encouraged to list the optional
339 parameters and any custom parameters supported by the instance of the
340 service.
341
342 Here is a sample interface description for a simple DAL service.
343
344 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
345 <interface xsi:type="vs:ParamHTTP" role="std">
346 <accessURL use="base">
347 http://adil.ncsa.uiuc.edu/cgi-bin/voimquery?survey=f&
348 </accessURL>
349
350 <!-- here is a standard, optional parameter -->
351 <param use="optional" std="true">
352 <name>CFRAME</name>
353 <description>request to shift to a given coordinate frame.</description>
354 <dataType>string</dataType>
355 </param>
356
357 <!-- here is a site-specific parameter that this service supports -->
358 <param use="optional" std="false">
359 <name>FREQ</name>
360 <description>Frequency of observation.</description>
361 <unit>Hz</unit>
362 <dataType>real</dataType>
363 </param>
364 </interface>
365 \end{lstlisting}
366
367 \section{Describing Standard Capabilities}
368 \label{sect:describing}
369
370 This section describes the specific VOResource metadata extension
371 schemas used to describe support for the target DAL protocols. The
372 purpose of these schemas are to provide the \xmlel{vr:Capability} sub-type that
373 identifies the specific protocol. These are defined employing the
374 recommendations for \xmlel{vr:Capability} extensions given in the VOResource
375 standard. In particular, each extension schema has the
376 following features:
377
378 \begin{itemize}
379 \item The namespace associated with the extension is a URI that is
380 intended to resolve an HTTP URL to XML Schema document that defines
381 the extension schema. This means that VOResource document authors
382 may use this URI as the location URL within the value of
383 \xmlel{xsi:schemaLocation} attribute.
384 Note that the IVOA Registry Interface standard actually
385 requires that the VOResource records it shares with other
386 registries provide location URLs via
387 \xmlel{xsi:schemaLocation}
388 for the VOResource schema and all legal extension schemas
389 that are used in the records. This rule would apply to the
390 extension schemas defined in this standard.
391
392 \item A particular namespace prefix is recommended for use when referring
393 to the specialized \xmlel{vr:Capability} sub-type defined in the schema.
394 In general XML applications, instance documents may use any prefix;
395 however, in a VO context, document authors are strongly advised
396 to use the canonical prefixes given (and used) in this document
397 to avoid confusion when raw XML is exposed to the users. This
398 means that documents should not use two different versions of a
399 given schema (as defined by a common canonical prefix) within the
400 same namespace mapping; documents for which this is impossible
401 are probably semantically invalid.
402
403 \item Following VOResource practice, the schema sets
404 \xmlel{elementFormDefault} to \verb|"unqualified"|. This means that
405 element names defined in the schema do not take a namespace
406 prefix (as there are no global elements defined).
407 The only place namespaced names occur in SimpleDALRegExt instance
408 elements is the
409 Capability sub-type name given as the value of an
410 \xmlel{xsi:type}
411 attribute on the \xmlel{capability} element (see the examples in the
412 subsections below).
413 \item The specialized \xmlel{vr:Capability} sub-type includes a
414 \xmlel{testQuery}
415 element for encoding parameters that together can be used to test
416 the service. The format for encoding the individual parameters is
417 customized for each of the four simple services covered in this
418 specification.
419 \end{itemize}
420
421 \subsection{Simple Cone Search}
422
423 This section describes the ConeSearch VOResource metadata extension
424 schema which is used to describe services that comply with the Simple
425 Cone Search protocol \citep{2008ivoa.specQ0222P}.
426
427 \subsubsection{The Standard Identifier}
428
429 The \xmlel{standardID} value for Simple Cone Search version 1.03 (and
430 before) is
431 $$\hbox{\nolinkurl{ivo://ivoa.net/std/ConeSearch} .}$$ Standard
432 identifiers for later versions will be given in the respective
433 standards.
434
435 \subsubsection{The Schema Namespace}
436
437 The namespace associated with the ConeSearch extension schema is
438 $$\hbox{\nolinkurl{http://www.ivoa.net/xml/ConeSearch/v1.0} ,}$$
439 the canoncical prefix is \xmlel{cs:}.
440
441 \subsubsection{ConeSearch}
442
443 The \xmlel{cs:ConeSearch} type is a \xmlel{vr:Capability} sub-type that should be used
444 to describe a service's support for the Simple Cone Search protocol;
445 it is defined as follows:
446
447 % GENERATED: !schemadoc ConeSearch-v1.1.xsd ConeSearch
448 \begin{generated}
449 \begingroup
450 \renewcommand*\descriptionlabel[1]{%
451 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{cs:ConeSearch} Type Schema Documentation}
452
453 \noindent{\small
454 The capabilities of a Cone Search implementation.
455 \par}
456
457 \vspace{1ex}\noindent\textbf{\xmlel{cs:ConeSearch} Type Schema Definition}
458
459 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
460 <xs:complexType name="ConeSearch" >
461 <xs:complexContent >
462 <xs:extension base="vr:Capability" >
463 <xs:sequence >
464 <xs:element name="maxSR" type="xs:float" minOccurs="0" maxOccurs="1" />
465 <xs:element name="maxRecords" type="xs:positiveInteger" minOccurs="0"
466 maxOccurs="1" />
467 <xs:element name="verbosity" type="xs:boolean" />
468 <xs:element name="testQuery" type="cs:Query" minOccurs="0"
469 maxOccurs="1" />
470 </xs:sequence>
471 </xs:extension>
472 </xs:complexContent>
473 </xs:complexType>
474 \end{lstlisting}
475
476 \vspace{0.5ex}\noindent\textbf{\xmlel{cs:ConeSearch} Extension Metadata Elements}
477
478 \begingroup\small\begin{bigdescription}\item[Element \xmlel{maxSR}]
479 \begin{description}
480 \item[Type] floating-point number: \xmlel{xs:float}
481 \item[Meaning]
482 The largest search radius, in degrees, that will be
483 accepted by the service without returning an error
484 condition. Not providing this element or
485 specifying a value of 180 indicates that there
486 is no restriction.
487
488 \item[Occurrence] optional
489 \item[Comment]
490 Not providing a value is the prefered way to indicate
491 that there is no restriction.
492
493
494 \end{description}
495 \item[Element \xmlel{maxRecords}]
496 \begin{description}
497 \item[Type] \xmlel{xs:positiveInteger}
498 \item[Meaning]
499 The largest number of records that the service will
500 return. Not providing this value means that
501 there is no effective limit.
502
503 \item[Occurrence] optional
504 \item[Comment]
505 This does not refer to the total number of records in
506 the catalog but rather maximum number of records the
507 service is capable of returning. A limit that is
508 greater than the number of records available in the
509 archive is equivalent to their being no effective
510 limit. (See RM, Hanisch 2007.)
511
512
513 \end{description}
514 \item[Element \xmlel{verbosity}]
515 \begin{description}
516 \item[Type] boolean (true/false): xs:boolean
517 \item[Meaning]
518 True if the service supports the VERB keyword;
519 false, otherwise.
520
521 \item[Occurrence] required
522
523 \end{description}
524 \item[Element \xmlel{testQuery}]
525 \begin{description}
526 \item[Type] composite: \xmlel{cs:Query}
527 \item[Meaning]
528 A query that will result in at least on
529 matched record that can be used to test the
530 service.
531
532 \item[Occurrence] optional
533
534 \end{description}
535
536
537 \end{bigdescription}\endgroup
538
539 \endgroup
540 \end{generated}
541
542 % /GENERATED
543
544 The custom metadata that the \xmlel{cs:ConeSearch} type provides is given
545 above. For the elements whose semantics map directly to
546 service profile metadata called for in the SCS standard,
547 section 3, there is an entry labeled ``SCS Name''; this indicates the
548 metadata name given in the SCS specification that the element in this
549 schema corresponds to. The profile metadata listed in the SCS
550 specification that is not covered by the elements below are covered by
551 other metadata that are part of the core VOResource schema.
552
553 \subsubsection{testQuery and the Query Type}
554
555 The \xmlel{testQuery} element is intended to help other VO components (e.g.
556 registries, validation services, services that monitor the VO's
557 operational health, but typically not end users) test that the service
558 is up and operating correctly. It provides a set of legal input
559 parameters that should return a legal response that includes at least
560 one matched record. Since this query is intended for testing purposes,
561 the size of the result set should be small.
562
563 The \xmlel{cs:Query} type captures the different components of the query into
564 separate elements, as defined below:
565
566 % GENERATED: !schemadoc ConeSearch-v1.1.xsd Query
567 \begin{generated}
568 \begingroup
569 \renewcommand*\descriptionlabel[1]{%
570 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{cs:Query} Type Schema Documentation}
571
572 \noindent{\small
573 A query to be sent to the service
574 \par}
575
576 \vspace{1ex}\noindent\textbf{\xmlel{cs:Query} Type Schema Definition}
577
578 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
579 <xs:complexType name="Query" >
580 <xs:sequence >
581 <xs:element name="ra" type="xs:double" />
582 <xs:element name="dec" type="xs:double" />
583 <xs:element name="sr" type="xs:double" />
584 <xs:element name="verb" type="xs:positiveInteger" minOccurs="0" />
585 <xs:element name="catalog" type="xs:string" minOccurs="0" />
586 <xs:element name="extras" type="xs:string" minOccurs="0" />
587 </xs:sequence>
588 </xs:complexType>
589 \end{lstlisting}
590
591 \vspace{0.5ex}\noindent\textbf{\xmlel{cs:Query} Metadata Elements}
592
593 \begingroup\small\begin{bigdescription}\item[Element \xmlel{ra}]
594 \begin{description}
595 \item[Type] floating-point number: \xmlel{xs:double}
596 \item[Meaning]
597 the right ascension of the search cone's center in
598 decimal degrees.
599
600 \item[Occurrence] required
601
602 \end{description}
603 \item[Element \xmlel{dec}]
604 \begin{description}
605 \item[Type] floating-point number: \xmlel{xs:double}
606 \item[Meaning]
607 the declination of the search cone's center in
608 decimal degrees.
609
610 \item[Occurrence] required
611
612 \end{description}
613 \item[Element \xmlel{sr}]
614 \begin{description}
615 \item[Type] floating-point number: \xmlel{xs:double}
616 \item[Meaning]
617 the radius of the search cone in decimal degrees.
618
619 \item[Occurrence] required
620
621 \end{description}
622 \item[Element \xmlel{verb}]
623 \begin{description}
624 \item[Type] \xmlel{xs:positiveInteger}
625 \item[Meaning]
626 the verbosity level to use where 1 means the bare
627 minimum set of columns and 3 means the full set of
628 available columns.
629
630 \item[Occurrence] optional
631
632 \end{description}
633 \item[Element \xmlel{catalog}]
634 \begin{description}
635 \item[Type] string: \xmlel{xs:string}
636 \item[Meaning]
637 the catalog to query.
638
639 \item[Occurrence] optional
640 \item[Comment]
641 When the service can access more than one catalog,
642 this input parameter, if available, is used to
643 indicate which service to access.
644
645
646 \end{description}
647 \item[Element \xmlel{extras}]
648 \begin{description}
649 \item[Type] string: \xmlel{xs:string}
650 \item[Meaning]
651 any extra (non-standard) parameters that must be
652 provided (apart from what is part of base URL given
653 by the accessURL element).
654
655 \item[Occurrence] optional
656 \item[Comment]
657 this value should be in the form of name=value
658 pairs delimited with ampersands (\&).
659
660
661 \end{description}
662
663
664 \end{bigdescription}\endgroup
665
666 \endgroup
667 \end{generated}
668
669 % /GENERATED
670
671 \subsection{Simple Image Access}
672
673 This section describes the SIA VOResource metadata extension schema
674 which is used to describe services that comply with versions of the
675 Simple Image Access protocol for which the specifications do not give
676 extensions themselves. This applies at least to versions 1.0
677 \citep{2009ivoa.spec.1111H} and 2.0 \citep{2015ivoa.spec.1223D}..
678
679 \subsubsection{The Standard Identifier}
680
681 The \xmlel{standardID} value for the Simple Image Access protocol
682 version 1.0 is
683 $$\hbox{\nolinkurl{ivo://ivoa.net/std/SIA} .}$$ Standard
684 identifiers for later versions are given in the respective
685 standards; for instance, SIA version 2.0 \citep{2015ivoa.spec.1223D},
686 specifies
687 $$\hbox{\nolinkurl{ivo://ivoa.net/std/SIA#query-2.0}}$$ for its query
688 capability.
689
690 \subsubsection{The Schema Namespace}
691
692 The namespace associated with the SIA extension schema is
693 $$\hbox{\nolinkurl{http://www.ivoa.net/xml/SIA/v1.1} ,}$$ the canonical
694 namespace prefix is \xmlel{sia:}
695
696 \subsubsection{SimpleImageAccess}
697
698 The \xmlel{sia:SimpleImageAccess} type is a \xmlel{vr:Capability} sub-type that should
699 be used to describe a service's support for the Simple Image Access
700 protocol; it is defined as follows:
701
702 % GENERATED: !schemadoc SIA-v1.2.xsd SimpleImageAccess
703 \begin{generated}
704 \begingroup
705 \renewcommand*\descriptionlabel[1]{%
706 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{sia:SimpleImageAccess} Type Schema Documentation}
707
708 \noindent{\small
709 The capabilities of an SIA implementation.
710 \par}
711
712 \vspace{1ex}\noindent\textbf{\xmlel{sia:SimpleImageAccess} Type Schema Definition}
713
714 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
715 <xs:complexType name="SimpleImageAccess" >
716 <xs:complexContent >
717 <xs:extension base="vr:Capability" >
718 <xs:sequence >
719 <xs:element name="imageServiceType"
720 type="sia:ImageServiceType" />
721 <xs:element name="maxQueryRegionSize" type="sia:SkySize"
722 minOccurs="0"
723 maxOccurs="1" />
724 <xs:element name="maxImageExtent" type="sia:SkySize" minOccurs="0"
725 maxOccurs="1" />
726 <xs:element name="maxImageSize" type="xs:positiveInteger"
727 minOccurs="0"
728 maxOccurs="1" />
729 <xs:element name="maxFileSize" type="xs:positiveInteger"
730 minOccurs="0"
731 maxOccurs="1" />
732 <xs:element name="maxRecords" type="xs:positiveInteger" minOccurs="0"
733 maxOccurs="1" />
734 <xs:element name="testQuery" type="sia:Query" minOccurs="0"
735 maxOccurs="1" />
736 </xs:sequence>
737 </xs:extension>
738 </xs:complexContent>
739 </xs:complexType>
740 \end{lstlisting}
741
742 \vspace{0.5ex}\noindent\textbf{\xmlel{sia:SimpleImageAccess} Extension Metadata Elements}
743
744 \begingroup\small\begin{bigdescription}\item[Element \xmlel{imageServiceType}]
745 \begin{description}
746 \item[Type] string with controlled vocabulary
747 \item[Meaning]
748 The class of image service: Cutout, Mosaic, Atlas, Pointed
749
750 \item[Occurrence] required
751
752 \item[Terms]\hfil
753 \begin{longtermsdescription}
754 \item[Cutout]
755 This is a service which extracts or “cuts out” rectangular
756 regions of some larger image, returning an image of the
757 requested size to the client. Such images are usually drawn
758 from a database or a collection of survey images that cover
759 some large portion of the sky. To be considered a cutout
760 service, the returned image should closely approximate (or at
761 least not exceed) the size of the requested region; however,
762 a cutout service will not normally resample (rescale or
763 reproject) the pixel data. A cutout service may mosaic image
764 segments to cover a large region but is still considered a
765 cutout service if it does not resample the data. Image
766 cutout services are fast and avoid image degredation due to
767 resampling.
768
769 \item[Mosaic]
770 This service is similar to the image cutout service
771 but adds the capability to compute an image of the
772 size, scale, and projection specified by the
773 client. Mosaic services include services which
774 resample and reproject existing image data, as well
775 as services which generate pixels from some more
776 fundamental dataset, e.g., a high energy event list
777 or a radio astronomy measurement set. Image mosaics
778 can be expensive to generate for large regions but
779 they make it easier for the client to overlay image
780 data from different sources. Image mosaicing
781 services which resample already pixelated data will
782 degrade the data slightly, unlike the simpler cutout
783 service which returns the data unchanged.
784
785 \item[Atlas]
786 This category of service provides access to
787 pre-computed images that make up a survey of some
788 large portion of the sky. The service, however, is
789 not capable of dynamically cutting out requested
790 regions, and the size of atlas images is
791 predetermined by the survey. Atlas images may range
792 in size from small cutouts of extended objects to
793 large calibrated survey data frames.
794
795 \item[Pointed]
796 This category of service provides access to
797 collections of images of many small, “pointed”
798 regions of the sky. “Pointed” images normally focus
799 on specific sources in the sky as opposed to being
800 part of a sky survey. This type of service usually
801 applies to instrumental archives from observatories
802 with guest observer programs (e.g., the HST archive)
803 and other general purpose image archives (e.g., the
804 ADIL). If a service provides access to both survey
805 and pointed images, then it should be considered a
806 Pointed Image Archive for the purposes of this
807 specification; if a differentiation between the
808 types of data is desired the pointed and survey data
809 collections should be registered as separate image
810 services.
811
812 \end{longtermsdescription}
813
814 \end{description}
815 \item[Element \xmlel{maxQueryRegionSize}]
816 \begin{description}
817 \item[Type] composite: \xmlel{sia:SkySize}
818 \item[Meaning]
819 The maximum image query region size, expressed in
820 decimal degrees. Not providing this element or
821 specifying a value of 360 degrees indicates that
822 there is no limit and the entire data collection
823 (entire sky) can be queried.
824
825 \item[Occurrence] optional
826 \item[Comment]
827 Not providing a value is the prefered way to indicate
828 that there is no limit.
829
830
831 \end{description}
832 \item[Element \xmlel{maxImageExtent}]
833 \begin{description}
834 \item[Type] composite: \xmlel{sia:SkySize}
835 \item[Meaning]
836 An upper bound on a region of the sky that can
837 be covered by returned images. That is, no image
838 returned by this service will cover more than
839 this limit. Not providing this element or
840 specifying a value of 360 degrees indicates that
841 there is no fundamental limit to the region covered
842 by a returned image.
843
844 \item[Occurrence] optional
845 \item[Comment]
846 When the imageServiceType is “Cutout” or “Mosaic”,
847 this represents the largest area that can be requested.
848 In this case, the “no limit” value means that all-sky
849 images can be requested. When the type is “Atlas” or
850 “Pointed”, it should be a region that most closely
851 encloses largest images in the archive, and the ”no
852 limit” value means that the archive contains all-sky
853 (or nearly so) images.
854
855 \item[Comment]
856 Not providing a value is the prefered way to indicate
857 that there is no limit.
858
859
860 \end{description}
861 \item[Element \xmlel{maxImageSize}]
862 \begin{description}
863 \item[Type] \xmlel{xs:positiveInteger}
864 \item[Meaning]
865 A measure of the largest image the service
866 can produce given as the maximum number of
867 pixels along the first or second axes.
868 Not providing a value indicates that there is
869 no effective limit to the size of the images
870 that can be returned.
871
872 \item[Occurrence] optional
873 \item[Comment]
874 This is primarily relevant when the imageServiceType
875 is “Cutout” or “Mosaic”, indicating the largest
876 image that can be created. When the imageServiceType
877 is “Atlas” or “Pointed”, this should be specified only
878 when there are static images in the archive that can
879 be searched for but not returned because they are
880 too big.
881
882 \item[Comment]
883 When a service is more fundementally limited
884 by the total number of pixels in the image, this
885 value should be set to the square-root of that
886 number. This number will then represent a
887 lower limit on the maximum length of a side.
888
889
890 \end{description}
891 \item[Element \xmlel{maxFileSize}]
892 \begin{description}
893 \item[Type] \xmlel{xs:positiveInteger}
894 \item[Meaning]
895 The maximum image file size in bytes. Not providing
896 a value indicates that there is no effective limit
897 the size of files that can be returned.
898
899 \item[Occurrence] optional
900 \item[Comment]
901 This is primarily relevant when the imageServiceType
902 is “Cutout” or “Mosaic”, indicating the largest
903 files that can be created. When the imageServiceType
904 is “Atlas” or “Pointed”, this should be specified only
905 when there are static images in the archive that can
906 be searched for but not returned because they are
907 too big.
908
909
910 \end{description}
911 \item[Element \xmlel{maxRecords}]
912 \begin{description}
913 \item[Type] \xmlel{xs:positiveInteger}
914 \item[Meaning]
915 The largest number of records that the Image Query web
916 method will return. Not providing this value means that
917 there is no effective limit.
918
919 \item[Occurrence] optional
920 \item[Comment]
921 This does not refer to the total number of images in
922 the archive but rather maximum number of records the
923 service is capable of returning. A limit that is
924 greater than the number of images available in the
925 archive is equivalent to their being no effective
926 limit. (See RM, Hanisch 2007.)
927
928
929 \end{description}
930 \item[Element \xmlel{testQuery}]
931 \begin{description}
932 \item[Type] composite: \xmlel{sia:Query}
933 \item[Meaning]
934 a set of query parameters that is expected
935 to produce at least one matched record which
936 can be used to test the service.
937
938 \item[Occurrence] optional
939
940 \end{description}
941
942
943 \end{bigdescription}\endgroup
944
945 \endgroup
946 \end{generated}
947
948 % /GENERATED
949
950
951 \subsubsection{SkySize}
952
953 The \xmlel{sia:SkySize} type is used to capture simple rectangular extents on
954 the sky along longitudinal and latitudinal directions. It is defined as
955 follows:
956
957 % GENERATED: !schemadoc SIA-v1.2.xsd SkySize
958 \begin{generated}
959 \begingroup
960 \renewcommand*\descriptionlabel[1]{%
961 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{sia:SkySize} Type Schema Definition}
962
963 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
964 <xs:complexType name="SkySize" >
965 <xs:sequence >
966 <xs:element name="long" type="xs:double" />
967 <xs:element name="lat" type="xs:double" />
968 </xs:sequence>
969 </xs:complexType>
970 \end{lstlisting}
971
972 \vspace{0.5ex}\noindent\textbf{\xmlel{sia:SkySize} Metadata Elements}
973
974 \begingroup\small\begin{bigdescription}\item[Element \xmlel{long}]
975 \begin{description}
976 \item[Type] floating-point number: \xmlel{xs:double}
977 \item[Meaning]
978 The maximum size in the longitude (R.A.) direction
979 given in degrees
980
981 \item[Occurrence] required
982
983 \end{description}
984 \item[Element \xmlel{lat}]
985 \begin{description}
986 \item[Type] floating-point number: \xmlel{xs:double}
987 \item[Meaning]
988 The maximum size in the latitude (Dec.) direction
989 given in degrees
990
991 \item[Occurrence] required
992
993 \end{description}
994
995
996 \end{bigdescription}\endgroup
997
998 \endgroup
999 \end{generated}
1000
1001 % /GENERATED
1002
1003 \subsubsection{testQuery and the Query Type}
1004
1005 As with the other DAL \xmlel{vr:capability} types, the \xmlel{testQuery}
1006 element is intended to help other VO components (e.g. registries,
1007 validation services, services that monitor the VO's operational
1008 health--but typically not end users) test that the service is up and
1009 operating correctly. It provides a region of interest (plus optionally
1010 additional parameters) to be used to get a non-empty result from the
1011 service. For SIAv2, this region of interest would usually be translated
1012 into a RANGE query.
1013 Since this query is intended for testing purposes, the size of the
1014 result set should be small.
1015
1016 The \xmlel{sia:Query} type captures the different components of the
1017 query into separate elements, as defined below:
1018
1019 % GENERATED: !schemadoc SIA-v1.2.xsd Query
1020 \begin{generated}
1021 \begingroup
1022 \renewcommand*\descriptionlabel[1]{%
1023 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{sia:Query} Type Schema Documentation}
1024
1025 \noindent{\small
1026 A query to be sent to the service
1027 \par}
1028
1029 \vspace{1ex}\noindent\textbf{\xmlel{sia:Query} Type Schema Definition}
1030
1031 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1032 <xs:complexType name="Query" >
1033 <xs:sequence >
1034 <xs:element name="pos" type="sia:SkyPos" minOccurs="0" />
1035 <xs:element name="size" type="sia:SkySize" minOccurs="0" />
1036 <xs:element name="verb" type="xs:positiveInteger" minOccurs="0" />
1037 <xs:element name="extras" type="xs:string" minOccurs="0" />
1038 </xs:sequence>
1039 </xs:complexType>
1040 \end{lstlisting}
1041
1042 \vspace{0.5ex}\noindent\textbf{\xmlel{sia:Query} Metadata Elements}
1043
1044 \begingroup\small\begin{bigdescription}\item[Element \xmlel{pos}]
1045 \begin{description}
1046 \item[Type] composite: \xmlel{sia:SkyPos}
1047 \item[Meaning]
1048 the center position of the rectangular region that
1049 should be used as part of the query to the SIA service.
1050
1051 \item[Occurrence] optional
1052
1053 \end{description}
1054 \item[Element \xmlel{size}]
1055 \begin{description}
1056 \item[Type] composite: \xmlel{sia:SkySize}
1057 \item[Meaning]
1058 the rectangular size of the region that should be
1059 used as part of the query to the SIA service.
1060
1061 \item[Occurrence] optional
1062
1063 \end{description}
1064 \item[Element \xmlel{verb}]
1065 \begin{description}
1066 \item[Type] \xmlel{xs:positiveInteger}
1067 \item[Meaning]
1068 the verbosity level to use where 0 means the bare
1069 minimum set of columns and 3 means the full set of
1070 available columns.
1071
1072 \item[Occurrence] optional
1073
1074 \end{description}
1075 \item[Element \xmlel{extras}]
1076 \begin{description}
1077 \item[Type] string: \xmlel{xs:string}
1078 \item[Meaning]
1079 any extra (particularly non-standard) parameters that must
1080 be provided (apart from what is part of base URL given by
1081 the accessURL element).
1082
1083 \item[Occurrence] optional
1084 \item[Comment]
1085 this value should be in the form of name=value
1086 pairs delimited with ampersands (\&).
1087
1088
1089 \end{description}
1090
1091
1092 \end{bigdescription}\endgroup
1093
1094 \endgroup
1095 \end{generated}
1096
1097 % /GENERATED
1098
1099 \subsubsection{SkyPos}
1100
1101 The \xmlel{sia:SkyPos} type is used to encode the \xmlel{testQuery}'s
1102 \xmlel{pos} element, the center position of the test region of interest.
1103
1104 % GENERATED: !schemadoc SIA-v1.2.xsd SkyPos
1105 \begin{generated}
1106 \begingroup
1107 \renewcommand*\descriptionlabel[1]{%
1108 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{sia:SkyPos} Type Schema Definition}
1109
1110 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1111 <xs:complexType name="SkyPos" >
1112 <xs:sequence >
1113 <xs:element name="long" type="xs:double" />
1114 <xs:element name="lat" type="xs:double" />
1115 </xs:sequence>
1116 </xs:complexType>
1117 \end{lstlisting}
1118
1119 \vspace{0.5ex}\noindent\textbf{\xmlel{sia:SkyPos} Metadata Elements}
1120
1121 \begingroup\small\begin{bigdescription}\item[Element \xmlel{long}]
1122 \begin{description}
1123 \item[Type] floating-point number: \xmlel{xs:double}
1124 \item[Meaning]
1125 The sky position in the longitude (R.A.) direction
1126
1127 \item[Occurrence] required
1128
1129 \end{description}
1130 \item[Element \xmlel{lat}]
1131 \begin{description}
1132 \item[Type] floating-point number: \xmlel{xs:double}
1133 \item[Meaning]
1134 The sky position in the latitude (Dec.) direction
1135
1136 \item[Occurrence] required
1137
1138 \end{description}
1139
1140
1141 \end{bigdescription}\endgroup
1142
1143 \endgroup
1144 \end{generated}
1145
1146 % /GENERATED
1147
1148
1149 \subsection{Simple Spectral Access}
1150
1151 This section describes the SSA VOResource metadata extension schema
1152 which is used to describe services that comply with the Simple Spectral
1153 Access protocol, which primarily defines the
1154 \xmlel{ssap:SimpleSpectralAccess}
1155 \xmlel{vr:Capability} type to be used by services
1156 compliant with published SSA Recommendation
1157 \citep{2012ivoa.spec.0210T}.
1158
1159 \subsubsection{The Standard Identifier}
1160
1161 The \xmlel{standardID} value for Simple Spectral access version 1.1 (and
1162 before) is
1163 $$\hbox{\nolinkurl{ivo://ivoa.net/std/SSA} .}$$ Standard
1164 identifiers for later versions will be given in the respective
1165 standards.
1166
1167
1168 \subsubsection{The Schema Namespace}
1169
1170 The namespace associated with the SSA extension schema is
1171 \nolinkurl{http://www.ivoa.net/xml/SSA/v1.1}. The namespace prefix,
1172 \xmlel{ssap:} should be used in applications where common use of
1173 prefixes improves interoperability (e.g. in the IVOA registries).
1174 Furthermore, we use the \xmlel{ssap:} prefix in this document to refer
1175 to types defined as part of the SSA extension schema.
1176
1177 \begin{admonition}{Note}
1178 Though it departs a bit from convention, the ssap prefix was
1179 chosen to avoid a collision with its use in SSA for
1180 identifying UTypes from the Spectral Data Model.
1181 \end{admonition}
1182
1183 \subsubsection{SimpleSpectralAccess}
1184
1185 The \xmlel{ssap:SimpleSpectralAccess} type is the \xmlel{vr:Capability}
1186 sub-type that should be used to describe a service's support for the
1187 Simple Spectral Access protocol; it is defined as follows:
1188
1189 % GENERATED: !schemadoc SSA-v1.3.xsd SimpleSpectralAccess
1190 \begin{generated}
1191 \begingroup
1192 \renewcommand*\descriptionlabel[1]{%
1193 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{ssap:SimpleSpectralAccess} Type Schema Documentation}
1194
1195 \noindent{\small
1196 The capabilities of an SSA service implementation.
1197 \par}
1198
1199 \vspace{1ex}\noindent\textbf{\xmlel{ssap:SimpleSpectralAccess} Type Schema Definition}
1200
1201 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1202 <xs:complexType name="SimpleSpectralAccess" >
1203 <xs:complexContent >
1204 <xs:extension base="vr:Capability" >
1205 <xs:sequence >
1206 <xs:element name="complianceLevel"
1207 type="ssap:ComplianceLevel" />
1208 <xs:element name="dataSource" type="ssap:DataSource" minOccurs="1"
1209 maxOccurs="unbounded" />
1210 <xs:element name="creationType" type="ssap:CreationType"
1211 minOccurs="1"
1212 maxOccurs="unbounded" />
1213 <xs:element name="supportedFrame" type="xs:token" minOccurs="1"
1214 maxOccurs="unbounded" />
1215 <xs:element name="maxSearchRadius" type="xs:double" minOccurs="0"
1216 maxOccurs="1" />
1217 <xs:element name="maxRecords" type="xs:positiveInteger" minOccurs="0"
1218 maxOccurs="1" />
1219 <xs:element name="defaultMaxRecords"
1220 type="xs:positiveInteger"
1221 minOccurs="0"
1222 maxOccurs="1" />
1223 <xs:element name="maxAperture" type="xs:double" minOccurs="0"
1224 maxOccurs="1" />
1225 <xs:element name="maxFileSize" type="xs:positiveInteger"
1226 minOccurs="0"
1227 maxOccurs="1" />
1228 <xs:element name="testQuery" type="ssap:Query" minOccurs="0"
1229 maxOccurs="1" />
1230 </xs:sequence>
1231 </xs:extension>
1232 </xs:complexContent>
1233 </xs:complexType>
1234 \end{lstlisting}
1235
1236 \vspace{0.5ex}\noindent\textbf{\xmlel{ssap:SimpleSpectralAccess} Extension Metadata Elements}
1237
1238 \begingroup\small\begin{bigdescription}\item[Element \xmlel{complianceLevel}]
1239 \begin{description}
1240 \item[Type] string with controlled vocabulary
1241 \item[Meaning]
1242 The category indicating the level to which
1243 this instance complies with the SSA standard.
1244
1245 \item[Occurrence] required
1246
1247 \item[Terms]\hfil
1248 \begin{longtermsdescription}
1249 \item[query]
1250 The service supports all of the capabilities and features
1251 of the SSA protocol identified as {"}must{"} in the
1252 specification, except that it does not support returning
1253 data in at least one SSA-compliant format.
1254
1255 \item[minimal]
1256 The service supports all of the capabilities and features
1257 of the SSA protocol identified as {"}must{"} in the
1258 specification.
1259
1260 \item[full]
1261 The service supports all of the capabilities and features
1262 of the SSA protocol identified as {"}must{"} or {"}should{"} in the
1263 specification.
1264
1265 \end{longtermsdescription}
1266 \item[Comment]
1267 Allowed values are {"}query{"}, {"}minimal{"}, and {"}full{"}.
1268 See definitions of allowed values for details.
1269
1270
1271 \end{description}
1272 \item[Element \xmlel{dataSource}]
1273 \begin{description}
1274 \item[Type] string with controlled vocabulary
1275 \item[Meaning]
1276 The category specifying where the data originally
1277 came from.
1278
1279 \item[Occurrence] required; multiple occurrences allowed.
1280
1281 \item[Terms]\hfil
1282 \begin{longtermsdescription}
1283 \item[survey]
1284 A survey dataset, which typically covers some region of
1285 observational parameter space in a uniform fashion, with
1286 as complete as possible coverage in the region of parameter
1287 space observed.
1288
1289 \item[pointed]
1290 A pointed observation of a particular astronomical object
1291 or field.
1292
1293 \item[custom]
1294 Data which has been custom processed, e.g., as part of
1295 a specific research project.
1296
1297 \item[theory]
1298 Theory data, or any data generated from a theoretical
1299 model, for example a synthetic spectrum.
1300
1301 \item[artificial]
1302 Artificial or simulated data.
1303
1304 \end{longtermsdescription}
1305 \item[Comment]
1306 Allowed values are {"}survey{"}, {"}pointed{"}, {"}custom{"},
1307 {"}theory{"}, {"}artificial{"}
1308
1309
1310 \end{description}
1311 \item[Element \xmlel{creationType}]
1312 \begin{description}
1313 \item[Type] string with controlled vocabulary
1314 \item[Meaning]
1315 The category that describes the process used to
1316 produce the dataset.
1317
1318 \item[Occurrence] required; multiple occurrences allowed.
1319
1320 \item[Terms]\hfil
1321 \begin{longtermsdescription}
1322 \item[archival]
1323 The entire archival or project dataset is returned.
1324 Transformations such as metadata or data model mediation
1325 or format conversions may take place, but the content of
1326 the dataset is not substantially modified (e.g., all the
1327 data is returned and the sample values are not modified).
1328
1329 \item[cutout]
1330 The dataset is subsetted in some region of parameter
1331 space to produce a subset dataset. Sample values are not
1332 modified, e.g., cutouts could be recombined to reconstitute
1333 the original dataset.
1334
1335 \item[filtered]
1336 The data is filtered in some fashion to exclude portions
1337 of the dataset, e.g., passing only data in selected regions
1338 along a measurement axis, or processing the data in a way
1339 which recomputes the sample values, e.g., due to
1340 interpolation or flux transformation.
1341
1342 \item[mosaic]
1343 Data from multiple non- or partially-overlapping datasets
1344 are combined to produce a new dataset.
1345
1346 \item[projection]
1347 Data is geometrically warped or dimensionally reduced by
1348 projecting through a multidimensional dataset.
1349
1350 \item[spectralExtraction]
1351 Extraction of a spectrum from another dataset, e.g.,
1352 extraction of a spectrum from a spectral data cube
1353 through a simulated aperture.
1354
1355 \item[catalogExtraction]
1356 Extraction of a catalog of some form from another dataset,
1357 e.g., extraction of a source catalog from an image, or
1358 extraction of a line list catalog from a spectrum (not
1359 valid for a SSA service).
1360
1361 \end{longtermsdescription}
1362 \item[Comment]
1363 Typically this describes only the processing
1364 performed by the data service, but it could
1365 describe some additional earlier processing as
1366 well, e.g., if data is partially precomputed.
1367
1368 \item[Comment]
1369 Allowed values are {"}archival{"}, {"}cutout{"}, {"}filtered{"},
1370 {"}mosaic{"}, {"}projection{"}, {"}spectralExtraction{"},
1371 {"}catalogExtraction{"}
1372
1373
1374 \end{description}
1375 \item[Element \xmlel{supportedFrame}]
1376 \begin{description}
1377 \item[Type] string: \xmlel{xs:token}
1378 \item[Meaning]
1379 Identifiers of spatial reference frames that can be used
1380 in the POS parameter. The identifiers must be taken
1381 from the vocabulary http://www.ivoa.net/rdf/refframe.
1382
1383 \item[Occurrence] required; multiple occurrences allowed.
1384 \item[Comment]
1385 At least one recognized value must be listed
1386 when the service supports POS.
1387 With SSA v1.1, ICRS must be supported in that
1388 case; thus,
1389 this list must include at least this value.
1390
1391
1392 \end{description}
1393 \item[Element \xmlel{maxSearchRadius}]
1394 \begin{description}
1395 \item[Type] floating-point number: \xmlel{xs:double}
1396 \item[Meaning]
1397 The largest search radius, in degrees, that will be
1398 accepted by the service without returning an error
1399 condition. Not providing this element or
1400 specifying a value of 180 indicates that there
1401 is no restriction.
1402
1403 \item[Occurrence] optional
1404 \item[Comment]
1405 Not providing a value is the prefered way to indicate
1406 that there is no restriction.
1407
1408
1409 \end{description}
1410 \item[Element \xmlel{maxRecords}]
1411 \begin{description}
1412 \item[Type] \xmlel{xs:positiveInteger}
1413 \item[Meaning]
1414 The hard limit on the largest number of records that
1415 the query operation will return in a single response.
1416 Not providing this value means that there is no
1417 effective limit.
1418
1419 \item[Occurrence] optional
1420 \item[Comment]
1421 This does not refer to the total number of spectra in
1422 the archive but rather maximum number of records the
1423 service is capable of returning. A limit that is
1424 greater than the number of spectra available in the
1425 archive is equivalent to their being no effective
1426 limit. (See RM, Hanisch 2007.)
1427
1428
1429 \end{description}
1430 \item[Element \xmlel{defaultMaxRecords}]
1431 \begin{description}
1432 \item[Type] \xmlel{xs:positiveInteger}
1433 \item[Meaning]
1434 The largest number of records that the service will
1435 return when the MAXREC parameter not specified
1436 in the query input. Not providing a value means
1437 that the hard limit implied by maxRecords will be
1438 the default limit.
1439
1440 \item[Occurrence] optional
1441
1442 \end{description}
1443 \item[Element \xmlel{maxAperture}]
1444 \begin{description}
1445 \item[Type] floating-point number: \xmlel{xs:double}
1446 \item[Meaning]
1447 The largest aperture that can be supported upon
1448 request via the APERTURE input parameter by a
1449 service that supports the spectral extraction
1450 creation method. A value of 180 or not providing
1451 a value means there is no theoretical limit.
1452
1453 \item[Occurrence] optional
1454 \item[Comment]
1455 Not providing a value is the preferred way to
1456 indicate that there is no limit.
1457
1458
1459 \end{description}
1460 \item[Element \xmlel{maxFileSize}]
1461 \begin{description}
1462 \item[Type] \xmlel{xs:positiveInteger}
1463 \item[Meaning]
1464 The maximum spectrum file size in bytes that will
1465 be returned. Not providing
1466 a value indicates that there is no effective limit
1467 the size of files that can be returned.
1468
1469 \item[Occurrence] optional
1470 \item[Comment]
1471 This is primarily relevant when spectra are created
1472 on the fly (see creationType). If the service
1473 provides access to static spectra, this should only
1474 be specified if there are spectra in the archive that
1475 can be searched for but not returned because they are
1476 too big.
1477
1478
1479 \end{description}
1480 \item[Element \xmlel{testQuery}]
1481 \begin{description}
1482 \item[Type] composite: \xmlel{ssap:Query}
1483 \item[Meaning]
1484 a set of query parameters that is expected to
1485 produce at least one matched record which can be
1486 used to test the service.
1487
1488 \item[Occurrence] optional
1489
1490 \end{description}
1491
1492
1493 \end{bigdescription}\endgroup
1494
1495 \endgroup
1496 \end{generated}
1497
1498 % /GENERATED
1499
1500 The custom metadata that the \xmlel{ssap:SimpleSpectralAccess} type provides is
1501 given above. Note that some of these elements derive from
1502 the SSA standard; others, from the RM standard \citep{2007ivoa.spec.0302H}.
1503 The ``Semantic Meaning'' entry provides the reference to the original
1504 definition.
1505
1506
1507 \subsubsection{testQuery and the Query Type}
1508
1509 As with the other DAL \xmlel{vr:capability} types, the \xmlel{testQuery} element is
1510 intended to help other VO components (e.g. registries, validation
1511 services, services that monitor the VO's operational health -- but
1512 typically not end users) test that the service is up and operating
1513 correctly. It provides a set of legal input parameters that should
1514 return a legal response that includes at least matched record. Since
1515 this query is intended for testing purposes, the size of the result set
1516 should be small.
1517
1518 The \xmlel{ssap:Query} type captures the different components of the
1519 query into separate elements, as defined below:
1520
1521 % GENERATED: !schemadoc SSA-v1.3.xsd Query
1522 \begin{generated}
1523 \begingroup
1524 \renewcommand*\descriptionlabel[1]{%
1525 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{ssap:Query} Type Schema Documentation}
1526
1527 \noindent{\small
1528 A query to be sent to the service
1529 \par}
1530
1531 \vspace{1ex}\noindent\textbf{\xmlel{ssap:Query} Type Schema Definition}
1532
1533 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1534 <xs:complexType name="Query" >
1535 <xs:sequence >
1536 <xs:element name="pos" type="ssap:PosParam" minOccurs="0" />
1537 <xs:element name="size" type="xs:double" minOccurs="0" />
1538 <xs:element name="queryDataCmd" type="xs:string" minOccurs="0" />
1539 </xs:sequence>
1540 </xs:complexType>
1541 \end{lstlisting}
1542
1543 \vspace{0.5ex}\noindent\textbf{\xmlel{ssap:Query} Metadata Elements}
1544
1545 \begingroup\small\begin{bigdescription}\item[Element \xmlel{pos}]
1546 \begin{description}
1547 \item[Type] composite: \xmlel{ssap:PosParam}
1548 \item[Meaning]
1549 the center position the search cone given in
1550 decimal degrees.
1551
1552 \item[Occurrence] optional
1553
1554 \end{description}
1555 \item[Element \xmlel{size}]
1556 \begin{description}
1557 \item[Type] floating-point number: \xmlel{xs:double}
1558 \item[Meaning]
1559 the size of the search radius.
1560
1561 \item[Occurrence] optional
1562
1563 \end{description}
1564 \item[Element \xmlel{queryDataCmd}]
1565 \begin{description}
1566 \item[Type] string: \xmlel{xs:string}
1567 \item[Meaning]
1568 Fully specified test query formatted as an URL
1569 argument list in the syntax specified by the SSA standard.
1570 The list must exclude the REQUEST argument which is
1571 assumed to be set to {"}queryData{"}.
1572
1573 \item[Occurrence] optional
1574 \item[Comment]
1575 This value must be in the form of name=value
1576 pairs delimited with ampersands (\&). A query
1577 may then be formed by appending to the base URL the
1578 request argument, {"}REQUEST=queryData\&{"}, followed
1579 by the contents of this element.
1580
1581
1582 \end{description}
1583
1584
1585 \end{bigdescription}\endgroup
1586
1587 \endgroup
1588 \end{generated}
1589
1590 % /GENERATED
1591
1592
1593 \subsubsection{PosParam}
1594
1595 The \xmlel{ssap:PosParam} type is used to encode the \xmlel{testQuery}'s
1596 \xmlel{pos} element, the center position of the test region of interest;
1597 it is defined as follows:
1598
1599 % GENERATED: !schemadoc SSA-v1.3.xsd PosParam
1600 \begin{generated}
1601 \begingroup
1602 \renewcommand*\descriptionlabel[1]{%
1603 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{ssap:PosParam} Type Schema Documentation}
1604
1605 \noindent{\small
1606 a position in the sky to search.
1607 \par}
1608
1609 \vspace{1ex}\noindent\textbf{\xmlel{ssap:PosParam} Type Schema Definition}
1610
1611 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1612 <xs:complexType name="PosParam" >
1613 <xs:sequence >
1614 <xs:element name="long" type="xs:double" />
1615 <xs:element name="lat" type="xs:double" />
1616 <xs:element name="refframe" type="xs:token" minOccurs="0" />
1617 </xs:sequence>
1618 </xs:complexType>
1619 \end{lstlisting}
1620
1621 \vspace{0.5ex}\noindent\textbf{\xmlel{ssap:PosParam} Metadata Elements}
1622
1623 \begingroup\small\begin{bigdescription}\item[Element \xmlel{long}]
1624 \begin{description}
1625 \item[Type] floating-point number: \xmlel{xs:double}
1626 \item[Meaning]
1627 The longitude (e.g. Right Ascension) of the center of the
1628 search position in decimal degrees.
1629
1630 \item[Occurrence] required
1631
1632 \end{description}
1633 \item[Element \xmlel{lat}]
1634 \begin{description}
1635 \item[Type] floating-point number: \xmlel{xs:double}
1636 \item[Meaning]
1637 The latitude (e.g. Declination) of the center of the
1638 search position in decimal degrees.
1639
1640 \item[Occurrence] required
1641
1642 \end{description}
1643 \item[Element \xmlel{refframe}]
1644 \begin{description}
1645 \item[Type] string: \xmlel{xs:token}
1646 \item[Meaning]
1647 the coordinate system reference frame name indicating
1648 the frame to assume for the given position. If not
1649 provided, ICRS is assumed.
1650
1651 \item[Occurrence] optional
1652
1653 \end{description}
1654
1655
1656 \end{bigdescription}\endgroup
1657
1658 \endgroup
1659 \end{generated}
1660
1661 % /GENERATED
1662
1663 \subsection{Simple Line Access}
1664
1665 This section describes the SLA VOResource metadata extension schema
1666 which is used to describe services that comply with the Simple Line
1667 Access protocol \citep{2010ivoa.specQ1209O}.
1668
1669 \subsubsection{The Standard Identifier}
1670
1671 The \xmlel{standardID} value for Simple Line Access version 1.0
1672 is
1673 $$\hbox{\nolinkurl{ivo://ivoa.net/std/SLAP} .}$$ Standard
1674 identifiers for later versions will be given in the respective
1675 standards.
1676
1677
1678 \subsubsection{The Schema Namespace}
1679
1680 The namespace associated with the SLA extension schema is
1681 \nolinkurl{http://www.ivoa.net/xml/SLAP/v1.0}. The namespace prefix,
1682 \xmlel{slap:}, should be used in applications where common use of
1683 prefixes improves interoperability (e.g. in the IVOA registries).
1684 Furthermore, we use the \xmlel{slap:} prefix in this document to refer
1685 to types defined as part of the SLA extension schema.
1686
1687 \subsubsection{SimpleLineAccess}
1688
1689 The \xmlel{slap:SimpleLineAccess} type is a \xmlel{vr:Capability}
1690 sub-type that should be used to describe a service's support for the
1691 Simple Line Access protocol; it is defined as follows:
1692
1693 % GENERATED: !schemadoc SLAP-v1.1.xsd SimpleLineAccess
1694 \begin{generated}
1695 \begingroup
1696 \renewcommand*\descriptionlabel[1]{%
1697 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{slap:SimpleLineAccess} Type Schema Documentation}
1698
1699 \noindent{\small
1700 The capabilities of an SLAP service implementation.
1701 \par}
1702
1703 \vspace{1ex}\noindent\textbf{\xmlel{slap:SimpleLineAccess} Type Schema Definition}
1704
1705 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1706 <xs:complexType name="SimpleLineAccess" >
1707 <xs:complexContent >
1708 <xs:extension base="vr:Capability" >
1709 <xs:sequence >
1710 <xs:element name="complianceLevel"
1711 type="slap:ComplianceLevel" />
1712 <xs:element name="dataSource" type="slap:DataSource" />
1713 <xs:element name="maxRecords" type="xs:positiveInteger" minOccurs="0"
1714 maxOccurs="1" />
1715 <xs:element name="testQuery" type="slap:Query" minOccurs="0"
1716 maxOccurs="1" />
1717 </xs:sequence>
1718 </xs:extension>
1719 </xs:complexContent>
1720 </xs:complexType>
1721 \end{lstlisting}
1722
1723 \vspace{0.5ex}\noindent\textbf{\xmlel{slap:SimpleLineAccess} Extension Metadata Elements}
1724
1725 \begingroup\small\begin{bigdescription}\item[Element \xmlel{complianceLevel}]
1726 \begin{description}
1727 \item[Type] string with controlled vocabulary
1728 \item[Meaning]
1729 The category indicating the level to which this
1730 service instance complies with the SLAP standard.
1731
1732 \item[Occurrence] required
1733
1734 \item[Terms]\hfil
1735 \begin{longtermsdescription}
1736 \item[minimal]
1737 The service supports all of the capabilities and features
1738 of the SLAP protocol identified as {"}must{"} in the
1739 specification.
1740
1741 \item[full]
1742 The service supports, at a minimum, all of the capabilities
1743 and features of the SLAP protocol identified as {"}must{"} or
1744 {"}should{"} in the specification.
1745
1746 \end{longtermsdescription}
1747 \item[Comment]
1748 Allowed values are {"}minimal{"} and {"}full{"}.
1749 See definitions of allowed values for details.
1750
1751
1752 \end{description}
1753 \item[Element \xmlel{dataSource}]
1754 \begin{description}
1755 \item[Type] string with controlled vocabulary
1756 \item[Meaning]
1757 The category specifying where the data accessed by
1758 the service originally came from.
1759
1760 \item[Occurrence] required
1761
1762 \item[Terms]\hfil
1763 \begin{longtermsdescription}
1764 \item[observational/astrophysical]
1765 Lines observed and identified in real spectra of
1766 astrophysical observations by different
1767 instrument/projects
1768
1769 \item[observational/laboratory]
1770 Lines observed and identified in real spectra of
1771 laboratory measurements
1772
1773 \item[theoretical]
1774 Servers containing theoretical spectral lines
1775
1776 \end{longtermsdescription}
1777 \item[Comment]
1778 Allowed values are {"}observational/astrophysical{"},
1779 {"}observational/laboratory{"}, {"}theoretical{"}
1780
1781
1782 \end{description}
1783 \item[Element \xmlel{maxRecords}]
1784 \begin{description}
1785 \item[Type] \xmlel{xs:positiveInteger}
1786 \item[Meaning]
1787 The hard limit on the largest number of records that
1788 the query operation will return in a single response.
1789 Not providing this value means that there is no
1790 effective limit.
1791
1792 \item[Occurrence] optional
1793 \item[Comment]
1794 This does not refer to the total number of spectra in
1795 the archive but rather maximum number of records the
1796 service is capable of returning. A limit that is
1797 greater than the number of spectra available in the
1798 archive is equivalent to their being no effective
1799 limit. (See RM, Hanisch 2007.)
1800
1801
1802 \end{description}
1803 \item[Element \xmlel{testQuery}]
1804 \begin{description}
1805 \item[Type] composite: \xmlel{slap:Query}
1806 \item[Meaning]
1807 A set of queryData parameters that is expected to
1808 produce at least one matched record which can be
1809 used to test the service.
1810
1811 \item[Occurrence] optional
1812 \item[Comment]
1813 The value should include all parameters required
1814 for the test query but should exclude the baseURL
1815 and the REQUEST parameter.
1816
1817
1818 \end{description}
1819
1820
1821 \end{bigdescription}\endgroup
1822
1823 \endgroup
1824 \end{generated}
1825
1826 % /GENERATED
1827
1828
1829 \subsubsection{testQuery and the Query Type}
1830
1831 As with the other DAL \xmlel{vr:capability} types, the \xmlel{testQuery} element is
1832 intended to help other VO components (e.g. registries, validation
1833 services, services that monitor the VO's operational health -- but
1834 typically not end users) test that the service is up and operating
1835 correctly. It provides a set of legal input parameters that should
1836 return a legal response that includes at least matched record. Since
1837 this query is intended for testing purposes, the size of the result set
1838 should be small.
1839
1840 The \xmlel{slap:Query} type captures the different components of the
1841 query into separate elements, as defined below:
1842
1843 % GENERATED: !schemadoc SLAP-v1.1.xsd Query
1844 \begin{generated}
1845 \begingroup
1846 \renewcommand*\descriptionlabel[1]{%
1847 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{slap:Query} Type Schema Documentation}
1848
1849 \noindent{\small
1850 A query to be sent to the service, e.g., a test query.
1851 \par}
1852
1853 \vspace{1ex}\noindent\textbf{\xmlel{slap:Query} Type Schema Definition}
1854
1855 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1856 <xs:complexType name="Query" >
1857 <xs:sequence >
1858 <xs:element name="wavelength"
1859 type="slap:WavelengthRange"
1860 minOccurs="0" />
1861 <xs:element name="queryDataCmd" type="xs:string" minOccurs="0" />
1862 </xs:sequence>
1863 </xs:complexType>
1864 \end{lstlisting}
1865
1866 \vspace{0.5ex}\noindent\textbf{\xmlel{slap:Query} Metadata Elements}
1867
1868 \begingroup\small\begin{bigdescription}\item[Element \xmlel{wavelength}]
1869 \begin{description}
1870 \item[Type] composite: \xmlel{slap:WavelengthRange}
1871 \item[Meaning]
1872 Spectral range in meters to be used to constrain the query
1873 of spectral lines.
1874
1875 \item[Occurrence] optional
1876
1877 \end{description}
1878 \item[Element \xmlel{queryDataCmd}]
1879 \begin{description}
1880 \item[Type] string: \xmlel{xs:string}
1881 \item[Meaning]
1882 Fully specified queryData test query formatted as an URL
1883 argument list in the syntax specified by the SLAP standard.
1884 The list must exclude the REQUEST argument which is
1885 assumed to be set to {"}queryData{"}. VERSION may be
1886 included if the test query applies to a specific version
1887 of the service protocol.
1888
1889 \item[Occurrence] optional
1890 \item[Comment]
1891 If queryDataCmd is used to form a query, the default
1892 value of WAVELENGTH specified above is not
1893 used; if the test query requires WAVELENGTH it
1894 should be included directly in queryDataCmd.
1895
1896 \item[Comment]
1897 This value must be a string in the form of name=value
1898 pairs delimited with ampersands (\&). A query may
1899 then be formed by appending to the baseURL the request
1900 argument, {"}REQUEST=queryData\&{"}, followed by the
1901 contents of this element.
1902
1903
1904 \end{description}
1905
1906
1907 \end{bigdescription}\endgroup
1908
1909 \endgroup
1910 \end{generated}
1911
1912 % /GENERATED
1913
1914 \subsubsection{WavelengthRange}
1915
1916 The \xmlel{slap:WavelengthRange} type is used to encode the \xmlel{testQuery}'s
1917 \xmlel{wavelength} element, the range of wavelengths to search.
1918
1919 % GENERATED: !schemadoc SLAP-v1.1.xsd WavelengthRange
1920 \begin{generated}
1921 \begingroup
1922 \renewcommand*\descriptionlabel[1]{%
1923 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{slap:WavelengthRange} Type Schema Documentation}
1924
1925 \noindent{\small
1926 Spectral range in meters to be used to constrain the query
1927 of spectral lines
1928 \par}
1929
1930 \vspace{1ex}\noindent\textbf{\xmlel{slap:WavelengthRange} Type Schema Definition}
1931
1932 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1933 <xs:complexType name="WavelengthRange" >
1934 <xs:sequence >
1935 <xs:element name="minWavelength" type="xs:double" minOccurs="0" />
1936 <xs:element name="maxWavelength" type="xs:double" minOccurs="0" />
1937 </xs:sequence>
1938 </xs:complexType>
1939 \end{lstlisting}
1940
1941 \vspace{0.5ex}\noindent\textbf{\xmlel{slap:WavelengthRange} Metadata Elements}
1942
1943 \begingroup\small\begin{bigdescription}\item[Element \xmlel{minWavelength}]
1944 \begin{description}
1945 \item[Type] floating-point number: \xmlel{xs:double}
1946 \item[Meaning]
1947 Minimum wavelength in meters to be used to constrain the query
1948 of spectral lines
1949
1950 \item[Occurrence] optional
1951
1952 \end{description}
1953 \item[Element \xmlel{maxWavelength}]
1954 \begin{description}
1955 \item[Type] floating-point number: \xmlel{xs:double}
1956 \item[Meaning]
1957 Maximum wavelength in meters to be used to constrain the query
1958 of spectral lines
1959
1960 \item[Occurrence] optional
1961
1962 \end{description}
1963
1964
1965 \end{bigdescription}\endgroup
1966
1967 \endgroup
1968 \end{generated}
1969
1970 % /GENERATED
1971
1972 \section{Auxiliary Capabilities for Simple DAL Protocols}
1973
1974 The endorsed note on discovering data collections DDC
1975 \citep{2019ivoa.rept.0520D} defines a method for separating metadata on
1976 the service that publishes one or more data collections from the
1977 metadata of these data collections themselves. This is particularly
1978 useful when, for instance, a single SSAP service publishes spectra from
1979 multiple experiments, surveys, or simulations. In this situations,
1980 publishers SHOULD register each data collection contained in a separate
1981 record as defined by DDC, and have one record for the service itself as
1982 specified here.
1983
1984 By DDC, the records for the data collections have to contain capability
1985 elements with special, bespoke \xmlel{standardID} values. For the
1986 capabilities described here, the corresponding auxiliary standardIDs
1987 are:
1988
1989 \begin{description}
1990 \item[SCS version 1] \verb|ivo://ivoa.net/std/ConeSearch#aux|
1991 \item[SIAP version 1] \verb|ivo://ivoa.net/std/SIA#aux|
1992 \item[SSAP version 1] \verb|ivo://ivoa.net/std/SSA#aux|
1993 \item[SLAP version 1] \verb|ivo://ivoa.net/std/SLAP#aux|
1994 \end{description}
1995
1996 While, contrary to the authority and path parts, the fragment
1997 part of ivoids is in principle case-sensitive, for ease of
1998 implementation we guarantee that no standard keys will be admitted to
1999 the resource records affected here that, when lowercased, would clash
2000 with the keys in the above identifiers. Clients may thus normalise
2001 SimpleDALRegExt standardIDs by lowercasing them as a whole without a
2002 prior parsing step.
2003
2004
2005 \appendix
2006
2007 \section{Supporting Multiple Versions of DAL Protocols}
2008
2009 This section is non-normative.
2010
2011 It is possible for a VOResource-encoded resource description to
2012 indicate support for multiple versions of standard service. This is
2013 described in general terms in Section~2.2.2 (``The service data model'') of the
2014 VOResource specification \citep{2008ivoa.spec.0222P}. In that section, the
2015 specification says that a \xmlel{capability} element can contain multiple
2016 \xmlel{interface} elements, each describing a different version.
2017
2018 In VO practice, in particular after the publication of StandardsRegExt
2019 \citep{2012ivoa.spec.0508H}, it turned out that declaring support
2020 of particular versions of IVOA
2021 standards (typically) happens with different capabilities, each with a
2022 different \xmlel{standardID}, rather than providing multiple interface
2023 elements with differing \xmlel{version} attributes as originially
2024 envisioned.
2025
2026 Here is an example a service that supports both SIA versions 1.0 and
2027 2.0, as well as a web browser interface on the 1.0 endpoint:
2028
2029 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2030 <vr:Resource xsi:type="vs:CatalogService">
2031 <title>Example Image Service</title>
2032 [...]
2033 <capability standardID="ivo://ivoa.net/std/SIA">
2034 <!-- this describes a SIA version 1 "face" of the service -->
2035 <interface role="std" xsi:type="vs:ParamHTTP">
2036 <!-- this is the SIA version 1.0 endpoint, the one standard
2037 clients talk to-->
2038 <accessURL use="base">http://example.com/asvc/sia.xml?</accessURL>
2039 <queryType>GET</queryType>
2040 <resultType>application/x-votable+xml</resultType>
2041 <param std="true">
2042 <name>POS</name>
2043 <description>ICRS Position, RA,DEC decimal degrees</description>
2044 [... enumerate the parameters supported ...]
2045 </param>
2046 </interface>
2047
2048 <interface xsi:type="vr:WebBrowser">
2049 <!-- this a a very SIA-like interface renderable in a web browser.
2050 If the web interface is functionally fairly different in
2051 interaction from a SIA version 1, put this into a separate,
2052 untyped capability -->
2053 <accessURL use="full">http://example.com/asvc/form.html</accessURL>
2054 </interface>
2055
2056 <imageServiceType>Pointed</imageServiceType>
2057 <maxRecords>1000000</maxRecords>
2058 <testQuery>
2059 <pos>
2060 <long>230.444</long>
2061 <lat>52.929</lat>
2062 </pos>
2063 <size>
2064 <long>0.1</long>
2065 <lat>0.1</lat>
2066 </size>
2067 </testQuery>
2068 </capability>
2069
2070 <capability standardID="ivo://ivoa.net/std/SIA#query-2.0">
2071 <!-- this describes a SIA version 2 "face" of the service -->
2072 <interface role="std" xsi:type="vs:ParamHTTP">
2073 <accessURL use="base">http://example.com/asvc/sia2.xml?</accessURL>
2074 <queryType>GET</queryType>
2075 <resultType>application/x-votable+xml</resultType>
2076 <param std="true">
2077 <name>POS</name>
2078 <description>Specification of a region of...</description>
2079 [... enumerate the parameters supported for SIAv2...]
2080 </param>
2081 </interface>
2082
2083 <imageServiceType>Pointed</imageServiceType>
2084 <maxRecords>10000</maxRecords>
2085 <testQuery>
2086 <pos>
2087 <long>230.444</long>
2088 <lat>52.929</lat>
2089 </pos>
2090 <size>
2091 <long>0.1</long>
2092 <lat>0.1</lat>
2093 </size>
2094 </testQuery>
2095 </capability>
2096 </vr:Resource>
2097 \end{lstlisting}
2098
2099
2100 \section{Change History}
2101
2102 \subsection{Changes from REC-1.1}
2103
2104 \begin{itemize}
2105 \item Added auxiliary ids for the standard ids covered.
2106
2107 \item Added language stressing the need for case-insensitive comparsions.
2108
2109 \item Dropped the SpaceFrame type, pointing to the relevant vocabulary
2110 instead. While this is, in principle, an incompatible change as the
2111 vocabulary is a good deal smaller than what SpaceFrame listed, no actual
2112 SSA record in the VO ever used one of the dropped identifiers. Also,
2113 clarifying that theoretical services don't have to give frames when
2114 they don't support POS. [in schema @version=1.3-wd1]
2115
2116 \item Dropped ProtoSpectralAccess type. Again, this is an incompatible
2117 change justified by the fact that no registered service uses this any
2118 more.
2119 \end{itemize}
2120
2121 \subsection{Changes from PR-2016-11-24}
2122
2123 Only editorial changes.
2124
2125 \subsection{Changes from PR-2016-07-06}
2126
2127 \begin{itemize}
2128 \item References to auxiliary SIAv2 capabilities removed again.
2129 \item Clarification that future standards are expected to override these
2130 regulations.
2131 \item Clarifications in the explanation of multi-version declarations,
2132 and how to interpret TestQuery for SIAv2.
2133 \end{itemize}
2134
2135 \subsection{Changes from REC-1.0}
2136
2137 \begin{itemize}
2138 \item \xmlel{standardID} values are no longer fixed for the various
2139 capability types.
2140 \item Now giving the \xmlel{standardID} values of the existing standards
2141 in the text (since they are no longer in the schema).
2142 \item XML schemas are no longer included in the document; the files in
2143 the IVOA repository are declared authoritative.
2144 \item We now claim, essentially, to describe the S-protocol metadata
2145 schemas until the respective standards define one themselves.
2146 \item Updated example in the appendix to the style of Identifiers 2.0
2147 \item Mentioning auxiliary capabilities and giving a standard id for
2148 them.
2149 \item Removing most material on ProtoSpectralAccess.
2150 \end{itemize}
2151
2152 \subsection{Changes since PR-v1.0 20130911}
2153
2154 \begin{itemize}
2155 \item none other than date and status.
2156 \end{itemize}
2157
2158 \subsection{Changes from PR-v1.0 20121116}
2159
2160 \begin{itemize}
2161 \item for SSA's creationType, changed specialExtraction to
2162 spectralExtraction.
2163 \item corrected Creation Type reference to section in SSA doc.
2164 \item made long and lat elements in ssap:PosParam required.
2165 \item incremented SSA schema version to 1.1 in namespace.
2166 \item refresh App. A from official schemas
2167 \item fixed typos ("IRCS" and value type for maxFileSize)
2168 \item noted that the <long> and <lat> values within the sia:SkySize type
2169 are given in degrees.
2170 \item Fixed documentation of SIA's sia:Query type in the schema.
2171 \end{itemize}
2172
2173 \subsection{Changes from PR-v1.0 20120517}
2174
2175 \begin{itemize}
2176 \item The namespace URIs given in Sections 3.1.1, 3.2.1, 3.3.1, and 3.4.1
2177 were updated to match that specified in the XSDs (i.e. to include a
2178 ``v'' preceding the version field).
2179 \item Several capability metadata with types xs:int and xs:float were
2180 changed to xs:positiveInterger xs:double to allow for larger/more
2181 precise numbers.
2182 \item Capability metadata that indicated maximum allowed values (e.g.
2183 <maxRecords>, <maxImageSize>, etc.) were made optional to avoid
2184 large, meaningless numbers from being provided. Now not specifying
2185 a value is the preferred way to indicate that no upper limit
2186 applies.
2187 \item Semantic definition of <sia:maxImageExtent> clarified to
2188 differentiate it from <sia:maxQueryRegionSize>
2189 \item The type for <sia:maxImageSize> was changed to xs:positiveInteger,
2190 a single number that represents the length of a side in pixels. The
2191 sia:ImageSize type (no longer needed) was dropped.
2192 \item The version field in the SIA namespace was incremented to 1.1 due
2193 to the non-backward-compatible change to <sia:maxImageSize>
2194 \item various typos and grammatical errors corrected.
2195 \end{itemize}
2196
2197 \subsection{Changes from WD-v1.0 20110921}
2198
2199 \begin{itemize}
2200 \item Now recommend ssap as prefix; changed all occurances of ssa in text
2201 and schema.
2202 \item added <supportedFrame> to ssap:SimpleSpectralAccess
2203 \item removed import of VODataService schema from SIA, SSA, and
2204 Conesearch schemas.
2205 \item change base type of controlled vocab types from xs:string to
2206 xs:token for consistancy with VOResource.
2207 \end{itemize}
2208
2209 \bibliography{ivoatex/ivoabib,ivoatex/docrepo}
2210
2211 \end{document}

Properties

Name Value
svn:keywords Date Rev URL

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