/[volute]/trunk/projects/grid/vospace/doc/VOSpace.html
ViewVC logotype

Contents of /trunk/projects/grid/vospace/doc/VOSpace.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2904 - (show annotations)
Thu Apr 2 23:08:56 2015 UTC (5 years, 8 months ago) by major.brian
File MIME type: text/html
File size: 140844 byte(s)
progress towards VOSpace in ivoatex
1 <?xml version="1.0" encoding="utf-8"?>
2 <html xmlns="http://www.w3.org/1999/xhtml"><head><link xmlns="http://www.w3.org/1999/xhtml" rel="stylesheet" type="text/css" href="http://www.ivoa.net/misc/ivoa_doc.css"/><link xmlns="http://www.w3.org/1999/xhtml" rel="stylesheet" type="text/css" href="http://www.ivoa.net/misc/ivoa_wd.css"/><style xmlns="http://www.w3.org/1999/xhtml" type="text/css">
3 div#versionstatement, div#dateline {
4 color: #005A9C;
5 font-size: 150%;
6 }
7
8 p.parsep {
9 overflow: hidden;
10 height: 0pt;
11 margin-top:0.5ex;
12 margin-bottom:0.5ex;
13 }
14
15 div.admonition {
16 width: 30em;
17 position: relative;
18 float: right;
19 background-color: #dddddd;
20 font-size: 80%;
21 margin: 1ex;
22 padding: 3pt;
23 overflow: auto;
24 }
25
26 p.admonition-type {
27 background-color: #444444;
28 color: #ffffff;
29 margin-top: 0px;
30 padding-left: 5pt;
31 padding-top: 5pt;
32 padding-bottom: 5pt;
33 font-weight: bold;
34 }
35
36 a.tth_citation, a.tth_citeref {
37 color: #002A5C;
38 text-decoration: none;
39 }
40
41 .xmlel {
42 font-family: monospace;
43 font-style: italic;
44 }
45
46 .vorent {
47 font-variant: small-caps;
48 }
49
50 table {
51 border-collapse: collapse;
52 border-spacing: 0px;
53 }
54
55 table.tabular {
56 margin-top: 2ex;
57 margin-bottom: 1ex;
58 margin-left: 0.5em;
59 }
60
61 table.tabular > * > tr > td, table.tabular > tr > td {
62 border-top: 1pt solid gray;
63 border-bottom: 1pt solid gray;
64 padding: 2pt;
65 }
66
67 dt {
68 margin-top: 0.5ex;
69 }
70
71 .redaction {
72 background-color: #ffff33;
73 }
74
75 span.nolinkurl {
76 font-family: monospace;
77 }
78 &gt;</style><meta name="GENERATOR" content="TtH 4.06"/><meta http-equiv="Content-type" content="text/html;charset=UTF-8"/></head><div>
79
80
81 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
82
83 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
84
85
86 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
87
88
89 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
90
91
92 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
93
94 <div><table xmlns="http://www.w3.org/1999/xhtml" cellspacing="0" cellpadding="0" width="450"><tr><td><a href="http://www.ivoa.net/"><img height="169" alt="IVOA" src="http://www.ivoa.net/icons/IVOA_wb_300.jpg" width="300" border="0"/></a></td><td><div style="padding: 3.6pt 7.2pt;"><p><b><i><span style="font-size: 14pt; color: rgb(0, 90, 156);"><span> </span>I</span></i></b><i><span style="font-size: 14pt; color: rgb(0, 90, 156);">nternational</span></i></p><p><b><i><span style="font-size: 14pt; color: rgb(0, 90, 156);"><span>   </span>V</span></i></b><i><span style="font-size: 14pt; color: rgb(0, 90, 156);">irtual</span></i></p><p><b><i><span style="font-size: 14pt; color: rgb(0, 90, 156);"><span> </span><span>  </span>O</span></i></b><i><span style="font-size: 14pt; color: rgb(0, 90, 156);">bservatory</span></i></p><p><b><i><span style="font-size: 14pt; color: rgb(0, 90, 156);">A</span></i></b><i><span style="font-size: 14pt; color: rgb(0, 90, 156);">lliance</span></i><i/></p></div><i/></td></tr></table><br xmlns="http://www.w3.org/1999/xhtml"/></div><h1 xmlns="http://www.w3.org/1999/xhtml">VOSpace </h1><div xmlns="http://www.w3.org/1999/xhtml" id="versionstatement">
95 Version 2.1</div><div xmlns="http://www.w3.org/1999/xhtml" id="dateline">IVOA Working Draft <span xmlns="" id="docdate">20140805</span></div><dl xmlns="http://www.w3.org/1999/xhtml" id="docmeta"><dt>Working Group</dt><dd xmlns="" id="ivoagroup">Grid and Web Services Working Group</dd><dt>This Version</dt><dd><a class="currentlink" href="http://www.ivoa.net/documents/VOSpace/201480">http://www.ivoa.net/documents/VOSpace/201480</a></dd><dt>Latest Version</dt><dd><a class="latestlink" href="http://www.ivoa.net/documents/VOSpace">http://www.ivoa.net/documents/VOSpace</a></dd><dt>Previous Versions</dt><dd><ul class="previousversions"><li xmlns="" class="previousversion">
96 <a href="http://www.ivoa.net/Documents/WD/GWS/REC-VOSpace-2.0-20130329.html">REC-VOSpace-2.0-20130329</a></li><li xmlns="" class="previousversion">
97 <a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20121221.html">PR-VOSpace-2.0-20121221</a></li><li xmlns="" class="previousversion">
98 <a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20120824.html">PR-VOSpace-2.0-20120824</a></li><li xmlns="" class="previousversion">
99 <a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20111202.html">PR-VOSpace-2.0-20111202</a></li><li xmlns="" class="previousversion">
100 <a href="http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20110628.html">WD-VOSpace-2.0-20110628</a></li><li xmlns="" class="previousversion">
101 <a href="http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20101112.html">WD-VOSpace-2.0-20101112</a></li><li xmlns="" class="previousversion">
102 <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20100323.html">WD-VOSpace-2.0-20100323</a></li><li xmlns="" class="previousversion">
103 <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090904.html">WD-VOSpace-2.0-20090904</a></li><li xmlns="" class="previousversion">
104 <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090513.doc">WD-VOSpace-2.0-20090513</a></li></ul></dd><dt>Author(s)</dt><dd><ul class="authors"><li xmlns="" class="author">Matthew Graham</li><li xmlns="" class="author">Dave Morris</li><li xmlns="" class="author">Guy Rixon</li><li xmlns="" class="author">Pat Dowler</li><li xmlns="" class="author">Andre Schaaff</li><li xmlns="" class="author">Doug Tody</li><li xmlns="" class="author">Brian Major</li></ul></dd><dt>Editor(s)</dt><dd><ul class="editors"><li xmlns="" class="editor">Matthew Graham</li><li xmlns="" class="editor">Brian Major</li></ul></dd></dl>
105 <div id="abstract"><h2>Abstract</h2>
106
107
108 VOSpace is the IVOA interface to distributed storage. This specification presents the second RESTful version of the interface. Except for minor additions to the 2.1 specification, it is functionally equivalent to the SOAP-based VOSpace 1.1 specification. Note that all 1.x VOSpace clients will not work with this new version of the interface. Clients and services written for VOSpace 2.1 will interoperate with 2.0 clients and services, however 2.0 clients and services are incompatible with the 2.1 specification.
109 </div>
110 <h2>Status of this Document</h2>
111 <p xmlns="http://www.w3.org/1999/xhtml" id="statusdecl"><em>
112 This is an IVOA Working Draft for review by IVOA members
113 and other interested parties. It is a draft document and
114 may be updated, replaced, or obsoleted by other documents
115 at any time. It is inappropriate to use IVOA Working Drafts
116 as reference materials or to cite them as other than "work
117 in progress".
118 </em></p>
119
120 <h1>Contents </h1><a href="#tth_sEc1">1  Introduction</a><br/>
121     <a href="#tth_sEc1.1">1.1  Typical use of a VOSpace service</a><br/>
122     <a href="#tth_sEc1.2">1.2  Role within the VO Architecture</a><br/>
123     <a href="#tth_sEc1.3">1.3  Document roadmap</a><br/><a href="#tth_sEc2">2  VOSpace identifiers</a><br/>
124     <a href="#tth_sEc2.1">2.1  Identifier resolution</a><br/><a href="#tth_sEc3">3  VOSpace data model</a><br/>
125     <a href="#tth_sEc3.1">3.1  Nodes and node types</a><br/>
126     <a href="#tth_sEc3.2">3.2  Properties</a><br/>
127         <a href="#tth_sEc3.2.1">3.2.1  Property values</a><br/>
128         <a href="#tth_sEc3.2.2">3.2.2  Property identifiers</a><br/>
129         <a href="#tth_sEc3.2.3">3.2.3  Property descriptions</a><br/>
130
131
132         <a href="#tth_sEc3.2.4">3.2.4  Standard properties</a><br/>
133     <a href="#tth_sEc3.3">3.3  Capabilities</a><br/>
134         <a href="#tth_sEc3.3.1">3.3.1  Example use cases</a><br/>
135         <a href="#tth_sEc3.3.2">3.3.2  Capability identifiers</a><br/>
136         <a href="#tth_sEc3.3.3">3.3.3  Capability descriptions</a><br/>
137         <a href="#tth_sEc3.3.4">3.3.4  UI display name</a><br/>
138         <a href="#tth_sEc3.3.5">3.3.5  Standard capabilities</a><br/>
139     <a href="#tth_sEc3.4">3.4  Views</a><br/>
140         <a href="#tth_sEc3.4.1">3.4.1  Example use cases</a><br/>
141
142         <a href="#tth_sEc3.4.2">3.4.2  View identifiers</a><br/>
143         <a href="#tth_sEc3.4.3">3.4.3  View descriptions</a><br/>
144
145
146         <a href="#tth_sEc3.4.4">3.4.4  Default views</a><br/>
147
148
149         <a href="#tth_sEc3.4.5">3.4.5  Container views</a><br/>
150     <a href="#tth_sEc3.5">3.5  Protocols</a><br/>
151         <a href="#tth_sEc3.5.1">3.5.1  Protocol identifiers</a><br/>
152         <a href="#tth_sEc3.5.2">3.5.2  Protocol descriptions</a><br/>
153
154         <a href="#tth_sEc3.5.3">3.5.3  Standard protocols and authentication types</a><br/>
155         <a href="#tth_sEc3.5.4">3.5.4  Custom protocols</a><br/>
156
157
158     <a href="#tth_sEc3.6">3.6  Transfers</a><br/>
159         <a href="#tth_sEc3.6.1">3.6.1  Service-initiated transfers</a><br/>
160         <a href="#tth_sEc3.6.2">3.6.2  Client-initiated transfers</a><br/>
161     <a href="#tth_sEc3.7">3.7  Searches</a><br/>
162     <a href="#tth_sEc3.8">3.8  REST bindings</a><br/><a href="#tth_sEc4">4  Access Control</a><br/><a href="#tth_sEc5">5  Web service operations</a><br/>
163     <a href="#tth_sEc5.1">5.1  Service metadata</a><br/>
164         <a href="#tth_sEc5.1.1">5.1.1  getProtocols</a><br/>
165
166
167
168
169
170
171         <a href="#tth_sEc5.1.2">5.1.2  getViews</a><br/>
172
173
174
175
176
177
178         <a href="#tth_sEc5.1.3">5.1.3  getProperties</a><br/>
179
180
181
182
183
184
185     <a href="#tth_sEc5.2">5.2  Creating and manipulating data nodes</a><br/>
186         <a href="#tth_sEc5.2.1">5.2.1  createNode</a><br/>
187
188
189
190
191
192
193         <a href="#tth_sEc5.2.2">5.2.2  moveNode</a><br/><a href="#tth_sEcA">A  Changes from Previous Versions</a><br/><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
194
195 <h2>Acknowledgments</h2>
196 This document derives from discussions among the Grid and Web Services working group of the IVOA.
197
198 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
199 This document has been developed with support from the National Science Foundation's Information Technology Research Program under Cooperative Agreement AST0122449 with the John Hopkins University, from the UK Science and Technology Facilities Council (STFC), and from the European Commission's Sixth Framework Program via the Optical Infrared Coordination Network (OPTICON).
200
201 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
202
203 <h2>Conformance-related definitions</h2>
204 The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and
205 "OPTIONAL" (in upper or lower case) used in this document are to be
206 interpreted as described in IETF standard,
207
208 .
209
210 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
211 The <em>Virtual Observatory (VO)</em> is
212 general term for a collection of federated resources that can be used
213 to conduct astronomical research, education, and outreach.
214 The <a href="http://www.ivoa.net">International
215 Virtual Observatory Alliance (IVOA)</a> is a global
216 collaboration of separately funded projects to develop standards and
217 infrastructure that enable VO applications.
218
219 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
220 <a id="tth_sEc1"/><h2>
221 1  Introduction</h2>
222 VOSpace is the IVOA interface to distributed storage. It specifies how VO agents and applications can use network attached data stores to persist and exchange data in a standard way.
223
224 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
225 A VOSpace web service is an access point for a distributed storage network. Through this access point, a client can:
226
227 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
228 add or delete data objects
229 manipulate metadata for the data objects
230 obtain URIs through which the content of the data objects can be accessed
231 VOSpace does not define how the data is stored or transferred, only the control messages to gain access. Thus, the VOSpace interface can readily be added to an existing storage system.
232
233 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
234 When we speak of ä VOSpace", we mean the arrangement of data accessible through one particular VOSpace service.
235
236 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
237 Each data object within a VOSpace service is represented as a node and has a description called a representation. A useful analogy to have in mind when reading this document is that a node is equivalent to a file.
238
239 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
240 Nodes in VOSpace have unique identifiers expressed as URIs in the 'vos' scheme, as defined below.
241
242 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
243 VOSpace 2.0 did not introduce any new functionality to that already offered by prior (SOAP-based) versions of the interface (VOSpace 1.1) but defines a RESTful binding for the interface. VOSpace 2.1 introduces minor functional changes to VOSpace 2.0 addressing access control and optimizations.
244
245 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
246 <a id="tth_sEc1.1"/><h3>
247 1.1  Typical use of a VOSpace service</h3>
248 A typical use case for VOSpace is uploading a local data file to a remote VOSpace service. This is a two-stage process: creating a description of the data file (representation) in the VOSpace including any metadata (its properties) that they want to associate with it (e.g., MIME type), and defining the transfer operation that will actually see the data file bytes uploaded to the VOSpace service. The order of the processes should not matter. The user may want to create the representation first and then perform the transfer or transfer the bytes first and then update the representation with the appropriate metadata.
249
250 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
251 Let's consider the first sequence: the user provides a XML description of the data file which they HTTP PUT to the appropriate VOSpace URI - this will be the HTTP identifier for the data file in the VOSpace, e.g. http://nvo.caltech.edu/vospace/nodes/mytable1. The description will resemble this:
252
253 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
254 <pre>
255
256 print "Hello, World"
257 again
258 </pre>
259
260 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
261
262 <pre>
263 &lt;node xmlns="http://www.ivoa.net/xml/VOSpaceTypes-v2.1"
264     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
265     uri="vos://nvo.caltech!vospace/mytable1"
266     xsi:type="vost:UnstructuredDataNode"&gt;  
267     &lt;properties&gt; 
268         &lt;property uri="ivo://ivoa.net/vospace/core\#mimetype"&gt;text/xml&lt;/property&gt;     
269     &lt;/properties&gt; 
270 &lt;/node&gt; 
271
272 </pre>
273
274 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
275 The service will reply with an amended version of the representation containing service-specific details in addition to the information supplied by the user. These will include data formats that the service can handle for the type of node created in the VOSpace, third-party interfaces (capabilities) to the data that the service offers and system metadata.
276
277 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
278 The user will then describe the data format (the view) they want to use in uploading the file, e.g. VOTable, and the transport protocol (the protocol) that they want to employ to upload the file, e.g. HTTP PUT. This will result in the HTTP POSTing of a XML description of the transfer request to the appropriate VOSpace URI, e.g. http://nvo.caltech.edu/vospace/myData/table123/transfers. The description will resemble this:
279
280 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
281
282 <pre>
283 &lt;transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1"&gt;
284     &lt;target&gt;vos://nvo.caltech!vospace/mytable1&lt;/target&gt;
285     &lt;direction&gt;pushToVoSpace&lt;/direction&gt; 
286     &lt;view uri="ivo://ivoa.net/vospace/core#votable"/&gt; 
287     &lt;protocol uri="ivo://ivoa.net/vospace/core#http-put"/&gt;  
288 &lt;/transfer&gt;
289
290 </pre>
291
292 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
293 will then use a regular HTTP client to transfer (PUT) the local file to the specified endpoint. This illustrates an important point about VOSpace - it is only concerned with the server-side management of data storage and transfer. A client negotiates the details of a data transfer with a VOSpace service but the actual transfer of bytes across a network is handled by other tools.
294
295 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
296 Similarly, when a user wants to retrieve a data file from a VOSpace service, they will specify the data format (view) they want to use in downloading the file, e.g. VOTable, and the transport protocol (the protocol) that they want to employ to download the file, e.g. HTTP GET, and HTTP POST a XML description of this transfer request to the appropriate VOSpace URI - the transfer URI for the node in the VOSpace, e.g. http://nvo.caltech.edu/vospace/myDataNode/table123/transfers. The description will resemble this:
297
298 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
299
300 <pre>
301 &lt;transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1"&gt;
302     &lt;target&gt;vos://nvo.caltech!vospace/mytable1&lt;/target&gt;
303     &lt;direction&gt;pullFromVoSpace&lt;/direction&gt; 
304     &lt;view uri="ivo://ivoa.net/vospace/core#votable"/&gt; 
305     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/&gt;  
306 &lt;/transfer&gt;
307
308 </pre>
309
310 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
311 The service will reply with the URL for the user to use, e.g. http://nvo.caltech.edu/vospace/myDataNode/table123/transfers/3df89ab4. The user can then download the data file by pointing an HTTP client (e.g. web browser) at the specified endpoint.
312
313 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
314 <a id="tth_sEc1.2"/><h3>
315 1.2  Role within the VO Architecture</h3>
316
317 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
318 The IVOA Architecture [Arch] provides a high-level view of how IVOA standards work together to connect users and applications with providers of data and services, as depicted in the diagram in Figure  <a href="#fig:archdiag">1</a>.
319
320 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
321
322 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
323 <a id="tth_fIg1">
324 </a> <div style="text-align:center">
325 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
326 <img src="archdiag.png" alt="archdiag.png"/><div style="text-align:center">Figure 1: VOSpace in the IVOA Architecture. This provides an interface to distributed storage. It specifies how applications can use networked data stores to persist and exchange data in a standardized fashion.</div>
327 <a id="fig:archdiag">
328 </a>
329 </div>
330 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
331 In this architecture, users employ a variety of tools (from the User Layer) to discover and access archives and services of interest (represented in the Resource Layer). VOSpace provides an interface to storage resources containing the results of using these archives and services and also to other storage solutions, e.g., local disks, where users might want to transfer these results for further work. Items in these resources are referenced by a VOSpace identifier which is related to the standard IVOA Resource Identifier (see section 2). This version of VOSpace employs the UWS design pattern [UWS] to manage data transfers (see section 3.6) and searches (see section 3.7). VOSpace instances may also employ the IVOA Single-Sign-On standard [SSO] for authentication purposes (see section 4) and IVOA Credential Delegation Protocol [CDP] to delegate data transfers.
332
333 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
334 <a id="tth_sEc1.3"/><h3>
335 1.3  Document roadmap</h3>
336 The rest of this document is structured as follows:
337
338 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
339 In Section 2 (TODO: link these section references), we specify the URI syntax for identifying data objects (nodes) in VOSpace.
340
341 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
342 In Section 3, we present the data model that underpins the VOSpace architecture. This consists of a number of data structures, which have XML representations that are used across the wire in message exchanges with a VOSpace service. These structures represent:
343
344 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
345 the data objects themselves (nodes)
346 metadata that can be associated with a data object (properties)
347 third-party interfaces to the data (capabilities)
348 the data format used when transferring data objects across the wire (views)
349 the transport protocol employed in a data transfer (protocols)
350 the data transfer itself (transfers)
351 searches of data objects (searches)
352 We also describe the REST bindings between these representations and their URIs (HTTP identifiers).
353
354 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
355 In Section 4, we outline how security and access control policies are currently handled in VOSpace.
356
357 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
358 In Section 5, we detail the operations that the VOSpace interface supports. These handle access to service-level metadata, the creation and manipulation of nodes within the VOSpace, access to node metadata (properties) and data transfer to and from the VOSpace.
359
360 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
361 In Appendix A, we formally define the VOSpace interface with a machine readable description of its requests and responses and in Appendix B, we present a compliance matrix listing the mandatory behaviour required of a valid VOSpace 2.1 service.
362
363 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
364 <a id="tth_sEc2"/><h2>
365 2  VOSpace identifiers</h2>
366 The identifier for a node in VOSpace SHALL be a URI with the scheme vos.
367
368 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
369 Such a URI SHALL have the following parts with the meanings and encoding rules defined in RFC2396 [TODO].
370
371 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
372
373 <ul><li> scheme
374 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
375 </li>
376
377 <li> naming authority
378 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
379 </li>
380
381 <li> path
382 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
383 </li>
384
385 <li> (optional) query
386 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
387 </li>
388
389 <li> (optional) fragment identifier (with the expected semantics [TODO])
390 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
391 </li>
392 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
393 The naming authority for a VOSpace node SHALL be the VOSpace service through which the node was created. The authority part of the URI SHALL be constructed from the IVO registry identifier [IVORN] for that service by deleting the ivo:// prefix and changing all forward-slash characters('/') in the resource key to exclamation marks ('!') or tildes (' '). Note that a service SHALL be consistent in its use of separator characters ('!' or ' ') when referring to its own data but SHALL accept either as valid in URIs in service requests. For the rest of the document, we shall use '!' as the default character.
394
395 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
396 This is an example of a possible VOSpace identifier.
397
398 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
399
400 <pre>
401 vos://nvo.caltech!vospace/myresults/siap-out-1.vot
402
403 </pre>
404
405 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
406 The URI scheme is <em>vos</em>
407
408 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
409 Using a separate URI scheme for VOSpace identifiers enables clients to distinguish between IVO registry identifiers and VOSpace identifiers.
410
411 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
412
413 <ul><li> nvo.caltech!vospace
414 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
415 </li>
416 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
417 is the authority part of the URI, corresponding to the IVO registry identifier
418
419 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
420
421 <ul><li> ivo://nvo.caltech/vospace
422 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
423 </li>
424 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
425 This is the IVO registry identifier of the VOSpace service that contains the node.
426
427 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
428
429 <ul><li> /siap-out-1.vot is the URI path
430 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
431 </li>
432 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
433 Slashes in the URI path imply a hierarchical arrangement of data: the data object identified by vos://nvo.caltech!vospace/myresults/siap-out-1.vot is within the container identified by vos://nvo.caltech!vospace/myresults.
434
435 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
436 Literal space characters are also not allowed in URIs.
437
438 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
439 All ancestors in the hierarchy SHALL be resolvable as containers (ContainerNodes), all the way up to the root node of the space (this precludes any system of implied hierarchy in the naming scheme for nodes with ancestors that are just logical entities and cannot be reified, e.g. the Amazon S3 system).
440
441 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
442 A VOSpace identifier is globally unique, and identifies one specific node in a specific VOSpace service.
443
444 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
445 The standardID for this specification SHALL be: ivo://ivoa.net/std/VOSpace/v2.1.
446
447 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
448 <a id="tth_sEc2.1"/><h3>
449 2.1  Identifier resolution</h3>
450 A VOSpace identifier can be resolved to a HTTP endpoint for accessing representations of the node associated with it. A client SHOULD use the following procedure to resolve access to a VOSpace node from a VOSpace identifier:
451
452 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
453
454 <ul><li> Resolve HTTP service endpoint of VOSpace service with registry
455 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
456 </li>
457
458 <li> Append "nodes/" and the path following the naming authority part of the VOSpace identifier to the service endpoint
459 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
460 </li>
461 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
462 Given the example identifier
463
464 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
465
466 <pre>
467     vos://org.astrogrid.cam!vospace/container-6/siap-out-1.vot?foo=bar
468
469 </pre>
470
471 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
472 processing the URI to resolve the VOSpace service would involve :
473
474 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
475
476 <ol type="1"><li> Extract the IVO registry identifier of the VOSpace service by prepending an ivo scheme to the naming authority part:
477
478 <pre>
479             ivo://org.astrogrid.cam/vospace
480         
481 </pre>
482 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
483 </li>
484
485 <li> Resolve the IVO identifier in a registry and retrieve the access URL of the service endpoint:
486
487 <pre>
488             http://some.uni.ac.uk/vospace
489         
490 </pre>
491 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
492 </li>
493
494 <li> Append "nodes/" and the path part of the VOSpace identifier:
495
496 <pre>
497             http://some.uni.ac.uk/vospace/nodes/container-6/siap-out-1.vot?foo=bar
498         
499 </pre>
500 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
501 </li>
502 </ol><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
503 Note that any fragment identifier in the identifier SHOULD be removed when resolving the identifier to a HTTP endpoint, consistent with the implied semantics of URI fragments [TODO].
504
505 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
506 <a id="tth_sEc3"/><h2>
507 3  VOSpace data model</h2>
508
509 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
510 <a id="tth_sEc3.1"/><h3>
511 3.1  Nodes and node types</h3>
512
513 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
514 We refer to the arrangement of data accessible through one particular VOSpace service as ä VOSpace".
515
516 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
517 Each data object within a VOSpace SHALL be represented as a node that is identified by a URI.
518
519 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
520 There are different types of nodes and the type of a VOSpace node determines how the VOSpace service stores and interprets the node data.
521
522 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
523 The types are arranged in a hierarchy (see Figure  <a href="#fig:nodehierarchy">2</a>), with more detailed types inheriting the structure of more generic types.
524
525 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
526
527 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
528 <a id="tth_fIg2">
529 </a> <div style="text-align:center"><img src="vospace-node-hierarchy.png" alt="vospace-node-hierarchy.png"/><div style="text-align:center">Figure 2: Node hierarchy - This shows the inheritance structure for the different types of nodes in VOSpace.</div>
530 <a id="fig:nodehierarchy">
531 </a>
532 </div>
533 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
534 The following types (and representations) are defined:
535
536 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
537
538 <ul><li> Node is the most basic type
539 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
540 </li>
541
542 <li> ContainerNode describes a data item that can contain other data items
543 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
544 </li>
545
546 <li> DataNode describes a data item stored in the VOSpace
547 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
548 </li>
549
550 <li> UnstructuredDataNode describes a data item for which the VOSpace does not understand the data format
551 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
552 </li>
553
554 <li> StructuredDataNode describes a data item for which the space understands the format and may make transformations that preserve the meaning of the data.
555 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
556 </li>
557
558 <li> LinkNode describes a node that points to another node.
559 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
560 </li>
561 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
562 When data is stored and retrieved from an <em>UnstructuredDataNode</em>, the bit pattern read back SHALL be identical to that written.
563
564 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
565 When data is stored and retrieved from a <em>StructuredDataNode</em>, the bit pattern returned MAY be different to the original. For example, storing tabular data from a VOTable file will preserve the tabular data, but any comments in the original XML file may be lost.
566
567 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
568 A Node representation SHALL have the following elements:
569
570 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
571
572 <ul><li> <em>uri</em>: the vos:// identifier for the node, URI-encoded according to RFC2396 [TODO]
573 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
574 </li>
575
576 <li> <em>properties</em>: a set of metadata properties for the node
577 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
578 </li>
579
580 <li> <em>capabilities</em>: a third-party interface to a data object
581 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
582 </li>
583 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
584 In addition, a <em>DataNode</em> representation SHALL have the following elements:
585
586 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
587
588 <ul><li> <em>accepts</em>: a list of the views (data formats) that the node can accept
589 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
590 </li>
591
592 <li> <em>provides</em>: a list of the views (data formats) that the node can provide
593 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
594 </li>
595
596 <li> <em>busy</em>: a boolean flag to indicate that the data associated with the node cannot be accessed
597 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
598 </li>
599 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
600 The <em>busy</em> flag is used to indicate that an internal operation is in progress, and the node data is not available.
601
602 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
603 A <em>ContainerNode</em> representation SHALL have the following elements, in addition to those it inherits from the <em>Node</em> representation:
604
605 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
606
607 <ul><li> <em>nodes</em>: a list of the direct children, if applicable, that the container has. Each child is represented as a node subelement containing its vos:// identifier, URI-encoded according to RFC2396 [TODO]
608 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
609 </li>
610 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
611 A <em>LinkNode</em> representation SHALL have the following elements, in addition to those it inherits from the Node representation:
612
613 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
614
615 <ul><li> <em>target</em>: the target URI, URI-encoded according to RFC2396 [TODO]
616 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
617 </li>
618 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
619 The link target can be a URI that points to any type of resource, including other VOSpace Nodes (within the same VOSpace service or in another service), or external resources outside VOSpace altogether.
620
621 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
622 The properties of a <em>LinkNode</em> do not propagate to the target of the <em>LinkNode</em>, i.e., a property attached to a LinkNode does not also get attached to the target node. One use case is to enable third-party annotations to be associated with a resource but without the resource itself getting cluttered with unnecessary metadata. In this case, the client creates a <em>LinkNode</em> pointing to the resource in question and then adds the annotations as properties of the <em>LinkNode</em>.
623
624 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
625 Both the <em>ContainerNode</em> and the <em>LinkNode</em> SHALL have no data bytes associated with them.
626
627 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
628 The set of node types defined by this standard is closed; new types may be introduced only via new versions of the standard.
629
630 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
631 To comply with the standard, a client or service SHALL be able to parse XML representations of all the node types defined in the current specification.
632
633 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
634 Note: This does not require all services to support all of the Node types, just that it can process an XML request containing any of the types. If the service receives a request for a type that it does not support, the service SHOULD return a <em>TypeNotSupported</em> fault. The service SHALL NOT throw an XML parser error if it receives a request for a type that it does not support.
635
636 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
637 <a id="tth_sEc3.2"/><h3>
638 3.2  Properties</h3>
639 <em>Properties</em> are simple string-based metadata properties associated with a node.
640
641 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
642 Individual <em>Properties</em> should contain simple short string values, not large blocks of information. If a system needs to attach a large amount of metadata to a node, then it should either use multiple small <em>Properties</em>, or a single <em>Property</em> containing a URI or URL pointing to an external resource that contains the additional metadata.
643
644 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
645 A <em>Property</em> representation SHALL have the following elements:
646
647 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
648
649 <ul><li> <em>uri</em>: the Property identifier
650 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
651 </li>
652
653 <li> <em>value</em>: the string value of the Property
654 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
655 </li>
656
657 <li> <em>readOnly</em>: a boolean flag to indicate that the Property cannot be changed by the client
658 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
659 </li>
660 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
661 Properties may be set by the client or the service.
662
663 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
664 <a id="tth_sEc3.2.1"/><h4>
665 3.2.1  Property values</h4>
666 Unless they have special meaning to the service or client, Properties are treated as simple string values.
667
668 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
669 When a <em>Property</em> can take multiple values, e.g., a list of groups which can access a particular resource, these SHOULD be comma-separated, unless the property description defines a specific delimiter.
670
671 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
672 Some <em>Properties</em> may have meaning to the service; others may have meaning only to one specific type of client. A service implementation does not need to understand the meaning of all the <em>Properties</em> of a node. Any Properties that it does not understand can simply be stored as text strings.
673
674 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
675 <a id="tth_sEc3.2.2"/><h4>
676 3.2.2  Property identifiers</h4>
677 Every new type of <em>Property</em> SHALL require a unique URI to identify the <em>Property</em> and its meaning.
678
679 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
680 The rules for the <em>Property</em> identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
681
682 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
683
684 <ul><li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my?namespace
685 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
686 </li>
687
688 <li> Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema or a resource describing it
689 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
690 </li>
691 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
692 The current VOSpace schema defines <em>Property</em> identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
693
694 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
695
696 <ul><li> A <em>Property</em> URI can be a simple URN, e.g. urn:my?property
697 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
698 </li>
699 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
700 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
701
702 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
703 For a production system, any new Properties SHOULD have unique URIs that can be resolved into to a description of the Property.
704
705 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
706 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
707
708 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
709
710 <ul><li> ivo://my?registry/vospace/properties#my?property
711 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
712 </li>
713 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
714 Using an IVO registry URI to identify Properties has two main advantages:
715
716 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
717
718 <ul><li> IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
719 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
720 </li>
721
722 <li> If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover what the Property means
723 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
724 </li>
725 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
726 <a id="tth_sEc3.2.3"/><h4>
727 3.2.3  Property descriptions</h4>
728 If the URI for a particular Property is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the Property.
729
730 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
731 A Property description SHOULD describe the data type and meaning of a Property.
732
733 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
734 A PropertyDescription SHOULD have the following members:
735
736 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
737
738 <ul><li> <em>uri</em>: the formal URI of the Property
739 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
740 </li>
741
742 <li> <em>DisplayName</em>: A display name for the Property
743 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
744 </li>
745
746 <li> <em>Description</em>: A text block describing the meaning and validation rules of the Property
747 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
748 </li>
749 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
750 A PropertyDescription MAY have the following OPTIONAL members:
751
752 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
753
754 <ul><li> <em>UCD</em>: the Universal Content Descriptor (in the UCD1+ scheme) for the Property
755 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
756 </li>
757
758 <li> <em>Unit</em>: the unit of measurement of the Property
759 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
760 </li>
761 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
762 The information in a Property description can be used to generate a UI for displaying and modifying the different types of Properties.
763
764 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
765 Note that at the time of writing, the schema for registering PropertyDescriptions in the IVO registry has not been finalized.
766
767 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
768
769 <b>UI Display name  </b>
770 If a client is unable to resolve a Property identifier into a description, then it may just display the identifier as a text string:
771
772 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
773
774 <ul><li> urn:modifieddate
775 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
776 </li>
777 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
778 If the client can resolve the Property identifier into a description, then the client may use the information in the description to display a human readable name and description of the Property:
779
780 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
781
782 <ul><li> Last modification date of the node data
783 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
784 </li>
785 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
786
787 <b>Property editors  </b>
788 If the client is unable to resolve a Property identifier into a description, or does not understand the type information defined in the description, then the client MAY treat the Property value as a simple text string.
789
790 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
791 If the client can resolve the Property identifier into a description, then the client MAY use the information in the description to display an appropriate editing tool for the Property.
792
793 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
794 In the current version of the specification the rules for editing Properties are as follows:
795
796 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
797
798 <ul><li> A service MAY impose validation rules on the values of specific types of Properties
799 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
800 </li>
801
802 <li> If a client attempts to set a Property to an invalid value, then the service MAY reject the change
803 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
804 </li>
805
806 <li> Where possible, the validation rules for a type of Property SHOULD be defined in the Property description
807 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
808 </li>
809 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
810 Future versions of the VOSpace specification may extend the PropertyDescription to include more specific machine readable validation rules for a Property type.
811
812 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
813 Note that at the time of writing, the schema for registering validation rules in PropertyDescriptions has not been finalized.
814
815 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
816 <a id="tth_sEc3.2.4"/><h4>
817 3.2.4  Standard properties</h4>
818 Property URIs and PropertyDescriptions for the core set of Properties are registered under a StandardKeyEnumeration resource [VOStd] in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. The following URIs SHOULD be used to represent the service properties:
819
820 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
821
822 <ul><li> ivo://ivoa.net/vospace/core#title SHALL be used as the property URI denoting a name given to the resource
823 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
824 </li>
825
826 <li> ivo://ivoa.net/vospace/core#creator SHALL be used as the property URI denoting an entity primarily responsible for making the resource
827 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
828 </li>
829
830 <li> ivo://ivoa.net/vospace/core#subject SHALL be used as the property URI denoting the topic of the resource
831 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
832 </li>
833
834 <li> ivo://ivoa.net/vospace/core#description SHALL be used as the property URI denoting an account of the resource
835 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
836 </li>
837
838 <li> ivo://ivoa.net/vospace/core#publisher SHALL be used as the property URI denoting an entity responsible for making the resource available
839 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
840 </li>
841
842 <li> ivo://ivoa.net/vospace/core#contributor SHALL be used as the property URI denoting an entity responsible for making contributions to this resource
843 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
844 </li>
845
846 <li> ivo://ivoa.net/vospace/core#date SHALL be used as the property URI denoting a point or period of time associated with an event in the lifecycle of the resource
847 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
848 </li>
849
850 <li> ivo://ivoa.net/vospace/core#type SHALL be used as the property URI denoting the nature or genre of the resource
851 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
852 </li>
853
854 <li> ivo://ivoa.net/vospace/core#format SHALL be used as the property URI denoting the file format, physical medium, or dimensions of the resource
855 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
856 </li>
857
858 <li> ivo://ivoa.net/vospace/core#identifier SHALL be used as the property URI denoting an unambiguous reference to the resource within a given context
859 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
860 </li>
861
862 <li> ivo://ivoa.net/vospace/core#source SHALL be used as the property URI denoting a related resource from which the described resource is derived
863 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
864 </li>
865
866 <li> ivo://ivoa.net/vospace/core#language SHALL be used as the property URI denoting a language of the resource
867 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
868 </li>
869
870 <li> ivo://ivoa.net/vospace/core#relation SHALL be used as the property URI denoting a related resource
871 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
872 </li>
873
874 <li> ivo://ivoa.net/vospace/core#coverage SHALL be used as the property URI denoting the spatial or temporal topic of the resource, the spatial applicability of the resource, or the jurisdiction under which the resource is relevant
875 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
876 </li>
877
878 <li> ivo://ivoa.net/vospace/core#rights SHALL be used as the property URI denoting information about rights held in and over the resource
879 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
880 </li>
881
882 <li> ivo://ivoa.net/vospace/core#availableSpace SHALL be used as the property URI denoting the amount of space available within a container
883 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
884 </li>
885
886 <li> ivo://ivoa.net/vospace/core#groupread SHALL be used as the property URI denoting the list of groups which can only read this resource (read-only)
887 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
888 </li>
889
890 <li> ivo://ivoa.net/vospace/core#groupwrite SHALL be used as the property URI denoting the list of groups which can read and write to this resource (read-write)
891 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
892 </li>
893
894 <li> ivo://ivoa.net/vospace/core#publicread SHALL be used as the property URI denoting whether this resource is world readable (anon-read-only)
895 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
896 </li>
897
898 <li> ivo://ivoa.net/vospace/core#quota SHALL be used as the property URI denoting the value of a system quota on the resource
899 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
900 </li>
901
902 <li> ivo://ivoa.net/vospace/core#length SHALL be used as the property URI denoting the length or size of a resource
903 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
904 </li>
905
906 <li> ivo://ivoa.net/vospace/core#mtime SHALL be used as the property URI denoting the data modification time
907 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
908 </li>
909
910 <li> ivo://ivoa.net/vospace/core#ctime SHALL be used as the property URI denoting status change (aka metadata modification) time
911 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
912 </li>
913
914 <li> ivo://ivoa.net/vospace/core#btime SHALL be used as the property URI denoting initial creation time
915 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
916 </li>
917 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
918 However, this is not intended to be a closed list, different implementations are free to define and use their own Properties.
919
920 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
921 <a id="tth_sEc3.3"/><h3>
922 3.3  Capabilities</h3>
923 A Capability describes a third-party interface to a node. One application of this would be to enable data access to a node or its contents using a 3rd party service interface.
924
925 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
926 A Capability representation SHALL have the following members:
927
928 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
929
930 <ul><li> <em>uri</em>: the Capability identifier
931 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
932 </li>
933
934 <li> <em>endpoint</em>: the endpoint URL to use for the third-party interface
935 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
936 </li>
937
938 <li> <em>param</em>: a set of parameters for the capability
939 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
940 </li>
941 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
942 <a id="tth_sEc3.3.1"/><h4>
943 3.3.1  Example use cases</h4>
944 A ContainerNode containing image files may offer a DAL SIAP capability so that the images in the container can be accessed using a SIAP service. In this way, a user could create a (DAL enabled) Container in VOSpace, transfer some images into it and then query the set of images using the SIAP interface.
945
946 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
947 Another example is a DataNode that provides an iRODS capability so that the data replication for this data object can be handled using the iRODS service API.
948
949 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
950 <a id="tth_sEc3.3.2"/><h4>
951 3.3.2  Capability identifiers</h4>
952 Every new type of Capability SHALL require a unique URI to identify the Capability. The rules for the Capability identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
953
954 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
955
956 <ul><li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my-namespace
957 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
958 </li>
959
960 <li> Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it.
961 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
962 </li>
963 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
964 The VOSpace schema defines Capability identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
965
966 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
967
968 <ul><li> A Capability URI can be a simple URN, e.g. urn:my-capability
969 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
970 </li>
971 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
972 This may be sufficient for testing and development on a private system, but it is not suitable for use on a public service. For a production system, any new Capabilities SHOULD have unique URIs that can be resolved into a description of the Capability. Ideally, these SHOULD be IVO registry URIs that point to a description registered in the IVO registry:
973
974 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
975
976 <ul><li> ivo://my-registry/vospace/capabilities#my-capability
977 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
978 </li>
979 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
980 Using an IVO registry URI to identify Capabilities has two main advantages:
981
982 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
983
984 <ul><li> IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
985 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
986 </li>
987
988 <li> If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover how to use the Capability.
989 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
990 </li>
991 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
992 <a id="tth_sEc3.3.3"/><h4>
993 3.3.3  Capability descriptions</h4>
994 If the URI for a particular Capability is resolvable, i.e. an IVO registry identifier or a HTTP URL then it SHOULD point to an XML resource that describes the Capability.
995
996 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
997 A CapabilityDescription SHOULD describe the third-party interface and how it should be used in this context. A CapabilityDescription SHOULD have the following members:
998
999 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1000
1001 <ul><li> <em>uri</em>: the formal URI of the Capability
1002 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1003 </li>
1004
1005 <li> <em>DisplayName</em>: a simple display name of the Capability.
1006 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1007 </li>
1008
1009 <li> <em>Description</em>: a text block describing the third-party interface and how it should be used in this context.
1010 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1011 </li>
1012 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1013 Note that at the time of writing, the schema for registering CapabilityDescriptions in the IVO registry has not been finalized.
1014
1015 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1016 <a id="tth_sEc3.3.4"/><h4>
1017 3.3.4  UI display name</h4>
1018 If a client is unable to resolve a Capability identifier into a description then it may just display the identifier as a text string:
1019
1020 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1021
1022 <ul><li> Access data using urn:edu.sdsc.irods
1023 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1024 </li>
1025 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1026 If a client can resolve the Capability identifier into a description then the client may use the information in the description to display a human readable name and description of the Capability:
1027
1028 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1029
1030 <ul><li> Access data using iRODS
1031 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1032 </li>
1033 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1034 <a id="tth_sEc3.3.5"/><h4>
1035 3.3.5  Standard capabilities</h4>
1036 Capability URIs and CapabilityDescriptions for the core set of Capabilities are registered under a StandardKeyEnumeration resource [VOStd] in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core.. The following URIs SHALL be used to represent the service capabilities:
1037
1038 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1039
1040 <ul><li> ivo://ivoa.net/vospace/core#vospace-1.0 SHALL be used as the capability URI for a VOSpace 1.0 service
1041 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1042 </li>
1043
1044 <li> ivo://ivoa.net/vospace/core#vospace-1.1 SHALL be used as the capability URI for a VOSpace 1.1 service
1045 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1046 </li>
1047
1048 <li> ivo://ivoa.net/vospace/core#vospace-2.0 SHALL be used as the capability URI for a VOSpace 2.0 service
1049 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1050 </li>
1051 </ul>
1052 If a service implementation supports more than one version of the VOSpace interface then these capability URIs can be used with a VOSpace service to identify different VOSpace capabilities for a node.
1053
1054 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1055 One use case for this would be a VOSpace 1.1 client talking to a service that implements both VOSpace 1.0 and VOSpace 1.1, where the client is acting on behalf of a third party agent that only understands VOSpace 1.0. In this case, the client can use the information in the VOSpace 1.0 capability to direct the third party agent to the VOSpace 1.0 endpoint.
1056
1057 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1058 Other standard service interfaces will also be registered, e.g.
1059
1060 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1061
1062 <ul><li> Cone Search
1063 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1064 </li>
1065
1066 <li> SIAP
1067 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1068 </li>
1069
1070 <li> SSAP
1071 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1072 </li>
1073
1074 <li> TAP
1075 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1076 </li>
1077 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1078 However, this is not intended to be a closed list and different implementations are free to define and use their own Capabilities.
1079
1080 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1081 <a id="tth_sEc3.4"/><h3>
1082 3.4  Views</h3>
1083 A View describes the data formats and contents available for importing or exporting data to or from a VOSpace node.
1084
1085 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1086 The metadata for a DataNode contains two lists of Views.
1087
1088 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1089
1090 <ul><li> <em>accepts</em>: is a list of Views that the service can accept for importing data into the Node
1091 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1092 </li>
1093
1094 <li> <em>provides</em>: is a list of Views that the service can provide for exporting data from Node
1095 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1096 </li>
1097 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1098 A View representation SHALL have the following members:
1099
1100 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1101
1102 <ul><li> <em>uri</em>: an optional boolean flag to indicate that the View preserves the original bit pattern of the data
1103 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1104 </li>
1105
1106 <li> <em>original</em>: a set of name-value pairs that can be used to specify additional arguments for the View
1107 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1108 </li>
1109 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1110 <a id="tth_sEc3.4.1"/><h4>
1111 3.4.1  Example use cases</h4>
1112 A simple VOSpace system that stores data as a binary files can just return the contents of the original file. The client supplies a View identifier when it imports the data, and the service uses this information to describe the data to other clients.
1113
1114 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1115 A file based system can use the special case identifier 'ivo://ivoa.net/vospace/core#view?any' to indicate that it will accept any data format or View for a Node.
1116
1117 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1118 For example:
1119
1120 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1121
1122 <ul><li> A client imports a file into the service, specifying a View to describe the file contents
1123 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1124 </li>
1125
1126 <li> The service stores the data as a binary file and keeps a record of the View
1127 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1128 </li>
1129
1130 <li> The service can then use the View supplied by the client to describe the data to other clients
1131 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1132 </li>
1133 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1134 This type of service is not required to understand the imported data, or to verify that it contents match the View, it treats all data as binary files.
1135
1136 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1137
1138 <b>Database store  </b>
1139 A VOSpace system that stores data in database tables would need to be able to understand the data format of an imported file in order to parse the data and store it correctly. This means that the service can only accept a specific set of Views, or data formats, for importing data into the Node.
1140
1141 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1142 In order to tell the client what input data formats it can accept, the service publishes a list of specific Views in the accepts list for each Node.
1143
1144 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1145 On the output side, a database system would not be able to provide access to the original input file. The contents of file would have been transferred into the database table and then discarded. The system has to generate the output results from the contents of the database table.
1146
1147 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1148 In order to support this, the service needs to be able to tell the client what Views of the data are available.
1149
1150 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1151 A database system may offer access to the table contents as either VOTable or FITS files, it may also offer zip or tar.gz compressed versions of these. In which case the system needs to be able to express nested file formats such as 'zip containing VOTable' and 'tar.gz containing FITS'.
1152
1153 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1154 A service may also offer subsets of the data. For example, a work flow system may only want to look at the table headers to decide what steps are required to process the data. If the table contains a large quantity of data, then downloading the whole contents just to look at the header information is inefficient. To make this easier, a database system may offer a 'metadata only' View of the table, returning a VOTable or FITS file containing just the metadata headers and no rows.
1155
1156 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1157 So our example service may want to offer the following Views of a database table:
1158
1159 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1160
1161 <ul><li> Table contents as FITS
1162 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1163 </li>
1164
1165 <li> Table contents as VOTable
1166 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1167 </li>
1168
1169 <li> Table contents as zip containing FITS
1170 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1171 </li>
1172
1173 <li> Table contents as zip containing VOTable
1174 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1175 </li>
1176
1177 <li> Table contents as tar.gz containing FITS
1178 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1179 </li>
1180
1181 <li> Table contents as tar.gz containing VOTable
1182 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1183 </li>
1184
1185 <li> Table metadata as FITS
1186 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1187 </li>
1188
1189 <li> Table metadata as VOTable
1190 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1191 </li>
1192 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1193 The service would publish this information as a list of Views in the provides section of the metadata for each Node.
1194
1195 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1196 The VOSpace specification does not mandate what Views a service must provide. The VOSpace specification is intended to provide a flexible mechanism enabling services to describe a variety of different Views of data. It is up to the service implementation to decide what Views of the data it can accept and provide.
1197
1198 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1199 <a id="tth_sEc3.4.2"/><h4>
1200 3.4.2  View identifiers</h4>
1201 Every new type of View SHALL require a unique URI to identify the View and its content.
1202
1203 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1204 The rules for the View identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
1205
1206 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1207
1208 <ul><li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my?namespace
1209 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1210 </li>
1211
1212 <li> Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it
1213 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1214 </li>
1215 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1216 The current VOSpace schema defines View identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
1217
1218 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1219
1220 <ul><li> A View URI can be a simple URN, e.g. urn:my?view
1221 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1222 </li>
1223 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1224 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
1225
1226 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1227 For a production system, any new Views SHOULD have unique URIs that can be resolved into to a description of the View.
1228
1229 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1230 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
1231
1232 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1233
1234 <ul><li> ivo://my?registry/vospace/views#my?view
1235 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1236 </li>
1237 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1238 Using an IVO registry URI to identify Views has two main advantages:
1239
1240 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1241
1242 <ul><li> IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
1243 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1244 </li>
1245
1246 <li> If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover what the View contains
1247 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1248 </li>
1249 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1250 <a id="tth_sEc3.4.3"/><h4>
1251 3.4.3  View descriptions</h4>
1252 If the URI for a particular View is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the View.
1253
1254 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1255 A ViewDescription SHOULD describe the data format and/or content of the view.
1256
1257 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1258 A ViewDescription SHOULD have the following members :
1259
1260 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1261
1262 <ul><li> <em>uri</em>: the formal URI of the View
1263 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1264 </li>
1265
1266 <li> <em>DisplayName</em>: a simple display name of the View.
1267 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1268 </li>
1269
1270 <li> <em>Description</em>: a text block describing the data format and content of the View.
1271 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1272 </li>
1273 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1274 A ViewDescription MAY have the following optional members:
1275
1276 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1277
1278 <ul><li> <em>MimeType</em>: the standard MIME type of the View, if applicable
1279 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1280 </li>
1281
1282 <li> <em>Parameters</em>: a list of required and option parameters the view accepts, if applicable
1283 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1284 </li>
1285 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1286 However, at the time of writing, the schema for registering ViewDescriptions in the IVO registry has not been finalized.
1287
1288 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1289
1290 <b>UI Display name  </b>
1291 If a client is unable to resolve a View identifier into a description, then it MAY just display the identifier as a text string:
1292
1293 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1294
1295 <ul><li> Download as urn:table.meta.fits
1296 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1297 </li>
1298 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1299 If the client can resolve the View identifier into a description, then the client MAY use the information in the description to display a human readable name and description of the View:
1300
1301 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1302
1303 <ul><li> Download table metadata as FITS header
1304 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1305 </li>
1306 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1307
1308 <b>Mime Types  </b>
1309 If a VOSpace service provides HTTP access to the data contained in a Node, then if the ViewDescription contains a MimeType field, this SHOULD be included in the appropriate header field of the HTTP response.
1310
1311 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1312 <a id="tth_sEc3.4.4"/><h4>
1313 3.4.4  Default views</h4>
1314 The following standard URIs are registered under a StandardKeyEnumeration resource [VOStd] in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. They SHALL be used to refer to the default import and export views:
1315
1316 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1317
1318 <ul><li> ivo://ivoa.net/vospace/core#anyview SHALL be used as the view URI to indicate that a service will accept any view for an import operation
1319 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1320 </li>
1321
1322 <li> ivo://ivoa.net/vospace/core#binaryview SHALL be used as the view URI to import or export data as a binary file
1323 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1324 </li>
1325
1326 <li> ivo://ivoa.net/vospace/core#defaultview SHALL be used by a client to indicate that the service should choose the most appropriate view for a data export
1327 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1328 </li>
1329 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1330
1331 <b>Default import view  </b>
1332 If a client imports data using this view, the data SHALL be treated as a binary BLOB, and stored as is with no additional processing. This is equivalent to the application/binary MIME type.
1333
1334 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1335 Note, this view is OPTIONAL, and the service may throw a ViewNotSupported exception if it does not accept this view. In particular, this view cannot be used to import data into a StructuredDataNode as the service needs to know about and understand the data format to be able to create the StructuredDataNode.
1336
1337 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1338 Note, this view is only valid for the data import operations, pullToVoSpace and pushToVoSpace. If this view is requested in an export operation, pullFromVoSpace and pushToVoSpace, then the service SHOULD throw a ViewNotSupported exception.
1339
1340 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1341
1342 <b>Default export view  </b>
1343 If a client requests data using this view, the server SHALL choose whichever of the available views (the server) thinks is the most appropriate, based on how the data is stored. In a simple file-based system, this will probably be the same format that the data was originally imported in. In a database table system, this will probably either be VOTable or CVS, depending on the level of metadata available.
1344
1345 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1346 Note, this view is OPTIONAL, and the server may throw a ViewNotSupported exception if it does not provide this view. However, in most cases, it is expected that a service would be able to select an appropriate 'default' format for data held within the service.
1347
1348 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1349 Note, this view is only valid for the data export operations, pullFromVoSpace and pushFromVoSpace. If this view is requested in an import operation, pullToVoSpace and pushToVoSpace, then the service SHOULD throw a ViewNotSupported fault.
1350
1351 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1352 <a id="tth_sEc3.4.5"/><h4>
1353 3.4.5  Container views</h4>
1354 In VOSpace 2.1, a view of a ContainerNode describes the data representation (format) of a file or data stream that represents the combined contents of the node and its children. If the view describes an archive format (tar, zip, etc.) then a service that accepts this view (format) for a ContainerNode SHALL provide access to the archive contents as children nodes of the container. Whether or not the service actually unpacks the archive is implementation dependent but the service SHALL behave as though it has done so. For example, a client may want to upload a tar file containing several images to a VOSpace service. If they associate it with (upload it to) a (Un)structuredDataNode then it will be treated as a blob and its contents will be not be available. However, if they upload it to a ContainerNode with an accepts view of "tar" then the image files within the tar file will be represented as children nodes of the ContainerNode and accessible like any other data object within the space.
1355
1356 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1357 If a service provides an archive format (tar, zip, etc.) view of a ContainerNode then the service SHALL package the contents of the container and all its child nodes in the specified format.
1358
1359 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1360 <a id="tth_sEc3.5"/><h3>
1361 3.5  Protocols</h3>
1362 A Protocol describes the parameters required to perform a data transfer using a particular protocol.
1363
1364 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1365 A Protocol representation SHALL have the following members:
1366
1367 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1368
1369 <ul><li> <em>uri</em>: the Protocol identifier
1370 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1371 </li>
1372
1373 <li> <em>endpoint</em>: the endpoint URL to use for the data transfer additional arguments required for the transfer
1374 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1375 </li>
1376 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1377 A protocol representation MAY have the following members:
1378
1379 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1380
1381 <ul><li> <em>param</em>: A list of name-value pairs that specify any additional arguments requried for the transfer
1382 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1383 </li>
1384
1385 <li> <em>authType</em>: The requested type of authentication method to be used
1386 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1387 </li>
1388 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1389 Note: endpoint will only contain a value after the response from the service is received.
1390
1391 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1392 <a id="tth_sEc3.5.1"/><h4>
1393 3.5.1  Protocol identifiers</h4>
1394 Every new type of Protocol requires a unique URI to identify the Protocol and how to use it.
1395
1396 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1397 The rules for the Protocol identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI
1398
1399 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1400
1401 <ul><li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my?namespace
1402 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1403 </li>
1404
1405 <li> Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it
1406 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1407 </li>
1408 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1409 The current VOSpace schema defines Protocol identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
1410
1411 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1412
1413 <ul><li> A Protocol URI can be a simple URN, e.g. urn:my?protocol
1414 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1415 </li>
1416 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1417 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
1418
1419 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1420 For a production system, any new Protocols SHOULD have unique URIs that can be resolved into to a description of the Protocol.
1421
1422 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1423 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
1424
1425 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1426
1427 <ul><li>
1428 <pre>ivo://my?registry/vospace/protocols#my?protocol
1429 </pre>
1430 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1431 </li>
1432 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1433 Using an IVO registry URI to identify Protocols has two main advantages:
1434
1435 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1436
1437 <ul><li> IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
1438 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1439 </li>
1440
1441 <li> If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover how to use the Protocol
1442 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1443 </li>
1444 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1445 <a id="tth_sEc3.5.2"/><h4>
1446 3.5.2  Protocol descriptions</h4>
1447 If the URI for a particular Protocol is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the Protocol.
1448
1449 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1450 A ProtocolDescription SHOULD describe the underlying transport protocol, and how it should be used in this context.
1451
1452 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1453 A ProtocolDescription SHOULD have the following members:
1454
1455 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1456
1457 <ul><li> <em>uri</em>: the formal URI of the Protocol
1458 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1459 </li>
1460
1461 <li> <em>DisplayName</em>: A simple display name of the Protocol
1462 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1463 </li>
1464
1465 <li> <em>Description</em>: Text block describing describing the underlying transport protocol, and how it should be used in this context
1466 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1467 </li>
1468 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1469 However, at the time of writing, the schema for registering ProtocolDescriptions in the IVO registry has not been finalized.
1470
1471 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1472
1473 <b>UI display name  </b>
1474
1475 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1476 If a client is unable to resolve a Protocol identifier into a description, then it MAY just display the identifier as a text string:
1477
1478 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1479
1480 <ul><li> Download using urn:my?protocol
1481 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1482 </li>
1483 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1484 If the client can resolve the Protocol identifier into a description, then the client MAY use the information in the description to display a human readable name and description of the Protocol:
1485
1486 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1487
1488 <ul><li> Download using standard HTTP GET
1489 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1490 </li>
1491 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1492 <a id="tth_sEc3.5.3"/><h4>
1493 3.5.3  Standard protocols and authentication types</h4>
1494 Protocol URIs and ProtocolDescriptions for the core set of standard transport protocols are registered under a StandardKeyEnumeration resource [VOStd] in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. The following URIs SHALL be used to represent the standard protocols:
1495
1496 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1497
1498 <ul><li>
1499 <pre>ivo://ivoa.net/vospace/core#httpget
1500 </pre> SHALL be used as the protocol URI for a HTTP GET transfer
1501 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1502 </li>
1503
1504 <li>
1505 <pre>ivo://ivoa.net/vospace/core#httpput
1506 </pre> SHALL be used as the protocol URI for a HTTP PUT transfer
1507 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1508 </li>
1509 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1510 AuthenticationType URIs and AuthenticationTypeDescriptions for the core set of standard authentication types are registered under a StandardKeyEnumeration resource [VOStd] in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. The following URIs SHALL be used to represent the standard authentication types:
1511
1512 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1513
1514 <ul><li>
1515 <pre>ivo://ivoa.net/vospace/core#anon
1516 </pre> SHALL be used as the authentication type URI for no client authentication
1517 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1518 </li>
1519
1520 <li>
1521 <pre>ivo://ivoa.net/vospace/core#httpauth
1522 </pre> SHALL be used as the authentication type URI for HTTP userid password SHALL be used as the authentication type URI for X.509 certificate authentication be used as the protocol URI for a HTTP PUT transfer
1523 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1524 </li>
1525
1526 <li>
1527 <pre>ivo://ivoa.net/vospace/core#cookie
1528 </pre> SHALL be used as the authentication type URI for session-based cookie authentication
1529 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1530 </li>
1531
1532 <li>
1533 <pre>ivo://ivoa.net/vospace/core#oauth
1534 </pre> SHALL be used as the authentication type URI for OAuth authentication
1535 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1536 </li>
1537 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1538 However, this is not intended to be a closed list, different implementations are free to define and use their own transfer Protocols and authentication types.
1539
1540 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1541 <a id="tth_sEc3.5.4"/><h4>
1542 3.5.4  Custom protocols</h4>
1543 There are several use cases where a specific VOSpace implementation may want to define and use a custom VOSpace transfer Protocol, either extending an existing Protocol, or defining a new one.
1544
1545 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1546
1547 <b>SRB Gateway  </b>
1548 One example would be a VOSpace service that was integrated with a SRB system. In order to enable the service to use the native SRB transport protocol to transfer data, the service providers would need to register a new ProtocolDescription to represent the SRB transport protocol.
1549
1550 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1551 The ProtocolDescription would refer to the technical specification for the SRB transport protocol, and define how it should be used to transfer data to and from the VOSpace service.
1552
1553 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1554 Clients that do not understand the SRB transport protocol would not recognize the URI for the SRB Protocol, and would ignore Transfer options offered using this Protocol.
1555
1556 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1557 Clients that were able to understand the SRB transport protocol would recognize the URI for the SRB Protocol, and could use the 'srb://..' endpoint address in a Protocol option to transfer data using the SRB transport protocol.
1558
1559 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1560 Enabling different groups to define, register and use their own custom Protocols in this way means that support for new transport protocols can be added to VOSpace systems without requiring changes to the core VOSpace specification.
1561
1562 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1563 In this particular example, it is expected that one group within the IVOA will work with the SRB team at SDSC to define and register the Protocol URI and ProtocolDescription for using the SRB protocol to transfer data to and from VOSpace systems.
1564
1565 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1566 Other implementations that plan to use the SRB transport protocol in the same way could use the same Protocol URI and ProtocolDescription to describe data transfers using the SRB transport protocol.
1567
1568 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1569 The two implementations would then be able use the common Protocol URI to negotiate data transfers using the SRB transport protocol.
1570
1571 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1572
1573 <b>Local NFS transfers  </b>
1574 Another example of a custom Protocol use case would to transfer data using the local NFS file system within an institute.
1575
1576 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1577 If an institute has one or more VOSpace services co-located with a number of data processing applications, all located within the same local network, then it would be inefficient to use HTTP GET and PUT to transfer the data between the services if they could all access the same local file system.
1578
1579 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1580 In this case, the local system administrators could register a custom ProtocolDescription which described how to transfer data using their local NFS file system.
1581
1582 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1583
1584 <ul><li>
1585 <pre>ivo://my.institute/vospace/protocols#internal?nfs
1586 </pre>
1587 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1588 </li>
1589 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1590 Data transfers using this Protocol would be done using file:// URLs pointing to locations within the local NFS file system:
1591
1592 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1593
1594 <ul><li>
1595 <pre>file:///net/host/path/file
1596 </pre>
1597 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1598 </li>
1599 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1600 These URLs would only have meaning to services and applications located within the local network, and would not be usable from outside the network.
1601
1602 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1603 Services and applications located within the local network would be configured to recognize the custom Protocol URI, and to use local file system operations to move files within the NFS file system.
1604
1605 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1606 Services and applications located outside local network would not recognize the custom Protocol URI and so would not attempt to use the internal file URLs to transfer data.
1607
1608 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1609 Note that in this example the custom Protocol URI and the associated ProtocolDescription refer to data transfers using file URLs within a specific local NFS file system.
1610
1611 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1612 If a different institute wanted to use a similar system to transfer data within their own local network, then they would have to register their own custom Protocol URI and associated ProtocolDescription.
1613
1614 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1615 The two different Protocol URIs and ProtocolDescriptions describe how to use the same underlying transport protocol (NFS) in different contexts.
1616
1617 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1618 Enabling different groups to define, register and use their own custom Protocols in this way means that systems can be configured to use the best available transport protocols for transferring data, without conflicting with other systems who may be using similar a transport protocol in a different context.
1619
1620 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1621 <a id="tth_sEc3.6"/><h3>
1622 3.6  Transfers</h3>
1623 A Transfer describes the details of a data transfer to or from a space.
1624
1625 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1626 A UWS Job representation [UWS] of a Transfer SHALL have the following parameters:
1627
1628 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1629
1630 <ul><li> <em>target</em>: denotes the VOSpace node to/from which data is to be transferred
1631 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1632 </li>
1633
1634 <li> <em>direction</em>: denotes the direction of a data transfer
1635
1636 <ul><li> It can be a URI for internal data transfers (move and copy operations) or one of: pushToVoSpace, pullToVoSpace, pushFromVoSpace or pullFromVoSpace - for an external data transfer.
1637 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1638 </li>
1639 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1640 </li>
1641
1642 <li> <em>view</em>: denotes the requested View
1643
1644 <ul><li> For the transfer to be valid, the specified View must match one of those listed in the accepts or provides list of the Node.
1645 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1646 </li>
1647
1648 <li> For an internal data transfer, this parameter is not required.
1649 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1650 </li>
1651 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1652 </li>
1653
1654 <li> <em>protocol</em>: denotes the transfer protocol(s) to use
1655
1656 <ul><li> A transfer may contain more than one protocol with different Protocol URIs.
1657 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1658 </li>
1659
1660 <li> For an internal data transfer, this parameter is not required.
1661 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1662 </li>
1663 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1664 </li>
1665
1666 <li> <em>keepBytes</em>: denotes whether the source object is to be kept in an internal data transfer, i.e. distinguishes between a move and a copy
1667
1668 <ul><li> For an external data transfer, this parameter is not required.
1669 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1670 </li>
1671 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1672 </li>
1673 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1674 This representation will be used as a child of the jobInfo element in a UWS Job representation.
1675
1676 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1677 The representation of the results of a Transfer SHALL have the following members:
1678
1679 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1680
1681 <ul><li> <em>target</em>: denotes the VOSpace node to/from which data is to be transferred
1682 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1683 </li>
1684
1685 <li> <em>direction</em>: denotes the direction of a data transfer
1686
1687 <ul><li> It can be a URI for internal data transfers (move and copy operations) or one of: pushToVoSpace, pullToVoSpace, pushFromVoSpace or pullFromVoSpace - for an external data transfer.
1688 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1689 </li>
1690 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1691 </li>
1692
1693 <li> <em>view</em>: A View specifying the requested View
1694
1695 <ul><li> For the transfer to be valid, the specified View must match one of those listed in the accepts or provides list of the Node.
1696 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1697 </li>
1698
1699 <li> For an internal data transfer, this parameter is not required.
1700 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1701 </li>
1702 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1703 </li>
1704
1705 <li> <em>protocol</em>: denotes the transfer protocol(s) to use
1706
1707 <ul><li> A transfer may contain more than one protocol with different Protocol URIs.
1708 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1709 </li>
1710
1711 <li> A Transfer may contain more than one Protocol element with the same Protocol URI with different endpoints
1712 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1713 </li>
1714
1715 <li> For an internal data transfer, this parameter is not required.
1716 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1717 </li>
1718 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1719 </li>
1720 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1721 <a id="tth_sEc3.6.1"/><h4>
1722 3.6.1  Service-initiated transfers</h4>
1723 Two of the external data transfers (pullToVoSpace and pushFromVoSpace) rely on the server performing the data transfer itself.
1724
1725 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1726 The client constructs a Job request containing details of the View and one or more Protocol elements with valid endpoint addresses.
1727
1728 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1729 The service MAY ignore Protocols with URIs that it does not recognize.
1730
1731 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1732 If the server is unable to handle any of the requested Protocols in a Transfer request, then it SHALL respond with a fault.
1733
1734 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1735 The order of the Protocols in the request indicates the order of preference that the client would like the server to use. However, this is only a suggestion, and the server is free to use its own preferences to select which Protocol it uses first.
1736
1737 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1738 The service selects the first Protocol it wants to use from the list and attempts to transfer the data using the Protocol endpoint.
1739
1740 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1741 If the first attempt fails, the server may choose another Protocol from the list and re-try the transfer using that Protocol endpoint. The status flag will be updated to reflect this.
1742
1743 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1744 The server may attempt to transfer the data using any or all of the Protocols in the list until either, the data transfer succeeds, or there are no more Protocol options left.
1745
1746 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1747 The server SHALL be allowed to only use each Protocol option once. This allows a data source to issue one time URLs for a Transfer, and cancel each URL once it has been used.
1748
1749 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1750 Once one of the Protocol options succeeds the transfer SHALL be considered to have completed - the status flag needs to be updated to reflect this -, and the server is not allowed to use any of the remaining Protocol options. This allows a data source to issue a set of one time URLs for a transfer, and to cancel any unused URLs once the transfer has been completed.
1751
1752 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1753 Some Protocols MAY require the service to call a callback address when a data transfer completes. This behavior is specific to the Protocol, and SHOULD be defined in the ProtocolDescription.
1754
1755 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1756 If none of the Protocol options succeed, then the transfer SHALL be considered to have failed, and the service SHALL return a fault containing details of the Protocol options it tried. The status flag will be updated to reflect this.
1757
1758 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1759 <a id="tth_sEc3.6.2"/><h4>
1760 3.6.2  Client-initiated transfers</h4>
1761 Two of the VOSpace external transfer methods rely on an external actor performing the data transfer outside the scope of the service call.
1762
1763 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1764 In these methods, the client sends a Job request to the server which SHOULD contain details of the View and one or more protocol parameters.
1765
1766 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1767 In effect, the client is sending a list of Protocols that it (the client) wants to use for the transfer.
1768
1769 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1770 The service MAY ignore Protocols with URIs that it does not recognize.
1771
1772 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1773 The service selects the Protocols from the request that it is capable of handling, and builds a Transfer results response containing the selected Protocol elements filling in valid endpoint addresses for each of them.
1774
1775 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1776 If available, the service may choose to consult the authType in the Protocols to construct correct endpoints.
1777
1778 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1779 The order of the Protocol elements in the request indicates the order of preference that the client would like to use. However, this is only a suggestion, and the server is free to use its own preferences when generating the list of Protocols in the response.
1780
1781 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1782 In effect, the server is responding with the subset of the requested Protocols that it (the server) is prepared to offer.
1783
1784 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1785 If the server is unable to accept any of the requested Protocols, then it SHALL respond with a fault.
1786
1787 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1788 On receipt of the response, the client can use the list of Protocols itself, or pass them on to another agent to perform the data transfer on its behalf.
1789
1790 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1791 The agent MAY ignore Protocols URIs that it does not recognize.
1792
1793 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1794 The agent selects the first Protocol it wants to use from the list and attempts to transfer the data using the Protocol endpoint. The status flag will be updated to reflect this.
1795
1796 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1797 If the first attempt fails, the agent MAY choose another Protocol from the list and re-try the transfer using that Protocol endpoint.
1798
1799 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1800 The agent MAY attempt to transfer the data using any or all of the Protocols in the list until either, the data transfer succeeds, or there are no more Protocol options left.
1801
1802 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1803 The agent SHALL be allowed to only use each Protocol option once. This allows a data source to issue one time URLs for a Transfer, and cancel each URL once it has been used.
1804
1805 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1806 Once one of the Protocol options succeeds the transfer SHALL be considered to have completed and the status flag will be updated correspondingly. The agent is not allowed to use any of the remaining unused Protocol options. This allows a data source to issue a set of one time URLs for a transfer, and to cancel any unused URLs once the transfer has been completed.
1807
1808 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1809 Some Protocols MAY require the agent to call a callback address when a data transfer completes. This behavior is specific to the Protocol, and SHOULD be defined in the ProtocolDescription.
1810
1811 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1812 If none of the Protocol options succeed, then the transfer SHALL be considered to have failed and the status will be updated.
1813
1814 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1815 <a id="tth_sEc3.7"/><h3>
1816 3.7  Searches</h3>
1817 A Search describes the details of data objects in the space which meet specified search criteria, i.e. that are the results of a submitted search request.
1818
1819 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1820 A UWS Job representation of a Search SHALL have the following parameters:
1821
1822 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1823
1824 <ul><li> <em>uri</em>: An OPTIONAL identifier indicating from which item to continue a search
1825 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1826 </li>
1827
1828 <li> <em>limit</em>: An OPTIONAL limit indicating the maximum number of results in the response
1829
1830 <ul><li> No limit indicates a request for an unpaged list. However the server MAY still impose its own limit on the size of an individual response, splitting the results into more than one page if required
1831 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1832 </li>
1833 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1834 </li>
1835
1836 <li> <em>detail</em>: The level of detail in the results
1837
1838 <ul><li> min: The list contains the minimum detail for each Node with all optional parts removed - the node type should be returned
1839
1840 <ul><li> e.g.
1841 <pre>&lt;node uri="vos://service/name" xsi:type="Node"/&gt;
1842 </pre>
1843 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1844 </li>
1845 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1846 </li>
1847
1848 <li> max : The list contains the maximum detail for each Node, including any xsi:type specific extensions
1849 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1850 </li>
1851
1852 <li> properties : The list contains a basic node element with a list of properties for each Node with no xsi:type specific extensions.
1853 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1854 </li>
1855 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1856 </li>
1857
1858 <li> <em>matches</em>: An OPTIONAL search string consisting of properties and values to match against and joined in conjunction (and) or disjunction (or).
1859
1860 <ul><li> Each property-value pair consists of the uri identifying a particular property and a regular expression against which the property values are to be matched: 'uri' = 'regex'
1861 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1862 </li>
1863
1864 <li> The match pairs can be combined in conjunction and/or disjunction using 'and' and 'or' respectively. For example: "(property1 = 'value1' and property2 = 'value2') or property3 = 'value3'".
1865 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1866 </li>
1867
1868 <li> The regex syntax SHALL comply with POSIX conventions.
1869 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1870 </li>
1871 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1872 </li>
1873
1874 <li> <em>node</em>: An OPTIONAL URI(s) identifying the starting node for a search, i.e., the matches constraints are applied to this node and its children
1875 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1876 </li>
1877 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1878 This representation will be used as a child of the jobInfo element in a UWS Job representation. For example:
1879
1880 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1881
1882 <pre>
1883 &lt;uws:jobInfo&gt;
1884   &lt;vos:search&gt;
1885     &lt;vos:detail&gt;properties&lt;/vos:detail&gt;
1886     &lt;vos:matches&gt;ivo://ivoa.net/vospace/core#description='galax'&lt;/vos:matches&gt;
1887   &lt;vos:search&gt;
1888 &lt;uws:jobInfo&gt;
1889
1890 </pre>
1891
1892 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1893 The representation of the results of a Search SHALL have the following members:
1894
1895 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1896
1897 <ul><li> <em>nodes</em>: A list containing zero or more Nodes of appropriate detail identifying the target URIs meeting the search criteria
1898 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1899 </li>
1900 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1901 <a id="tth_sEc3.8"/><h3>
1902 3.8  REST bindings</h3>
1903 In a REST (Representational State Transfer) binding of VOSpace, each of the objects defined below is available as a web resource with its own URI.
1904
1905 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1906
1907 <table class="tabular"><tr><td align="left">/properties </td><td width="158">the properties employed in the space </td></tr><tr><td align="left">/views </td><td width="158">the views employed in the space </td></tr><tr><td align="left">/protocols </td><td width="158">the protocols employed in the space </td></tr><tr><td align="left">/searches </td><td width="158">the searches of the space </td></tr><tr><td align="left">/nodes/(node-path) </td><td width="158">a Node under the nodes of the space </td></tr><tr><td align="left">/transfers </td><td width="158">the transfers for the space </td></tr><tr><td align="left">/transfers/(job-id)/results/transferDetails </td><td width="158">the transfer details for synchronous jobs </td></tr></table><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1908 The service implementor is free to choose the names given in parentheses above; the other names are part of the VOSpace 2.0 standard.
1909
1910 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1911 The endpoint /sync is also defined to receive HTTP POST requests of synchronous transfer jobs. This should respond with a redirect to the transfer details for synchronous jobs resource:
1912
1913 <pre>
1914 http://rest-endpoint/transfers/(jobid)/results/transferDetails
1915
1916 </pre>
1917 Synchronous transfers are limited to pushToVoSpace and pullFromVoSpace operations only where the client is requesting endpoint URLs where it can read or write data.
1918
1919 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1920 As an optimization, the /sync endpoint should support parameter-based HTTP POST transfer requests. Instead of returning a redirect to the transfer details, the parameter-based request to /sync returns the transferDetails document itself. As a further optimzation, if the parameter name value pair REQUEST=redirect is supplied, the /sync endpoint should issue a redirect to the first transfer endpoint that would be contained in the transfer details. In the case of an error with the optimized transfers, clients may wish to fall back to the HTTP POST to /sync and step through the entire transfer negotiation.
1921
1922 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1923 In addition, the following Nodes, appearing as part of a node-path, are reserved:
1924
1925 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1926
1927 <ul><li> .auto indicates that the service should auto-generate an endpoint URI to replace this placeholder (Note: that this is an OPTIONAL feature of a service)
1928 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1929 </li>
1930
1931 <li> .null indicates an endpoint that discards all data written to it and provides no data when read from, i.e. a bit bucket
1932 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1933 </li>
1934 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1935 The standardID for the service is: ivo://ivoa.net/std/VOSpace/v2.0. Available resources will then just be ivo://ivoa.net/std/VOSpace/v2.0#&lt;resourceName&gt;, e.g., ivo://ivoa.net/std/VOSpace/v2.0#nodes.
1936
1937 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1938 <a id="tth_sEc4"/><h2>
1939 4  Access Control</h2>
1940 VOSpace implementations may support any of the following authentication methods:
1941
1942 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1943
1944 <ul><li> no authentication (anonymous clients)
1945 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1946 </li>
1947
1948 <li> digital signatures with X.509 client certificates
1949 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1950 </li>
1951
1952 <li> user ID and password HTTP authentication
1953 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1954 </li>
1955
1956 <li> cookies
1957 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1958 </li>
1959
1960 <li> OAuth (http://oauth.net)
1961 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1962 </li>
1963 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1964 When a client is requesting a transfer from the service, the authentication type (authType) may be supplied along side the list of transfer protocols. If the service supports the requested authentication type, it may use the authType information to construct the endpoint URL for data transfer, for services may encounter situations when the URL for data transfer will depend on the authentication type the client wished to use.
1965 The access control policy for a VOSpace is defined by the implementor of that space according to the use cases for which the implementation is intended.
1966
1967 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1968 A human-readable description of the implemented access policy must be declared in the registry metadata for the space.
1969
1970 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1971 These are the most probable access policies:
1972
1973 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1974
1975 <ul><li> No access control is asserted. Any client can create, read, write and delete nodes anonymously
1976 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1977 </li>
1978
1979 <li> No authorization is required, but clients must authenticate an identity (for logging purposes) in each request to the space
1980 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1981 </li>
1982
1983 <li> Clients may not create or change nodes (i.e. the contents of the space are fixed by the implementation or set by some interface other than VOSpace), but any client can read any node without authentication
1984 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1985 </li>
1986
1987 <li> Nodes are considered to be owned by the user who created them. Only the owner can operate on a node
1988 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1989 </li>
1990 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1991 No operations to modify the access policy (e.g. to set permissions on an individual node) are included in this standard. Later versions may add such operations.
1992
1993 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1994 Where the access policy requires authentication of callers, the VOSpace service SHALL support one of the authentication methods defined in the IVOA Single Sign On profile.
1995
1996 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
1997 <a id="tth_sEc5"/><h2>
1998 5  Web service operations</h2>
1999
2000 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2001 A VOSpace 2.1 service SHALL be a REST service with the following operations:
2002
2003 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2004 Note: The URL http://(rest-endpoint)/nodes denotes the URL of the top node in the VOSpace. The URL http://(rest-endpoint)/nodes/(path) denotes a specific node within the VOSpace.
2005
2006 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2007 Note: When representing a Fault, the exact specified fault name SHALL be used. If this is followed by some details, the fault SHALL be separated from the subsequent characters by whitespace.
2008
2009 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2010 Note: If the service is able to detect an internal system failure (associated with an HTTP 500 status code) then it should indicate this as described below if possible.
2011
2012 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2013 <a id="tth_sEc5.1"/><h3>
2014 5.1  Service metadata</h3>
2015 These operations return comprehensive lists of service-level metadata, e.g. all protocols supported by the service. Individual nodes within a service, however, may not necessarily support all of these, i.e. only container nodes may support archive formats such as zip or tar.
2016
2017 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2018 <a id="tth_sEc5.1.1"/><h4>
2019 5.1.1  getProtocols</h4>
2020 Get a list of the transfer Protocols supported by the space service
2021
2022 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2023
2024 <b>Request  </b>
2025 A HTTP request to http://rest-endpoint/protocols
2026
2027 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2028
2029 <b>Response  </b>
2030 <br/>   <b>Status code  </b> A HTTP 200 status code
2031 <br/>   <b>Body  </b>
2032 A Protocols representation giving:
2033
2034 <ul><li> accepts: A list of Protocols that the service SHALL accept
2035
2036 <ul><li> In this context 'accepting a protocol' means that the service SHALL act as a client for the protocol
2037 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2038 </li>
2039
2040 <li> e.g. 'accepting httpget' means the service can read data from an external HTTP web server
2041 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2042 </li>
2043 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2044 </li>
2045
2046 <li> provides: A list of Protocols that the service SHALL provide
2047
2048 <ul><li> In this context 'providing a protocol' means that the service SHALL act as a server for the protocol
2049 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2050 </li>
2051
2052 <li> e.g. 'providing httpget' means the service can act as a http web server
2053 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2054 </li>
2055 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2056 </li>
2057 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2058
2059 <b>Faults  </b>
2060
2061 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
2062 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2063 </li>
2064 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2065
2066 <b>Example  </b>
2067 getProtocols
2068
2069 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2070
2071 <table class="tabular"><tr><td width="395">
2072 <pre>
2073 &gt; curl -v http://localhost:8000/vospace-2.0/protocols
2074
2075 </pre> </td></tr><tr><td width="395">
2076 <pre>
2077 * Connected to localhost (127.0.0.1) port 8000 (#0)
2078 &gt; GET /protocols HTTP/1.1
2079 &gt; User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4
2080     OpenSSL/0.9.8l zlib/1.2.3
2081 &gt; Host: localhost:8000
2082 &gt; Accept: */*
2083 &gt; 
2084 &lt; HTTP/1.1 200 OK
2085 &lt; Date: Tue, 09 Mar 2010 04:59:12 GMT
2086 &lt; Content-Length: 309
2087 &lt; Content-Type: text/html
2088 &lt; Allow: GET, HEAD, POST, PUT
2089 &lt; Server: CherryPy/3.1.2
2090 &lt; 
2091 &lt;protocols xmlns="http://www.ivoa.net/xml/VOSpace/v2.0"&gt;
2092   &lt;accepts&gt;
2093     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/&gt;
2094     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpput"/&gt;
2095   &lt;/accepts&gt;
2096   &lt;provides&gt;
2097     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/&gt;
2098     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpput"/&gt;
2099   &lt;/provides&gt;
2100 &lt;/protocols&gt;
2101 * Connection #0 to host localhost left intact
2102 * Closing connection #0
2103
2104 </pre> </td></tr></table><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2105 <a id="tth_sEc5.1.2"/><h4>
2106 5.1.2  getViews</h4>
2107 Get a list of the Views and data formats supported by the space service
2108
2109 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2110
2111 <b>Request  </b>
2112 A HTTP GET to http://rest-endpoint/views
2113
2114 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2115
2116 <b>Response  </b>
2117 <br/>   <b>Status code  </b> A HTTP 200 status code
2118 <br/>   <b>Body  </b>
2119 A Views representation giving:
2120
2121 <ul><li> accepts: A list of Views that the service SHALL accept
2122
2123 <ul><li> In this context 'accepting a view' means that the service SHALL receive input data in this format
2124 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2125 </li>
2126
2127 <li> A simple file based system may use the reserved View URI ivo://net.ivoa.vospace/views/any to indicate that it can accept data in any format
2128 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2129 </li>
2130 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2131 </li>
2132
2133 <li> provides: A list of Views that the service SHALL provide
2134
2135 <ul><li> In this context 'providing a view' means that the service SHALL produce output data in this format
2136 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2137 </li>
2138
2139 <li> A simple file based system may use the reserved View URI ivo://net.ivoa.vospace/views/any to indicate that it can provide data in any format
2140 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2141 </li>
2142 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2143 </li>
2144 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2145
2146 <b>Faults  </b>
2147
2148 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
2149 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2150 </li>
2151 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2152
2153 <b>Example  </b>
2154 getViews
2155
2156 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2157
2158 <table class="tabular"><tr><td width="395">
2159 <pre>
2160 &gt; curl -v "http://localhost:8000/views"
2161
2162 </pre> </td></tr><tr><td width="395">
2163 <pre>
2164 * Connected to localhost (127.0.0.1) port 8000 (#0)
2165 &gt; GET /views HTTP/1.1
2166 &gt; User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4
2167     OpenSSL/0.9.8l zlib/1.2.3
2168 &gt; Host: localhost:8000
2169 &gt; Accept: */*
2170 &gt; 
2171 &lt; HTTP/1.1 200 OK
2172 &lt; Date: Tue, 09 Mar 2010 19:36:17 GMT
2173 &lt; Content-Length: 181
2174 &lt; Content-Type: text/html
2175 &lt; Allow: GET, HEAD, POST, PUT
2176 &lt; Server: CherryPy/3.1.2
2177 &lt; 
2178 &lt;views xmlns="http://www.ivoa.net/xml/VOSpace/v2.0"&gt;
2179   &lt;accepts&gt;
2180     &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/&gt;
2181   &lt;/accepts&gt;
2182   &lt;provides&gt;
2183     &lt;view uri="ivo://ivoa.net/vospace/core#defaultview"/&gt;
2184   &lt;/provides&gt;
2185 &lt;/views&gt;
2186 * Connection #0 to host localhost left intact
2187 * Closing connection #0
2188
2189 </pre> </td></tr></table><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2190 <a id="tth_sEc5.1.3"/><h4>
2191 5.1.3  getProperties</h4>
2192
2193 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2194
2195 <b>Request  </b>
2196 A HTTP request to http://rest-endpoint/properties
2197
2198 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2199
2200 <b>Response  </b>
2201 <br/>   <b>Status code  </b> A HTTP 200 status code
2202 <br/>   <b>Body  </b>
2203 A Properties representation including:
2204
2205 <ul><li> accepts: A list of identifiers for the Properties that the service SHALL accept and understand. This refers to metadata (Properties) that is implementation dependent but can be used by a client to control operational aspects of the service: for example, a VOSpace implementation might allow individual users to control the permissions on data objects via a Property called "permissions". If the VOSpace receives a data object with this Property then it 'understands' what this property refers to and can deal with it accordingly.
2206 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2207 </li>
2208
2209 <li> provides: A list of identifiers for the Properties that the service SHALL provide
2210 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2211 </li>
2212
2213 <li> contains: A list of identifiers for all the Properties currently used by Nodes within the service
2214 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2215 </li>
2216 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2217
2218 <b>Faults  </b>
2219
2220 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
2221 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2222 </li>
2223 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2224
2225 <b>Example  </b>
2226 getProperties
2227
2228 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2229
2230 <table class="tabular"><tr><td width="395">
2231 <pre>
2232 &gt; curl -v "http://localhost:8000/properties"
2233
2234 </pre> </td></tr><tr><td width="395">
2235 <pre>
2236 * Connected to localhost (127.0.0.1) port 8000 (#0)
2237 &gt; GET /properties HTTP/1.1
2238 &gt; User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4
2239     OpenSSL/0.9.8l zlib/1.2.3
2240 &gt; Host: localhost:8000
2241 &gt; Accept: */*
2242 &gt; 
2243 &lt; HTTP/1.1 200 OK
2244 &lt; Date: Tue, 09 Mar 2010 19:43:23 GMT
2245 &lt; Content-Length: 644
2246 &lt; Content-Type: text/html
2247 &lt; Allow: GET, HEAD, POST, PUT
2248 &lt; Server: CherryPy/3.1.2
2249 &lt; 
2250 &lt;properties xmlns="http://www.ivoa.net/xml/VOSpace/v2.0"&gt;
2251   &lt;accepts&gt;
2252     &lt;property uri="ivo://ivoa.net/vospace/core#title"/&gt;
2253     &lt;property uri="ivo://ivoa.net/vospace/core#creator"/&gt;
2254     &lt;property uri="ivo://ivoa.net/vospace/core#description"/&gt;
2255   &lt;/accepts&gt;
2256  &lt;provides&gt;
2257     &lt;property uri="ivo://ivoa.net/vospace/core#availableSpace"/&gt;
2258     &lt;property uri="ivo://ivoa.net/vospace/core#httpput"/&gt;
2259   &lt;/provides&gt;
2260   &lt;contains&gt;
2261     &lt;property uri="ivo://ivoa.net/vospace/core#availableSpace"/&gt;
2262     &lt;property uri="ivo://ivoa.net/vospace/core#title"/&gt;
2263     &lt;property uri="ivo://ivoa.net/vospace/core#creator"/&gt;
2264     &lt;property uri="ivo://ivoa.net/vospace/core#description"/&gt;
2265   &lt;/contains&gt;
2266 &lt;/properties&gt;
2267 * Connection #0 to host localhost left intact
2268 * Closing connection #0
2269
2270 </pre> </td></tr></table><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2271 <a id="tth_sEc5.2"/><h3>
2272 5.2  Creating and manipulating data nodes</h3>
2273
2274 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2275 <a id="tth_sEc5.2.1"/><h4>
2276 5.2.1  createNode</h4>
2277 Create a new node at a specified location
2278
2279 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2280
2281 <b>Request  </b>
2282 A HTTP PUT of a node representation to the node URL:
2283
2284 <ul><li> <em>node</em>: A template Node (as defined in Section 3.1) for the node to be created
2285 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2286 </li>
2287 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2288 A valid uri attribute SHALL be required. The name .auto is a reserved URI to indicate an auto-generated URI for the destination, i.e. given the following URI vos://service/path/.auto a service SHALL create a new unique URI for the node within vos://service/path.
2289
2290 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2291 If the Node xsi:type is not specified then a generic node of type Node is implied.
2292
2293 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2294 The permitted values of xsi:type are:
2295
2296 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2297
2298 <ul><li> vos:Node
2299 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2300 </li>
2301
2302 <li> vos:DataNode
2303 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2304 </li>
2305
2306 <li> vos:UnstructuredDataNode
2307 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2308 </li>
2309
2310 <li> vos:StructuredDataNode
2311 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2312 </li>
2313
2314 <li> vos:ContainerNode
2315 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2316 </li>
2317
2318 <li> vos:LinkNode
2319 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2320 </li>
2321 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2322 When creating a new Node the service MAY substitute a valid subtype, i.e. If xsi:type is set to vos:DataNode then this may be implemented as a DataNode, StructuredDataNode or an UnstructuredDataNode.
2323
2324 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2325 The properties of the new Node can be set by adding Properties to the template. Attempting to set a Property that the service considers to be 'readOnly' SHALL cause a PermissionDenied fault. The accepts and provides lists of Views for the Node cannot be set using this method.
2326
2327 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2328 The capabilities list for the Node cannot be set using this method.
2329
2330 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2331
2332 <b>Response  </b>
2333 <br/>   <b>Status code  </b> A HTTP 201 status code
2334 <br/>   <b>Body  </b>
2335 A node representation including
2336
2337 <ul><li> <em>node</em>: details of the new Node
2338 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2339 </li>
2340 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2341 The <em>accepts</em> list of Views for the Node SHALL be filled in by the service based on service capabilities.
2342
2343 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2344 The <em>provides</em> list of Views for the Node MAY not be filled in until some data has been imported into the Node.
2345
2346 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2347 The <em>capabilities</em> list for the Node MAY not be filled in until some data has been imported into the Node.
2348
2349 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2350
2351 <b>Faults  </b>
2352
2353 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
2354 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2355 </li>
2356
2357 <li> The service SHALL throw a HTTP 409 status code including a DuplicateNode fault in the entity body if a Node already exists with the same URI
2358 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2359 </li>
2360
2361 <li> The service SHALL throw a HTTP 400 status code including an InvalidURI fault in the entity body if the requested URI is invalid
2362 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2363 </li>
2364
2365 <li> The service SHALL throw a HTTP 400 status code including a TypeNotSupported fault in the entity body if the type specified in xsi:type is not supported
2366 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2367 </li>
2368
2369 <li> The service SHALL throw a HTTP 401 status code including PermissionDenied fault in the entity body if the user does not have permissions to perform the operation
2370 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2371 </li>
2372
2373 <li> If a parent node in the URI path does not exist then the service SHALL throw a HTTP 404 status code including a ContainerNotFound fault in the entity body.
2374
2375 <ul><li> For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a ContainerNotFound fault in the entity body if either /a or /a/b do not exist.
2376 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2377 </li>
2378 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2379 </li>
2380
2381 <li> If a parent node in the URI path is a LinkNode, the service SHALL throw a HTTP 400 status code including a LinkFound fault in the entity body.
2382
2383 <ul><li> For example, given the URI path /a/b/c, the service must throw a HTTP 400 status code including a LinkFound fault in the entity body if either /a or /a/b are LinkNodes.
2384 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2385 </li>
2386 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2387 </li>
2388 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2389
2390 <b>Example  </b>
2391 createNode
2392
2393 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2394
2395 <table class="tabular"><tr><td width="395">The node to be created (newNode.xml) is:
2396
2397 <pre>
2398 &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2399     xsi:type="vos:UnstructuredDataNode"
2400     xmlns="http://www.ivoa.net/xml/VOSpace/v2.0"
2401         uri="vos://nvo.caltech!vospace/mydata1"&gt;
2402   &lt;properties&gt;
2403     &lt;property uri="ivo://ivoa.net/vospace/core#description"&gt;
2404         My important results&lt;/property&gt;
2405   &lt;/properties&gt;
2406   &lt;accepts/&gt;
2407   &lt;provides/&gt;
2408   &lt;capabilities/&gt;
2409 &lt;/node&gt;
2410
2411 </pre>
2412
2413 <pre>
2414 &gt; curl -v -X PUT -d @newNode.xml "http://localhost:8000/nodes/mydata1"
2415
2416 </pre> </td></tr><tr><td width="395">
2417 <pre>
2418 * Connected to localhost (127.0.0.1) port 8000 (#0)
2419 &gt; PUT /nodes/mydata1 HTTP/1.1
2420 &gt; User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4
2421     OpenSSL/0.9.8l zlib/1.2.3
2422 &gt; Host: localhost:8000
2423 &gt; Accept: */*
2424 &gt; Content-Length: 267
2425 &gt; Content-Type: application/x-www-form-urlencoded
2426 &gt; 
2427 &lt; HTTP/1.1 200 Created
2428 &lt; Date: Wed, 10 Mar 2010 00:10:27 GMT
2429 &lt; Content-Length: 323
2430 &lt; Content-Type: text/html
2431 &lt; Allow: GET, HEAD, POST, PUT
2432 &lt; Server: CherryPy/3.1.2
2433 &lt; 
2434 * Connection #0 to host localhost left intact
2435 * Closing connection #0
2436 &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2437   xmlns="http://www.ivoa.net/xml/VOSpace/v2.0"
2438       xsi:type="vos:UnstructuredDataNode" 
2439   uri="vos://nvo.caltech!vospace/mydata1"&gt;
2440   &lt;properties&gt;
2441     &lt;property uri="ivo://ivoa.net/vospace/core#description"&gt;
2442         My important results&lt;/property&gt;
2443   &lt;/properties&gt;
2444   &lt;accepts&gt;
2445     &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/&gt;
2446   &lt;/accepts&gt;
2447   &lt;provides/&gt;
2448   &lt;capabilities/&gt;
2449 &lt;/node&gt;
2450
2451 </pre> </td></tr></table><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2452 <a id="tth_sEc5.2.2"/><h4>
2453 5.2.2  moveNode</h4>
2454 Move a node within a VOSpace service.
2455
2456 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2457 Note that this does not cover moving data between two separate VOSpace services.
2458
2459 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2460 Moving nodes between separate VOSpace services SHOULD be handled by the client, using the import, export and delete methods.
2461
2462 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2463 When the source is a ContainerNode, all its children (the contents of the container) SHALL also be moved to the new destination.
2464
2465 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2466 When the destination is an existing ContainerNode, the source SHALL be placed under it (i.e. within the container).
2467
2468 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2469 The Node type cannot be changed using this method.
2470
2471 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2472
2473 <b>Request  </b>
2474
2475 <ul><li> A HTTP POST of a Job representation for the transfer (see section 3.6) to http://rest-endpoint/transfers.
2476 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2477 </li>
2478 </ul><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2479 .auto is a reserved URI to indicate an autogenerated URI for the destination, i.e. vos://service/path/.auto SHALL cause a new unique URI for the node within vos://service/path to be generated.
2480
2481 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2482
2483 <b>Response  </b>
2484 <br/>   <b>Status code  </b> The initial response is a HTTP 303 status code with the Location header keyword assigned to the created job.
2485 <br/>   <b>Body  </b>
2486 If an autogenerated URI for the destination was specified in the request then its value SHALL be specified as a result in the Results List for the completed transfer with the id of "destination":
2487
2488 <pre>
2489 &lt;uws:job&gt;
2490   ...
2491   &lt;uws:jobInfo&gt;
2492     &lt;vos:direction&gt;vos://nvo.caltech!vospace/mjg/.auto&lt;/vos:direction&gt;
2493   ...
2494   &lt;uws:results&gt;
2495     &lt;uws:result id="destination"&gt;vos://nvo.caltech!vospace/mjg/abc123&lt;/uws:result&gt;
2496   &lt;/uws:results&gt;
2497   ...
2498 &lt;/uws:job&gt;
2499
2500 </pre>
2501
2502 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2503
2504 <b>Faults  </b>
2505
2506 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2507 For all faults, the service shall set the PHASE to ËRROR" in the Job representation. The &lt;errorSummary&gt; element in the Job representation shall be set to the appropriate value for the fault type and the appropriate fault representation (see section 5.5) provided at the error URI: http://rest-endpoint/transfers/(jobid)/error.
2508
2509 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2510
2511 <table class="tabular"><tr><td width="197"><b>Fault description</b> </td><td align="left"><b>errorSummary</b> </td><td width="158"><b>Fault representation</b> </td></tr><tr><td width="197">Operation fails </td><td align="left">Internal Fault </td><td width="158">InternalFault </td></tr><tr><td width="197">User does not have permissions to perform the operation </td><td align="left">Permission Denied </td><td width="158">PermissionDenied </td></tr><tr><td width="197">Source node does not exist </td><td align="left">Node Not Found </td><td width="158">NodeNotFound </td></tr><tr><td width="197">Destination node already exists and it is not a ContainerNode </td><td align="left">Duplicate Node </td><td width="158">DuplicateNode </td></tr><tr><td width="197">A specified URI is invalid </td><td align="left">Invalid URI </td><td width="158">InvalidURI </td></tr></table><p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2512
2513 <b>Example  </b>
2514 moveNode
2515
2516 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2517 The Job to be submitted (newJob.xml) is:
2518
2519 <pre>
2520 &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2521 &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0&gt;
2522   &lt;vos:target&gt;vos://nvo.caltech!vospace/mydata1&lt;/vos:target&gt;
2523   &lt;vos:direction&gt;vos://nvo.caltech!vospace/mydata2&lt;/vos:direction&gt;
2524   &lt;vos:keepBytes&gt;false&lt;/vos:keepBytes&gt;
2525 &lt;/vos:transfer&gt;
2526
2527 </pre>
2528
2529 <pre>
2530 &gt; curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"
2531
2532 </pre>
2533
2534
2535 <pre>
2536 * Connected to localhost (127.0.0.1) port 8000 (#0)
2537 &gt; POST /transfers HTTP/1.1
2538 &gt; User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4
2539     OpenSSL/0.9.8l zlib/1.2.3
2540 &gt; Host: localhost:8000
2541 &gt; Accept: */*
2542 &gt; Content-Length: 762
2543 &gt; Content-Type: application/x-www-form-urlencoded
2544 &gt; 
2545 &lt; HTTP/1.1 303 See Other
2546 &lt; Content-Length: 174
2547 &lt; Server: CherryPy/3.1.2
2548 &lt; Location: http://localhost:8080/transfers/
2549     ec200b5ff77641fb841978a85d1f7245
2550 &lt; Allow: GET, HEAD, POST, PUT
2551 &lt; Date: Thu, 11 Mar 2010 19:54:00 GMT
2552 &lt; Content-Type: text/html
2553 &lt; 
2554 * Connection #0 to host localhost left intact
2555 * Closing connection #0
2556
2557 </pre>
2558 This resource can be found at http://localhost:8000/transfers/
2559 ec200b5ff77641fb841978a85d1f7245.
2560
2561
2562 <pre>
2563 The status of the job can now be polled at the job location:
2564 &gt; curl -v "http://localhost:8000/transfers/
2565     ec200b5ff77641fb841978a85d1f7245"
2566
2567 </pre>
2568
2569 <span class="huge">
2570 <pre>
2571
2572 * Connected to localhost (127.0.0.1) port 8000 (#0)
2573 &gt; GET /transfers/ccfd4ba0dd9f4406b2039c4358ba8ef3 HTTP/1.1
2574 &gt; User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4
2575 OpenSSL/0.9.8l zlib/1.2.3
2576 &gt; Host: localhost:8000
2577 &gt; Accept: */*
2578 &gt;
2579 &lt; HTTP/1.1 200 OK
2580 &lt; Date: Thu, 11 Mar 2010 19:54:02 GMT
2581 &lt; Content-Length: 802
2582 &lt; Content-Type: text/html
2583 &lt; Allow: GET, HEAD, POST, PUT
2584 &lt; Server: CherryPy/3.1.2
2585 &lt;
2586 &lt;uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink=
2587 "http://www.w3.org/1999/xlink"
2588 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2589 xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0"
2590 xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd »
2591 &lt;uws:jobId&gt;ec200b5ff77641fb841978a85d1f7245&lt;/uws:jobId&gt;
2592 &lt;uws:ownerId xsi:nil="true"/&gt;
2593 &lt;uws:phase&gt;EXECUTING&lt;/uws:phase&gt;
2594 &lt;uws:startTime&gt;2010-03-11T19:54:00.433058&lt;/uws:startTime&gt;
2595 &lt;uws:endTime xsi:nil="true"/&gt;
2596 &lt;uws:executionDuration&gt;0&lt;/uws:executionDuration&gt;
2597 &lt;uws:destruction xsi:nil="true"/&gt;
2598 &lt;uws:jobInfo&gt;
2599 &lt;vos:transfer&gt;
2600 &lt;vos:target&gt;vos://nvo.caltech!vospace/mydata1&lt;/vos:target&gt;
2601 &lt;vos:direction&gt;vos://nvo.caltech!vospace/mydata2&lt;/vos:direction&gt;
2602 &lt;vos:keepBytes&gt;false&lt;/vos:keepBytes&gt;
2603 &lt;/vos:transfer&gt;
2604 &lt;/uws:jobInfo&gt;
2605 &lt;uws:results/&gt;
2606 * Connection #0 to host localhost left intact
2607 * Closing connection #0
2608 &lt;/uws:job&gt;
2609 </pre>
2610 </span>
2611
2612 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2613 <a id="tth_sEcA"/><h2>
2614 A  Changes from Previous Versions</h2>
2615
2616 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2617 No previous versions yet.
2618
2619 <p xmlns="http://www.w3.org/1999/xhtml" class="parsep"><span/></p>
2620
2621 <br/><br/><hr/><small>File translated from
2622 T<sub><span class="small">E</span></sub>X
2623 by <a href="http://hutchinson.belmont.ma.us/tth/">
2624 T<sub><span class="small">T</span></sub>H</a>,
2625 version 4.06.<br/>On 2 Apr 2015, 16:09.</small>
2626 </div></html>

Properties

Name Value
svn:mime-type text/html

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