/[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 5920 - (show annotations)
Wed Dec 16 09:31:00 2020 UTC (4 months ago) by msdemlei
File MIME type: application/x-tex
File size: 94810 byte(s)
Preparing for PR-1.2.


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

Properties

Name Value
svn:keywords Date Rev URL

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