forked from ivoa-std/ConeSearch
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREC-SCS-1.03-20080222.html
executable file
·1182 lines (1039 loc) · 44.7 KB
/
REC-SCS-1.03-20080222.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Cone Search (Recommendation)</title>
<script type="text/javascript" src="/misc/jquery-1.2.6.min.js"></script>
<script type="text/javascript" src="/misc/generated-toc.js"></script>
<style type="text/css">
.issue {background-color: yellow}
.postponedissue {background-color: yellow}
.def code
.future {background-color: pink}
.draftedit {background-color: white}
.draftdelete {background-color: white}
.note { margin-left: 4em }
div.exampleInner pre { margin-left: 1em;
margin-top: 0em; margin-bottom: 0em}
div.exampleOuter {border: 4px double gray;
margin: 0em; padding: 0em}
div.exampleInner { border-top-width: 4px;
border-top-style: double;
border-top-color: white;
border-bottom-width: 4px;
border-bottom-style: double;
border-bottom-color: white;
padding: 0px; margin: 0em }
div.exampleWrapper { margin: 4px }
div.exampleHeader { font-weight: bold;
margin: 4px}
</style>
<link rel="stylesheet" href="http://www.ivoa.net/misc/ivoa_rec.css" type="text/css" />
</head>
<body>
<div class="head">
<a href="http://www.ivoa.net/"><img alt="IVOA" src="http://www.ivoa.net/pub/images/IVOA_wb_300.jpg"
width="300" height="169"></a>
<h1>Simple Cone Search<br />
Version 1.03</h1>
<h2>IVOA Recommendation
22 February 2008</h2>
<dl>
<dt>This version:</dt>
<dd><a href="http://www.ivoa.net/Documents/REC/DAL/ConeSearch-20080222.html">
http://www.ivoa.net/Documents/REC/DAL/ConeSearch-20080222.html</a></dd>
<dt>Latest version:</dt>
<dd><a href="http://www.ivoa.net/Documents/latest/ConeSearch.html">
http://www.ivoa.net/Documents/latest/ConeSearch.html</a></dd>
<dt>Previous versions:</dt>
<dd><a href="http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20070914.html">
http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20070914.html</a></dd>
<dd><a href="http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20070628.html">
http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20070628.html</a></dd>
<dd><a href="http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20060908.html">
http://www.ivoa.net/Documents/PR/DAL/ConeSearch-20060908.html</a><br />
</dd>
<br/>
<dt>Working Group:</dt>
<dd><a href="http://www.ivoa.net/twiki/bin/view/IVOA/IvoaDAL">http://www.ivoa.net/twiki/bin/view/IVOA/IvoaDAL</a></dd>
<dt>Editor:</dt>
<dd><a href="http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante">
Raymond Plante</a>
<dt>Authors:</dt>
<dd><a href="http://www.ivoa.net/twiki/bin/view/IVOA/RoyWilliams">
Roy Williams</a><br>
<a href="http://www.ivoa.net/twiki/bin/view/IVOA/BobHanisch">
Robert Hanisch</a><br>
<a href="http://www.ivoa.net/twiki/bin/view/IVOA/AlexSzalay">
Alex Szalay</a><br>
<a href="http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante">
Raymond Plante</a></dd>
</dl>
<hr>
</div>
<h2><a name="abstract" id="abstract">Abstract</a></h2>
This specification defines a simple query protocol for retrieving records
from a catalog of astronomical sources. The query describes sky
position and an angular distance, defining a cone on the sky. The
response returns a list of astronomical sources from the catalog whose
positions lie within the cone, formatted as a VOTable. This version of
the specification is essentially a transcription of the original Cone
Search specification in order to move it into the IVOA standardization
process.
<div class="status">
<h2><a name="status" id="status">Status of this document</a></h2>
<p>
This document has been produced by the IVOA Resource Registry Working
Group.<br/>
It has been reviewed by IVOA Members and other interested parties, and
has been endorsed by the IVOA Executive Committee as an IVOA
Recommendation as of 2007 September 27. It is a stable document and
may be used as reference material or cited as a normative reference
from another document. IVOA's role in making the Recommendation is to
draw attention to the specification and to promote its widespread
deployment. This enhances the functionality and interoperability
inside the Astronomical Community.
</p>
<p>
This document was originally published as a document of the
<a href="http://www.us-vo.org/">US National Virtual Observatory</a>
(NVO), available at
<a href="http://us-vo.org/pubs/files/conesearch.html">http://us-vo.org/pubs/files/conesearch.html</a>.
This IVOA version is essentially a transcription of that document into
the IVOA standards document format. Minor changes have been made to sharpen
the specification description where needed and to otherwise fit it
into the IVOA standards context; these changes are enumerated in
<a href="#appA">Appendix C</a>. It is the intention of this document
that <strong>all existing services compliant with the original NVO
document will be compliant with this specification</strong>.
Similarly, all future service implementations that are based on this
specification are expected to be compliant with the spirit of the
original NVO document and practices in the VO current at the time of
this writing; thus, existing client applications should work with the
new implementations without change.
</p>
<p>
Comments on this document can be sent to the Data Access Layer Working
Group via <a href="mailto:[email protected]">[email protected]</a>.
</p>
<p>
A list of <a href="http://www.ivoa.net/Documents/">current IVOA
Recommendations and other technical documents</a> can be found at
http://www.ivoa.net/Documents/.
</p>
<h2><a id="acknowledge" name="acknowledge">Acknowledgments</a></h2>
<p>Cone Search represents the first and arguably the most successful
"standard protocol" developed within the Virtual Observatory
movement. The editor, therefore, gratefully acknowledges the work of
the original authors of the Cone Search specification as well as the
numerous data providers who have implemented and continue to support
this protocol.</p>
<p>This document has been developed with support from the <a
href="http://www.nsf.gov">National Science Foundation's</a>
Information Technology Research Program under Cooperative Agreement
AST0122449 with The Johns Hopkins University.</p>
<a name="conf">
<h3>Conformance-related definitions</h3></a>
<p>The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and
"OPTIONAL" (in upper or lower case) used in this document are to be
interpreted as described in IETF standard, RFC 2119
<a href="#should">[RFC 2119]</a>. </p>
<p>The <a name="d:vo"><strong>Virtual Observatory (VO)</strong></a> is
general term for a collection of federated resources that can be used
to conduct astronomical research, education, and outreach.
<a name="d:ivoa">The</a> <a href="http://www.ivoa.net"><strong>International
Virtual Observatory Alliance (IVOA)</strong></a> is a global
collaboration of separately funded projects to develop standards and
infrastructure that enable VO applications. </p>
<p><a name="d:cone">A <strong>Cone</strong></a> is a circular region
on the sky defined by a sky position and a radius around that
position. A <a name="d:cs"><strong>Cone Search</strong></a> is a
query for information related to a Cone. The <a name="d:csp">
<strong>Cone Search Protocol</strong></a> refers to the protocol
described in this document. A <a name="d:css"><strong> Cone Search
Service</strong></a> is a service implementation that complies with
this standard. </p>
<!--
<a name="synnot">
<h3>Syntax Notation</h3></a>
<p>This document uses the Augmented Backus-Naur Form (ABNF) notation
(<a href="#abnf">RFC 2234</a>) to formally define syntax for the query
syntax. It references the following core ABNF syntax productions
(defined in section 6.1): ALPHA, DIGIT. </p>
-->
<h2><a id="contents" name="contents">Contents</a></h2>
<ul class="toc">
<li><a href="#abstract">Abstract</a></li>
<li><a href="#status">Status of this document</a></li>
<li><a href="#acknowledge">Acknowledgments</a></li>
<li><a href="#conf">Conformance-related definitions</a></li>
<!--
<li><a href="#synnot">Syntax Notation</a></li>
-->
<li><a href="#intro">1. Introduction</a>
<li><a href="#req">2. Service Interface Requirements</a>
<li><a href="#prof">3. The Resource Profile</a>
<li><a href="#appA">Appendix A: Sample VOTable Response
<li><a href="#appB">Appendix B: Current Practices for Representing
Resource Profiles</a></li>
<li><a href="#appC">Appendix C: Changes History</a>
<ul>
<li> <a href="#appC1">C.1. Changes From the Original NVO
Specification Document</a></li>
<li> <a href="#appC2">C.2. Changes From Previous IVOA Versions</a></li>
</ul>
<li><a href="#References">References</a></li>
</ul>
<hr>
<h2><a name="intro">1. Introduction</a></h2>
<p>
This specification describes how a provider of an astronomical source catalog
can publish that catalog to the Virtual Observatory in such a
way that a simple cone search can be done. The data remains in the
control of the data provider, served through a web server to the world, but
the query profile and response profile are carefully controlled, as
described below. It is intended that setting up this web service be simple
enough that data providers will not have to spend too much time on it
(their funding to support such services is typically small). At the
same time, the service implementation and the data it provides can
serve as a basis for more sophisticated tools.
</p>
<p>
This specification does not specify how Cone Search services are
implemented, or how the data are stored or manipulated. The concern
of this specification is how the data are exposed to the world through
well-defined requests and responses.
</p>
<p>
This specification assumes that the data provider has already
selected a catalog of astronomical sources. This catalog can be
presented as a single table; it is expected that the table contains
several columns.
</p>
<a name="req">
<h2>2. Service Interface Requirements</h2></a>
A service implementation that is compliant with this standard must
meet the following requirements:
<ol>
<li> the service must respond to a HTTP GET request represented by a
URL having two parts:
<ul>
<li> <p>A base URL of the form:</p>
<p>
<b>http://</b><i><server-address></i><b>/</b><i><path></i><b>?</b><i>[<extra-GET-arg><b>&</b>[...]]</i>
</p>
<p>
where <i><server-address></i> and
<i><path></i> are URI-compliant components
indicating the domain address and local location path
where the service is deployed. The
<i><server-address></i> may end with one or more
locally supported URL arguments, <i><extra-GET-arg></i>;
these arguments are not recognized parts of the Cone Search
protocol and thus are treated opaquely by clients of the
service as part of the base URL.
</p>
<p>
Note that when it contains extra GET arguments, the base
URL ends in an ampersand, <strong>&</strong>; if
there are no extra arguments, then it ends in a question
mark, <strong>?</strong>.
</p>
<p>
<TABLE cellPadding=5 bgColor=#dddddd border=2>
<TBODY>
<TR>
<TD>
<DL>
<DT><STRONG>Examples:</STRONG>
<DD><TT>http://mycone.org/cgi-bin/VOsearch? <BR>
http://adil.ncsa.uiuc.edu/vocone?resolv&issurvey=T&</TT>
</DD>
</DL>
</TD>
</TR>
</TBODY>
</TABLE>
</p>
<p>Every query to a given cone search service uses the same
base URL.</p>
<li> <p>Constraints expressed as a list of ampersand-delimited
GET arguments of the form: <br>
<i><name></i><b>=</b><i><value></i>
</p>
<p>
where <i><name></i> is a parameter name specified
by this specification and <i><value></i> is its
value. The constraints represent the query parameters which
can vary for each successive query. The order of the
name-parameter pairs is not significant.
</p>
<li> <P>The baseURL and constraint list are concatenated to form
the query. </P>
<li> <p><a name="p:req">
The set of query constraints must include the following
parameters</a>, which are interpreted by the service with
the stated meaning:
<ul>
<li><a name="p:RA"><b>RA</b></a> -- a right-ascension
in the ICRS coordinate system for the positon of
the center of the cone to search, given in
decimal degrees. </li>
<li><a name="p:DEC"><b>DEC</b></a> -- a declination in
the ICRS coordinate system for the positon of
the center of the cone to search, given in
decimal degrees. </li>
<li><a name="p:SR"><b>SR</b></a> -- the radius of the
cone to search, given in decimal degrees. </li>
</ul></p>
<p>
<TABLE cellPadding=5 bgColor=#dddddd border=2>
<TBODY>
<TR>
<TD>
<DL>
<DT><STRONG>Example:</STRONG>
<DD><TT>http://mycone.org/cgi-bin/search?RA=180.567&DEC=-30.45&SR=0.0125
</tt></DD>
</DL>
</TD>
</TR>
</TBODY>
</TABLE>
</p>
<li> <p>The query MAY contain the optional parameter,
<a name="p:VERB"><strong>VERB</strong></a>, whose value
is an integer--either 1, 2, or 3--indicating verbosity
which determines how many columns are to be returned in
the resulting table. Support for this parameter by a
Cone Search service implementation is optional. If the
service supports the parameter, then when the value is
1, the response should include the bare minimum of
columns that the provider considers useful in describing
the returned objects (while still remaining compliant
with this standard; see <a href="#response">section
2.2</a> below). When the value is 3, the service
should return all of the columns that are available for
describing the objects. A value of 2 is intended for
requesting a medium number of columns between the
minimum and maximum (inclusive) that are considered by
the provider to most typically useful to the user. When
the VERB parameter is not provided, the server should
respond as if VERB=2. If the VERB parameter is not
supported by the service, the service should ignore the
parameter and should always return the same columns for
every request. </p> </li>
<li> <p>There may be other parameters in the query, but this
document does not specify their meaning or usage. If a
query includes an optional parameter, either one
specified by this document or not, that is not supported
by the service implementation, the service must ignore
that parameter.</p> </li>
</ul>
A query following this syntax represents a request for
information on sources located within the specified cone on the
sky.
<li> <p><a name="resp"></a>The service must respond with an XML
document in the VOTable format, that represents a table of
astronomical sources whose positions are within the cone (see
<a href="#appA">Appendix A</a> for an example). There may also
be other sources outside the cone -- the service implementor
may decide on the exact search criterion used internally to the
service to select the sources.</p> </li>
<p>
The base MIME-type of the HTTP response should be <TT>text/xml</TT>.
The more specific form <TT>text/xml;content=x-votable</TT> may
optionally be used. The MIME-type, <tt>text/xml;votable</tt>
shall also be considered legal (for backward compatibility
reasons); however, this value is strongly discouraged as it is
not compliant with the MIME-type standard [<a href="#mime">MIME</a>].
The XML content of the response must be compliant with VOTable
schema, version 1.0 [<a href="#vot10">VOTable v1.0</a>] or 1.1
[<a href="#vot11">VOTable v1.1</a>].
</p>
<blockquote>
<table bgcolor="#dddddd" border="2" cellpadding="5"><tbody><tr><td>
<dl>
<dt> <strong>Editor's Note:</strong> </dt>
<dd> The original NVO specification allowed a MIME-type of
<tt>text/xml;votable</tt>, thus for backward compatibility this
is still allowed but discouraged. </dd>
</dl>
</td></tr></tbody></table>
</blockquote>
<p>The VOTable MUST comply with these conditions:</p>
<ul>
<li> <p>There must be a single RESOURCE in the VOTable, and
that contains a single TABLE.</p> </li>
<li> <p>The TABLE must have FIELDS where the following UCD
[<a href="http://vizier.u-strasbg.fr/UCD">UCD</A>] values
have been set. There must only be one FIELD with each of
these UCDs: </p> </li>
<ul>
<li> <p>Exactly one FIELD must have ucd="ID_MAIN", with
an array character type (fixed or variable length),
representing an ID string for that record of the
table. This identifier may not be repeated in the
table, and it could be used to retrieve that same
record again from that same table.</p> </li>
<li> <p>Exactly one FIELD must have ucd="POS_EQ_RA_MAIN",
with type double, representing the
right-ascension of the source in the ICRS
coordinate system. </p> </li>
<li> <p>Exactly one FIELD must have ucd="POS_EQ_DEC_MAIN",
with type double, representing the declination of
the source in the ICRS coordinate system. <p> </li>
</ul>
<li> <p> The VOTable may include an expression of the uncertainty
of the positions given in the above mentioned
fields to be interpreted either as a positional error of
the source positions, or an angular size if the
sources are resolved. If this uncertainty is not
provided, it should be taken to be zero; otherwise, it
may be set for all table entries with a PARAM in the
RESOURCE which has a UCD that is set to OBS_ANG-SIZE and
has a value which is the angle in decimal degrees.
Alternatively, a different value for each row in the
table can be given via a FIELD in the table having a UCD
set to OBS_ANG-SIZE. </p> </li>
<li> <p> There may be other FIELDs in the table. Their
specification should include a description, data-type,
and UCD. </p> </li>
</ul>
<li> <p> The service must respond with a stubbed version of the
VOTable in the case of error. This must happen if the three
<a href="#p:req">required parameters</a> (RA, DEC, SR) are not
all present, or if their values cannot be parsed to
floating-point numbers, or if the numbers are out of range
(DEC=91.0, for example). The service may also make an error
return if the search radius (give by the <a href="p:SR">SR</a>
parameter) is larger than the MaxSR parameter of the Resource
Profile (see <a href="prof">Section 3</a>). </p> </li>
<P> In the case of error, the service MUST respond with a
VOTable that contains a single PARAM element <em>or</em> a
single INFO element with <B><code>name="Error"</code></B>,
where the corresponding value attribute should contain some
explanation of the nature of the error. If an INFO element is
used, it must appear as a direct child of one of the following
elements: </p>
<ul>
<li> the root VOTABLE element (which is preferred by this
document), or
<li> the RESOURCE element </li>
</ul>
<p>If a PARAM element is used, it must appear as a direct child of
one of following elements: </p>
<ul>
<li> the RESOURCE element, or </li>
<li> a DEFINITION element below the root
VOTABLE element (which is discouraged by this document). </li>
</ul>
<blockquote>
<table bgcolor="#dddddd" border="2" cellpadding="5"><tbody><tr><td>
<dl>
<dt> <strong>Editor's Note:</strong> </dt>
<dd> It was recognized that this requirement, as it was described in
the original NVO specification, is ambiguous about both the
element to use for the ERROR message and its location in the document.
The VOTable standard allows PARAM and INFO elements to appear in
various places within the document. Since several of the
different methods have been used in practice by
Cone Search service implementations, no attempt is made in this
version to correct this ambiguity. All of the above-mentioned
locations should be considered legal, and Cone Search service
clients should be prepared to look in all of them for an ERROR
message. The use of PARAM as a child of DEFINITIONS is
discouraged as the DEFINITIONS element was deprecated in
VOTable v1.1.</dd>
</dl>
</td></tr></tbody></table>
</blockquote>
<div class="exampleOuter">
<a name="ex:errors"></a>
<div class="exampleHeader">Example Error Responses:</div>
<div class="exampleWrapper"><a name="ex:votable">Error INFO as child
of VOTABLE (preferred)</a></div>
<div class="exampleInner" style="background-color: rgb(213, 222, 227);">
<pre><?xml version="1.0"?>
<!DOCTYPE VOTABLE SYSTEM "http://us-vo.org/xml/VOTable.dtd">
<VOTABLE version="1.0">
<DESCRIPTION>MAST Simple Cone Search Service</DESCRIPTION>
<INFO ID="Error" name="Error" value="Error in input RA value: as3f"/>
</VOTABLE>
</pre>
</div>
<div class="exampleHeader"></div>
<div class="exampleWrapper"><a name="ex:votable">Error PARAM as child
of RESOURCE (allowed)</a></div>
<div class="exampleInner" style="background-color: rgb(213, 222, 227);">
<pre><?xml version="1.0"?>
<!DOCTYPE VOTABLE SYSTEM "http://us-vo.org/xml/VOTable.dtd">
<VOTABLE version="1.0">
<DESCRIPTION>
HEASARC Browse data service
Please send inquiries to mailto:[email protected]
</DESCRIPTION>
<RESOURCE ID="error_resource">
<PARAM ID="Error" name="Error" datatype="char" arraysize="*"
value="Invalid data type: text/html"/>
</RESOURCE>
</VOTABLE>
</pre>
</div>
</div>
<p> Other conditions may NOT be considered erroneous, for
example if a query cone is in the Southern hemisphere and the
catalog coverage is in the Northern hemisphere. This type of
query is different from an error return; it should return a
VOTable as described above, with metadata, but no data
records. In particular, a zero value of Search Radius should
not return an error condition. This is because an application
may be more interested in the metadata than the data, and send
a fixed query (for example RA=0&DEC=90&SR=0) simply to
discover the fields delivered by the service. </p> </li>
</ol>
<a name="prof">
<h2>3. The Resource Profile</h2></a>
<p>
A Cone Search service MUST be described with a Resource Profile that
includes the following information. The Profile is composed of named
metadata listed below. The format used to encode the profile should be
compliant with the publishing standards of the IVOA throughout the time
the service is supported by the data provider. The metadata names
and values used in the profile encoding should match those given below
as closely as possible; where they do not match exactly, they should
be consistent with the IVOA metadata conventions in place at any given
time and the mapping of names and values actually used and those given
below should be well documented.
</p>
<blockquote>
<table bgcolor="#dddddd" border="2" cellpadding="5"><tbody><tr><td>
<dl>
<dt> <strong>Editor's Note:</strong> </dt>
<dd> The original NVO specification pre-dates the IVOA standard for
resource metadata [<a name="rm">RM</a>], and so, obviously,
some inconsistencies with that standard exist. To deal with
this, the wording of this section has been altered to allow
profiles to be constructed according to the latest practices in
the IVOA. Appendix B outlines the mapping of the metadata
listed below to that in the RM as well as the XML Schema used
to render the metadata within a Registry.</dd>
</dl>
</td></tr></tbody></table>
</blockquote>
<p>
Several of the metadata listed below can have values that are
hierarchical; this hierarchy should be represented in a manner most
appropriate to the format used. When the format does not provide any
such mechanism, it is recommended that the value be represented as a
strings delimited by dots with the root domain of the value appearing
first.
</p>
<p>
The resource profile consists of the following metadata with the
stated definitions:
</p>
<ul>
<li> <p><b>ResponsibleParty</b>: The data provider's name and
email.</p></li>
<li> <p><b>ServiceName</b>: The name of the catalog served by the
service, for example "IRSA.2MASS.ExtendedSources".</p></li>
<li> <p><b>Description</b>: A couple of paragraphs of text that
describe the nature of the catalog and its wider context.</p></li>
<li> <p><b>Instrument</b>: The instrument that made the observations, for
example STScI.HST.WFPC2. </p></li>
<li> <p><b>Waveband</B>: The waveband of the observations, with ONE
selected from this list: radio, millimeter, infrared, optical,
ultraviolet, xray, gammaray. </p></li>
<li> <p><b>Epoch</B>: The epoch of the observations, as a free-form
string. </p></li>
<li> <p><b>Coverage</B>: The coverage on the sky, as a free-form
string. </p></li>
<li> <p><b>MaxSR</B>: The largest search radius, given in decimal
degrees, that will be accepted by the service without returning
an error condition. A value of 180.0 indicates that there is
no restriction. </p></li>
<li> <p><b>MaxRecords</B>: The largest number of records that the
service will return. </p></li>
<li> <p><b>Verbosity</B>: True or false, depending on whether the
service supports the VERB keyword in the request. </p></li>
<li> <p><b>BaseURL</B>: The base URL for the service as described in
<a href="#req">Section 2</a>. </p></li>
</ul>
<p>
The service will be considered published to the VO if the profile has
been added to an IVOA Registry according to the IVOA standards and
conventions at the time the service is made available, TOGETHER with
maintaining the web service that is described by the profile in
compliant order.
</p>
<a name="appA">
<h2>Appendix A: Sample VOTable Response</h2></a>
<p>
This is a sample of a legal response to a Cone Search query.
</p>
<div class="exampleOuter">
<a name="ex:errors">
</a><div class="exampleHeader">Example VOTable Response:</div>
<div class="exampleInner" style="background-color: rgb(213, 222, 227);">
<pre><?xml version="1.0"?>
<!DOCTYPE VOTABLE SYSTEM "http://us-vo.org/xml/VOTable.dtd">
<VOTABLE version="1.0">
<DEFINITIONS>
<COOSYS system="eq_FK5" equinox="2000" />
</DEFINITIONS>
<RESOURCE ID="T9001">
<DESCRIPTION>
HEASARC Browse data service
Please send inquiries to mailto:[email protected]
</DESCRIPTION>
<PARAM ID="default_search_radius" ucd="OBS_ANG-SIZE" datatype="double"
value="0.0516666666666667" />
<TABLE ID="heasarc_first_9001">
<DESCRIPTION> Faint Images of the Radio Sky at Twenty cm Source Catalog (FIRST) </DESCRIPTION>
<FIELD name="unique_id" datatype="char" arraysize="*" ucd="ID_MAIN">
<DESCRIPTION> Integer key </DESCRIPTION>
</FIELD>
<FIELD name="name" datatype="char" arraysize="*" >
<DESCRIPTION> FIRST Source Designation </DESCRIPTION>
</FIELD>
<FIELD name="ra" datatype="double" unit="degree" ucd="POS_EQ_RA_MAIN">
<DESCRIPTION> Right Ascension </DESCRIPTION>
</FIELD>
<FIELD name="dec" datatype="double" unit="degree" ucd="POS_EQ_DEC_MAIN">
<DESCRIPTION> Declination </DESCRIPTION>
</FIELD>
<FIELD name="flux_20_cm" datatype="double" unit="mJy" >
<DESCRIPTION> Peak 1.4GHz Flux Density (mJy) </DESCRIPTION>
</FIELD>
<FIELD name="flux_20_cm_error" datatype="double" unit="mJy" >
<DESCRIPTION> Estimated rms in at Source (mJy) </DESCRIPTION>
</FIELD>
<FIELD name="int_flux_20_cm" datatype="double" unit="mJy" >
<DESCRIPTION> Integrated 1.4GHz Flux Density (mJy) </DESCRIPTION>
</FIELD>
<DATA>
<TABLEDATA>
<TR>
<TD>384559</TD><TD>FIRST J120002.6+595708</TD>
<TD>180.0110042</TD><TD>59.9523889</TD>
<TD> 1.11</TD><TD> 0.139</TD><TD> 1.14</TD>
</TR>
<TR>
<TD>385094</TD><TD>FIRST J120025.3+600103</TD>
<TD>180.1057250</TD><TD>60.0175556</TD>
<TD> 2.89</TD><TD> 0.142</TD><TD> 2.56</TD>
</TR>
<TR>
<TD>384928</TD><TD>FIRST J120018.1+600236</TD>
<TD>180.0755500</TD><TD>60.0434750</TD>
<TD> 19.38</TD><TD> 0.145</TD><TD> 19.23</TD>
</TR>
<TR>
<TD>384490</TD><TD>FIRST J115959.4+600403</TD>
<TD>179.9978875</TD><TD>60.0677083</TD>
<TD> 1.01</TD><TD> 0.147</TD><TD> 1.20</TD>
</TR>
</TABLEDATA>
</DATA>
</TABLE>
</RESOURCE>
</VOTABLE>
</pre>
</div>
</div>
<a name="appB">
<h2>Appendix B: Current Practices for Representing Resource Profiles</h2></a>
<a name="appB1">
<h3>B.1. Mapping for Resource Profile Metadata to the RM</h3></a>
<p>
As mentioned in an Editor's Note in <a href="#prof">Section 3</a>, the
original NVO specification pre-dated the IVOA standard for resource
metadata known as the RM [<a href="#rm">RM</a>]. This section
indicates how the resource profile metadata defined in this
specification maps to the metadata defined in the RM.
</p>
<blockquote>
<table border="2" cellspacing="2">
<tr>
<th>Cone Search Metadatum</th> <th>RM Metadatum</th>
</tr>
<tr>
<td><b>ResponsibleParty</b></td>
<td>Publisher, <br>
Contact.Email</td>
</tr>
<tr>
<td><b>ServiceName</b></td>
<td>Title</td>
</tr>
<tr>
<td><b>Description</b></td>
<td>Description</td>
</tr>
<tr>
<td><b>Instrument</b></td>
<td>Instrument</td>
</tr>
<tr>
<td><b>Waveband</b></td>
<td>Coverage.Spectral</td>
</tr>
<tr>
<td><b>Epoch</b></td>
<td>Coverage.Temporal.StartTime,<br>
Coverage.Temporal.StopTime<sup>1</sup></td>
</tr>
<tr>
<td><b>Coverage</b></td>
<td>Coverage.Spatial</td>
</tr>
<tr>
<td><b>MaxSR</b></td>
<td>Service.MaxSearchRadius</td>
</tr>
<tr>
<td><b>MaxRecords</b></td>
<td>Service.MaxReturnRecords</td>
</tr>
<tr>
<td><b>Verbosity</b></td>
<td><i>n/a</i><sup>2</sup></td>
</tr>
<tr>
<td><b>BaseURL</b></td>
<td>Service.BaseURL</td>
</tr>
</table>
<sup>1</sup>The notion of the epoch the observations is captured in
the RM as the temporal coverage. The notion of the equinox of the
observational positions is captured part of the RM's
Coverage.Spatial. <br>
<sup>2</sup>As this concept is not covered by the RM, it should be
considered service-specific capability metadata.
</blockquote>
<a name="appB2">
<h3>B.2. VOResource (pre-v1.0) Schema Extension for Cone Search
Services</h3></a>
<p>
Just prior to the adoption of IVOA standard for registry interfaces,
v1.0 [<a href="#RI">RI</a>], resource descriptions were encoded using
the VOResource XML Schema,
<a href="http://www.ivoa.net/xml/VOResource/v0.10">v0.10</a> and its
family of extension schemas. The extensions used to specifically
describe Cone Search services were
<a href="http://www.ivoa.net/xml/VOResource/v0.10">VODataService,
v0.5</a> and <a href="http://www.ivoa.net/xml/ConeSearch/v0.3">
ConeSearch, v0.3</a>. See the embedded documentation in each of these
schemas for the precise definitions and usage of the metadata encodable
through them.
</p>
<p>
The following table enumerates the mapping of resource profile
metadata defined in this specification with those defined in the XML
schemas.
</p>
<blockquote>
<table border="2" cellspacing="2">
<tr>
<th rowspan="2">Cone Search Metadatum</th>
<th colspan="2">VOResource Metadatum</th>
</tr>
<tr>
<th>Schema Name</th>
<th>XPath Name</th>
</tr>
<tr>
<td><b>ResponsibleParty</b></td>
<td>VOResource</td>
<td><code>curation/publisher</code>, <br>
<code>curation/contact/email</code></td>
</tr>
<tr>
<td><b>ServiceName</b></td>
<td>VOResource</td>
<td><code>title</code></td>
</tr>
<tr>
<td><b>Description</b></td>
<td>VOResource</td>
<td><code>content/description</code></td>
</tr>
<tr>
<td><b>Instrument</b></td>
<td>VOResource</td>
<td><code>instrument</code></td>
</tr>
<tr>
<td><b>Waveband</b></td>
<td>VODataService</td>
<td><code>coverage/spectral/waveband</code></td>
</tr>
<tr>
<td><b>Epoch</b></td>
<td>VODataService</td>
<td><code>coverage/temporal/startTime</code>,<br>
<code>coverage/temporal/stopTime</code><sup>1</sup></td>
</tr>
<tr>
<td><b>Coverage</b></td>
<td>VODataService</td>
<td><code>coverage/spatial</code><sup>2</sup></td>
</tr>
<tr>
<td><b>MaxSR</b></td>
<td>ConeSearch</td>
<td><code>capability/maxSR</code></td>
</tr>
<tr>
<td><b>MaxRecords</b></td>
<td>ConeSearch</td>
<td><code>capability/maxRecords</code></td>
</tr>
<tr>
<td><b>Verbosity</b></td>
<td>ConeSearch</td>
<td><code>capability/verbosity</code></td>
</tr>
<tr>
<td><b>BaseURL</b></td>
<td>VOResource</td>
<td><code>interface/accessURL</code></td>
</tr>
</table>
<sup>1</sup>The notion of the epoch the observations is captured in
the schema inside coverage/temporal. The notion of the equinox of the
observational positions is captured within coverage/spatial/region,
such as in coverage/spatial/region[@xsi:type='vs:Circle']/coordFrame. <br>
<sup>2</sup>the coverage/spatial element encodes its information as a
complex set of child elements.
</blockquote>
<a name="appB3">
<h3>B.3. VOResource (v1.0) Schema Extension for Cone Search Services</h3></a>
<p>
With the expected adoption of the IVOA standard for Registry Interface
[<a href="#RI">RI</a>], resources are described using the VOResource
schema, v1.0 [<a href="VOR">VOR</a>] and its family of extensions.
Cone Search services are specifically described using the
<a href="http://www.ivoa.net/xml/VOResource/v0.10">VODataService,
v1.0</a>, and <a href="http://www.ivoa.net/xml/ConeSearch/v0.3">
ConeSearch, v1.0</a>, extension schemas. Coverage information is
encoded using the Space-Time Coordinates (STC) schema
[<a href="#stc">STC</a>].
</p>
<p>
The following table enumerates the mapping of resource profile
metadata defined in this specification with those defined in the XML
schemas.
</p>
<table border="2" cellspacing="2">
<tr>
<th rowspan="2">Cone Search Metadatum</th>
<th colspan="2">VOResource Metadatum</th>
</tr>
<tr>
<th>Schema Name</th>
<th>XPath Name</th>
</tr>
<tr>
<td><b>ResponsibleParty</b></td>
<td>VOResource</td>
<td><code>curation/publisher</code>, <br>
<code>curation/contact/email</code></td>
</tr>
<tr>
<td><b>ServiceName</b></td>
<td>VOResource</td>
<td><code>title</code></td>
</tr>
<tr>
<td><b>Description</b></td>
<td>VOResource</td>
<td><code>content/description</code></td>
</tr>
<tr>
<td><b>Instrument</b></td>
<td>VOResource</td>
<td><code>instrument</code></td>
</tr>
<tr>
<td><b>Waveband</b></td>
<td>VODataService</td>
<td><code>coverage/waveband</code></td>
</tr>
<tr>
<td><b>Epoch</b></td>
<td>VODataService</td>
<td><code>coverage/stc:STCResourceProfile/stc:AstroCoordArea</code><sup>1</sup></td>
</tr>
<tr>
<td><b>Coverage</b></td>
<td>VODataService</td>
<td><code>coverage/stc:STCResourceProfile/stc:AstroCoordArea</code><sup>1</sup></td>
</tr>
<tr>
<td><b>MaxSR</b></td>
<td>ConeSearch</td>