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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2843 - (hide annotations)
Wed Feb 4 19:45:32 2015 UTC (5 years, 7 months ago) by major.brian
File MIME type: text/html
File size: 204906 byte(s)
vospace example correction
1 major.brian 2657 <?xml version="1.0" encoding="iso-8859-1"?>
2     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 major.brian 2654 <html>
4     <head>
5 major.brian 2657 <title>VOSpace 2.0 Recommendation</title>
6     <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
7 major.brian 2688 <meta name="keywords" content="IVOA, International, Virtual, Observatory, Alliance" />
8     <meta name="maintainedBy" content="IVOA Document Coordinator, ivoadoc@ivoa.net" />
9     <link rel="stylesheet" href="http://ivoa.net/misc/ivoa_rec.css" type="text/css" />
10 major.brian 2654 <style type="text/css">
11     .issue {background-color: yellow}
12     .postponedissue {background-color: yellow}
13     .def code
14     .future {background-color: pink}
15     .draftedit {background-color: white}
16     .draftdelete {background-color: white}
17     .note { margin-left: 4em }
18     code { font-weight: bold;
19     font-family: monospace }
20    
21     div.exampleInner pre { margin-left: 1em;
22     margin-top: 0em; margin-bottom: 0em}
23     div.exampleOuter {border: 4px double gray;
24     margin: 0em; padding: 0em}
25     div.exampleInner { border-top-width: 4px;
26     border-top-style: double;
27     border-top-color: white;
28     border-bottom-width: 4px;
29     border-bottom-style: double;
30     border-bottom-color: white;
31     padding: 0px; margin: 0em }
32     div.exampleWrapper { margin: 4px }
33     div.exampleHeader { font-weight: bold;
34     margin: 4px}
35    
36     div.schemaInner pre { margin-left: 1em;
37     margin-top: 0em; margin-bottom: 0em;
38     }
39     div.schemaOuter {border: 4px double gray; padding: 0em}
40     div.schemaInner { background-color: #eeeeee;
41     border-top-width: 4px;
42     border-top-style: double;
43     border-top-color: #d3d3d3;
44     border-bottom-width: 4px;
45     border-bottom-style: double;
46     border-bottom-color: #d3d3d3;
47     padding: 4px; margin: 0em }
48     div.schemaHeader { font-weight: bold;
49     margin: 4px}
50     </style>
51    
52     </head>
53    
54     <body>
55     <div class="head">
56     <a href="http://www.ivoa.net/"><img alt="IVOA" src="http://www.ivoa.net/pub/images/IVOA_wb_300.jpg" width="300" height="169"/></a>
57     <h1>VOSpace specification<br/>
58 major.brian 2701 Version 2.1-20140805</h1>
59 major.brian 2688 <h2>IVOA Working Draft 05 Aug 2014</h2>
60 major.brian 2654
61     <dl>
62     <dt>This version:</dt>
63 major.brian 2688 <dd><a href="http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.1-20140805.html">
64     http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.1-20140805.html</a></dd>
65 major.brian 2654
66     <dt>Latest version:</dt>
67    
68     <dd><a href="http://www.ivoa.net/Documents/latest/VOSpace-2.0">
69     http://www.ivoa.net/Documents/latest/VOSpace-2.0.html</a></dd>
70    
71 major.brian 2655 <dt>Previous versions:</dt>
72     <dd><a href="http://www.ivoa.net/Documents/WD/GWS/REC-VOSpace-2.0-20130329.html">
73     http://www.ivoa.net/Documents/WD/GWS/REC-VOSpace-2.0-20130329.html</a></dd>
74 major.brian 2654 <dd><a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20121221.html">
75     http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20121221.html</a></dd>
76     <dd><a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20120824.html">
77     http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20120824.html</a></dd>
78 major.brian 2688 <dd>PR: <a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20111202.html">
79     http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20111202.html</a></dd>
80 major.brian 2654 <dd>WD: <a href="http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20110628.html">
81     http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20110628.html</a></dd>
82     <dd>WD: <a href="http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20101112.html">
83     http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20101112.html</a></dd>
84     <dd>WD: <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20100323.html">
85     http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20100323.html</a></dd>
86     <dd>WD: <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090904.html">
87     http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090904.html</a></dd>
88     <dd>WD: <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090513.doc">
89     http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090513.doc</a></dd>
90     </dl>
91    
92     <dl>
93     <dt>Working Group:</dt>
94     <dd><a href="http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices"> http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices</a></dd>
95     <dt>Author(s):</dt>
96     <dd>
97     <a
98     href="http://www.ivoa.net/twiki/bin/view/IVOA/MatthewGraham">Matthew
99     Graham (editor) </a><br/>
100     <a
101     href="http://www.ivoa.net/twiki/bin/view/IVOA/DaveMorris">Dave
102     Morris</a><br/> <a
103     href="http://www.ivoa.net/twiki/bin/view/IVOA/GuyRixon">Guy
104     Rixon</a><br/>
105     <a
106     href="http://www.ivoa.net/twiki/bin/view/IVOA/PatDowler">Pat Dowler</a><br/>
107     <a
108     href="http://www.ivoa.net/twiki/bin/view/IVOA/AndreSchaaff">Andre
109     Schaaff</a><br/> <a
110 major.brian 2655 href="http://www.ivoa.net/twiki/bin/view/IVOA/DougTody">Doug
111     Tody</a><br/> <a
112 major.brian 2688 href="http://www.ivoa.net/twiki/bin/view/IVOA/BrianMajor">Brian
113     Major</a>
114 major.brian 2654 </dd>
115     </dl>
116     <hr/></div>
117    
118     <h2><a name="abstract" id="abstract">Abstract</a></h2>
119 major.brian 2655 <p>VOSpace is the IVOA interface to distributed storage. This specification presents the second RESTful version of the interface. Except for minor
120     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
121     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,
122     however 2.0 clients and services are incompatible with the 2.1 specification.</p>
123 major.brian 2654
124     <div class="status">
125     <h2><a name="status" id="status">Status of this Document</a></h2>
126    
127     <!-- Choose one of the following (and remove the rest)-->
128 major.brian 2688
129     <!-- Note-->
130 major.brian 2654 <!--
131     <p>This is an IVOA Note expressing suggestions from and opinions of the authors.<br/>
132     It is intended to share best practices, possible approaches, or other perspectives on interoperability with the Virtual Observatory.
133     It should not be referenced or otherwise interpreted as a standard specification.</p>
134     <p>This is an IVOA Working Draft for review by IVOA members and other interested parties.<br/>
135     It is a draft document and may be updated, replaced, or obsoleted by other documents at any time.
136     It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than work in progress.</p>
137     -->
138    
139 major.brian 2688 <!-- Working Draft -->
140     <!--
141     <p>This is an IVOA Working Draft for review by IVOA members and other interested parties.<br/>
142     It is a draft document and may be updated, replaced, or obsoleted by other documents at any time.
143     It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than work in progress.</p>
144     -->
145    
146     <!-- Proposed Recommendation -->
147     <!--
148 major.brian 2654 <p>This is an IVOA Proposed Recommendation made available for public review.<br/>
149     It is appropriate to reference this document only as a recommended standard that is under review and which may be changed before it is accepted as a full recommendation.</p>
150     <p>The first release of this document was 2009 May 13 as a Working
151     Draft and 2011 December 2011 as a Proposed Recommendation.
152     </p>
153     -->
154    
155 major.brian 2688 <!-- Recommendation
156 major.brian 2654 -->
157 major.brian 2688 <!--
158     <p>This document has been produced by the IVOA Grid and Web Services Working Group.<br/>
159     It has been reviewed by IVOA Members and other interested parties, and has been endorsed by the IVOA Executive Committee as an IVOA Recommendation.
160     It is a stable document and may be used as reference material or cited as a normative reference from another document. IVOA's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment.
161     This enhances the functionality and interoperability inside the Astronomical Community.</p>
162     -->
163 major.brian 2655 <p>This is an IVOA Working Draft for review by IVOA members and other interested parties.<br/>
164     It is a draft document and may be updated, replaced, or obsoleted by other documents at any time.
165     It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than work in progress.</p>
166 major.brian 2654
167     A list of <a href="http://www.ivoa.net/Documents/">current IVOA Recommendations and other technical documents</a> can be found at http://www.ivoa.net/Documents/.
168    
169     </div><br />
170    
171     <h2><a name="acknowledgments" id="acknowledgments">Acknowledgments</a></h2>
172     <p>This document derives from discussions among the Grid and Web Services working group of the IVOA.<p></p>
173     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).</p>
174    
175    
176     <h2><a name="conformance" id="conformance">Conformance related definitions</a></h2>
177     <p>The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and "OPTIONAL" (in upper or lower case) used in this document are to be interpreted as described in IETF standard, RFC 2119 [RFC 2119].</p><p>
178     The <strong>Virtual Observatory (VO)</strong> is a general term for a
179     collection of federated resources that can be used to conduct
180     astronomical research, education, and outreach. The <strong>International Virtual Observatory Alliance (IVOA)</strong> is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications. The International Virtual Observatory (IVO) application is an application that takes advantage of IVOA standards and infrastructure to provide some VO service.
181     </p>
182    
183     <h2><a id="contents" name="contents">Contents</a></h2>
184     <div class="head">
185     <ul class="toc">
186     <li><a href="#abstract">Abstract</a></li>
187     <li><a href="#status">Status</a></li>
188     <li><a href="#acknowledgments">Acknowledgments</a></li>
189     <li><a href="#contents">Contents</a></li>
190     <li><a href="#sec1">1. Introduction</a></li>
191     <ul class="toc"><li><a href="#sec1_1">1.1 Typical use of a VOSpace service</a></li>
192     <li><a href="#sec1_2">1.2 The role in the IVOA Architecture</a></li>
193     <li><a href="#sec1_3">1.3 Document roadmap</a></li></ul>
194     <li><a href="#sec2">2. VOSpace identifiers</a></li>
195     <ul class="toc"><li><a href="#sec2_1">2.1 Identifier resolution</a></li></ul>
196     <li><a href="#sec3">3. VOSpace data model</a></li>
197     <ul class="toc"><li><a href="#sec3_1">3.1 Node and node types</a></li>
198     <li><a href="#sec3_2">3.2 Properties</a></li>
199     <ul class="toc"><li><a href="#sec3_2_1">3.2.1 Property values</a></li>
200     <li><a href="#sec3_2_2">3.2.2. Property identifiers</a></li>
201     <li><a href="#sec3_2_3">3.2.3 Property descriptions</a></li>
202     <li><a href="#sec3_2_4">3.2.4 Standard properties</a></li></ul>
203     <li><a href="#sec3_3">3.3 Capabilities</a></li>
204     <ul class="toc"><li><a href="#sec3_3_1">3.3.1 Example use cases</a></li>
205     <li><a href="#sec3_3_2">3.3.2 Capability identifiers</a></li>
206     <li><a href="#sec3_3_3">3.3.3 Capability descriptions</a></li>
207     <li><a href="#sec3_3_4">3.3.4 UI display name</a></li>
208     <li><a href="#sec3_3_5">3.3.5 Standard capabilities</a></li></ul>
209     <li><a href="#sec3_4">3.4 Views</a></li>
210     <ul class="toc"><li><a href="#sec3_4_1">3.4.1 Example use cases</a></li>
211     <li><a href="#sec3_4_2">3.4.2 View identifiers</a></li>
212     <li><a href="#sec3_4_3">3.4.3 View descriptions</a></li>
213     <li><a href="#sec3_4_4">3.4.4 Default views</a></li>
214     <li><a href="#sec3_4_5">3.4.5 Container views</a></li></ul>
215     <li><a href="#sec3_5">3.5 Protocols</a></li>
216     <ul class="toc"><li><a href="#sec3_5_1">3.5.1 Protocol identifiers</a></li>
217     <li><a href="#sec3_5_2">3.5.2 Protocol descriptions</a></li>
218     <li><a href="#sec3_5_3">3.5.3 Standard protocols</a></li>
219     <li><a href="#sec3_5_4">3.5.4 Custom protocols</a></li></ul>
220     <li><a href="#sec3_6">3.6 Transfers</a></li>
221     <ul class="toc"><li><a href="#sec3_6_1">3.6.1 Service-initiated transfers</a></li>
222     <li><a href="#sec3_6_2">3.6.2 Client-initiated transfers</a></li></ul>
223     <li><a href="#sec3_7">3.7 Searches</a></li>
224     <li><a href="#sec3_8">3.8 REST bindings</a></li></ul>
225     <li><a href="#sec4">4. Access Control</a></li>
226     <li><a href="#sec5">5. Web service operations</a></li>
227     <ul class="toc"><li><a href="#sec5_1">5.1 Service metadata</a></li>
228     <ul class="toc"><li><a href="#sec5_1_1">5.1.1 getProtocols</a></li>
229     <li><a href="#sec5_1_2">5.1.2 getViews</a></li>
230     <li><a href="#sec5_1_3">5.1.3 getProperties</a></li></ul>
231     <li><a href="#sec5_2">5.2 Creating and manipulating data nodes</a></li>
232     <ul class="toc"><li><a href="#sec5_2_1">5.2.1 createNode</a></li>
233     <li><a href="#sec5_2_2">5.2.2 moveNode</a></li>
234     <li><a href="#sec5_2_3">5.2.3 copyNode</a></li>
235     <li><a href="#sec5_2_4">5.2.4 deleteNode</a></li></ul>
236     <li><a href="#sec5_3">5.3 Accessing metadata</a></li>
237     <ul class="toc"><li><a href="#sec5_3_1">5.3.1 getNode</a></li>
238     <li><a href="#sec5_3_2">5.3.2 setNode</a></li>
239     <li><a href="#sec5_3_3">5.3.3 findNodes</a></li></ul>
240     <li><a href="#sec5_4">5.4 Transferring data</a></li>
241     <ul class="toc"><li><a href="#sec5_4_1">5.4.1 pushToVoSpace</a></li>
242     <li><a href="#sec5_4_2">5.4.2 pullToVoSpace</a></li>
243     <li><a href="#sec5_4_3">5.4.3 pullFromVoSpace</a></li>
244     <li><a href="#sec5_4_4">5.4.4 pushFromVoSpace</a></li></ul>
245     <li><a href="#sec5_5">5.5 Fault arguments</a></li>
246     </ul>
247     <li><a href="#sec6">6. Changes since last version</a></li>
248     <li><a href="#appA">Appendix A: Machine readable definitions</a></li>
249     <ul class="toc">
250     <li><a href="#appA_1">A.1 Message schema</a></li></ul>
251     <li><a href="#appB">Appendix B: Compliance matrix</a></li>
252     <li><a href="#appC">Appendix C: Standard properties</a></li>
253     <li><a href="#references">References</a></li>
254     </ul>
255     </div>
256     <hr/>
257    
258     <br/>
259     <h2><a name="sec1">1. Introduction</a></h2>
260     <p>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.</p><p>
261     A VOSpace web service is an access point for a distributed storage network. Through this access point, a client can:</p><p>
262     <ul><li> add or delete data objects
263     <li> manipulate metadata for the data objects
264     <li> obtain URIs through which the content of the data objects can be accessed
265     </ul>
266     </p><p>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.</p><p>
267    
268     When we speak of "a VOSpace", we mean the arrangement of data accessible through one particular VOSpace service. </p><p>
269    
270     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. </p><p>
271    
272     Nodes in VOSpace have unique identifiers expressed as URIs in the 'vos' scheme, as defined below. </p><p>
273    
274 major.brian 2655 VOSpace 2.0 did not introduce any new functionality to that already
275 major.brian 2688 offered by prior (SOAP-based) versions of the interface (<a href="#VOSpace11">VOSpace 1.1</a>) but defines a RESTful binding for the interface.
276     VOSpace 2.1 introduces minor functional changes to VOSpace 2.0 addressing access control and optimizations.
277 major.brian 2654 </p>
278    
279     <h3><a name="sec1_1">1.1 Typical use of a VOSpace service</a></h3>
280     <p>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. </p><p>
281    
282     Let's consider the first sequence: the user provides a XML description
283     of the data file which they HTTP PUT to the appropriate VOSpace URI -
284     this will be the HTTP identifier for the data file in the VOSpace,
285 major.brian 2843 e.g. http://nvo.caltech.edu/vospace/nodes/mytable1. The description
286 major.brian 2654 will resemble this:</p>
287     <pre>
288 major.brian 2655 &lt;node xmlns="http://www.ivoa.net/xml/VOSpaceTypes-v2.1"
289     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
290     uri="vos://nvo.caltech!vospace/mytable1"
291     xsi:type="vost:UnstructuredDataNode">
292 major.brian 2654 &lt;properties>
293     &lt;property uri="ivo://ivoa.net/vospace/core#mimetype">text/xml&lt;/property>
294     &lt;/properties>
295     &lt;/node>
296     </pre>
297     <p>
298     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.
299     </p><p>
300     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:
301     </p><pre>
302 major.brian 2655 &lt;transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1">
303     &lt;target>vos://nvo.caltech!vospace/mytable1&lt;/target>
304 major.brian 2654 &lt;direction>pushToVoSpace&lt;/direction>
305     &lt;view uri="ivo://ivoa.net/vospace/core#votable"/>
306     &lt;protocol uri="ivo://ivoa.net/vospace/core#http-put"/>
307     &lt;/transfer>
308     </pre><p>
309     The service will reply with the URL that the user will HTTP PUT the
310     data file to,
311     e.g. http://nvo.caltech.edu/bvospace/myData/table123/transfers/147516ab. The
312     user will then use a regular HTTP client to transfer (PUT) the local
313     file to the specified endpoint. This illustrates an important point
314     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.
315     </p><p>
316     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:
317     </p><pre>
318 major.brian 2655 &lt;transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1">
319     &lt;target>vos://nvo.caltech!vospace/mytable1&lt;/target>
320 major.brian 2654 &lt;direction>pullFromVoSpace&lt;/direction>
321     &lt;view uri="ivo://ivoa.net/vospace/core#votable"/>
322     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
323     &lt;/transfer>
324     </pre><p>
325     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.
326     </p>
327    
328     <h3><a name="sec1_2">1.2 The role in the IVOA Architecture</a></h3>
329     <p>The IVOA Architecture [Arch] provides a high-level view of how IVOA
330     standards work together to connect users and applications with
331     providers of data and services, as depicted in the diagram in Fig. 1.
332     </p>
333    
334     <p>
335     <center>
336     <font size="-1">
337     <img src="vospace-in-arch.png" width="756"/> <br />
338     <blockquote>
339     <strong>Figure 1. VOSpace in the IVOA Architecture.</strong>
340     This provides an interface to distributed storage. It specifies how
341     applications can use networked data stores to persist and exchange data in a standardized fashion.
342     </blockquote>
343     </font>
344     </center>
345     </p>
346    
347     <p>In this architecture, users employ a variety of tools (from the
348     User Layer) to discover and access archives and services of interest
349     (represented in the Resource Layer). VOSpace provides an interface to
350     storage resources containing the results of using these archives and
351     services and also to other storage solutions, e.g., local disks, where
352     users might want to transfer these results for further work. Items in
353     these resources are referenced by a VOSpace identifier which is
354     related to the standard IVOA Resource Identifier (see section 2).
355     This version of VOSpace employs the UWS design pattern [UWS] to manage data
356     transfers (see section 3.6) and searches (see section 3.7). VOSpace
357     instances may also employ the IVOA Single-Sign-On standard [SSO] for
358     authentication purposes (see section 4) and IVOA Credential Delegation
359     Protocol [CDP] to delegate data transfers.
360     </p>
361    
362    
363     <h3><a name="sec1_3">1.3 Document roadmap</a></h3>
364     <p>The rest of this document is structured as follows:
365     </p><p>
366     In <a href="#sec2">Section 2</a>, we specify the URI syntax for identifying data objects (nodes) in VOSpace.
367     </p><p>
368     In <a href="#sec3">Section 3</a>, 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:
369     </p>
370     <ul>
371     <li> the data objects themselves (nodes)
372     <li> metadata that can be associated with a data object (properties)
373     <li> third-party interfaces to the data (capabilities)
374     <li> the data format used when transferring data objects across the wire (views)
375     <li> the transport protocol employed in a data transfer (protocols)
376     <li> the data transfer itself (transfers)
377     <li> searches of data objects (searches)
378     </ul>
379     <p>
380     We also describe the REST bindings between these representations and their URIs (HTTP identifiers).
381     </p><p>
382     In <a href="#sec4">Section 4</a>, we outline how security and access control policies are currently handled in VOSpace.
383     </p><p>
384     In <a href="#sec5">Section 5</a>, 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.
385     </p><p>
386     In <a href="#appA">Appendix A</a>, we formally define the VOSpace
387     interface with a machine readable description of its requests and
388     responses and in <a href="#appB">Appendix B</a>, we present a
389     compliance matrix listing the mandatory behaviour required of a valid
390 major.brian 2655 VOSpace 2.1 service.
391 major.brian 2654 </p>
392    
393    
394     <br/>
395     <h2><a name="sec2">2. VOSpace identifiers</a></h2>
396     <p>The identifier for a node in VOSpace SHALL be a URI with the scheme <code>vos</code>.</p>
397     <p>
398     Such a URI SHALL have the following parts with the meanings and
399     encoding rules defined in RFC2396 <a href="#ref2">[RFC 2396]</a>.
400     </p><ul>
401     <li> scheme
402     <li> naming authority
403     <li> path
404     <li> (optional) query
405     <li> (optional) fragment identifier (with the expected semantics <a
406     href="#fragref">[see here]</a>)
407     </ul><p>
408     The naming authority for a VOSpace node SHALL be the VOSpace service
409     through which the node was created. The authority part of the URI
410     SHALL be constructed from the IVO registry identifier [IVORN] for that
411     service by deleting the ivo:// prefix and changing all forward-slash
412     characters('/') in the resource key to exclamation marks ('!') or
413     tildes ('~'). Note that a service SHALL be consistent in its use of
414     separator characters ('!' or '~') when referring to its own data but
415     SHALL accept either as valid in URIs in service requests. For the rest
416     of the document, we shall use '!' as the default character.
417     </p><p>
418     This is an example of a possible VOSpace identifier.
419     </p>
420     <pre>
421     vos://nvo.caltech!vospace/myresults/siap-out-1.vot
422     </pre>
423     <ul<li>The URI scheme is <em>vos</em>
424     </ul>
425     <p>
426     Using a separate URI scheme for VOSpace identifiers enables clients to distinguish between IVO registry identifiers and VOSpace identifiers.
427     </p><ul>
428     <li> nvo.caltech!vospace
429     </ul><p>
430     is the authority part of the URI, corresponding to the IVO registry identifier
431     </p><ul>
432     <li> ivo://nvo.caltech/vospace
433     </ul><p>
434     This is the IVO registry identifier of the VOSpace service that contains the node.
435     </p><ul>
436     <li> /siap-out-1.vot is the URI path
437     </ul><p>
438     Slashes in the URI path imply a hierarchical arrangement of data: the
439     data object identified by
440     vos://nvo.caltech!vospace/myresults/siap-out-1.vot is within the
441     container identified by vos://nvo.caltech!vospace/myresults.
442     </p>
443     Literal space characters are also not allowed in URIs.
444     </p><p>
445     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).
446     </p><p>
447     A VOSpace identifier is globally unique, and identifies one specific
448     node in a specific VOSpace service.
449     </p>
450    
451     <p>
452 major.brian 2655 The standardID for this specification SHALL be: ivo://ivoa.net/std/VOSpace/v2.1.
453 major.brian 2654 </p>
454    
455     <h3><a name="sec2_1">2.1 Identifier resolution</a></h3>
456     <p>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: </p><ul>
457    
458     <li> Resolve HTTP service endpoint of VOSpace service with registry
459     <li> Append "nodes/" and the path following the naming authority part of the VOSpace identifier to the service endpoint
460     </ul><p>
461     Given the example identifier
462     </p><pre>
463     vos://org.astrogrid.cam!vospace/container-6/siap-out-1.vot?foo=bar
464     </pre><p>
465     processing the URI to resolve the VOSpace service would involve :
466     </p><ul>
467     <li> Extract the IVO registry identifier of the VOSpace service by prepending an ivo scheme to the naming authority part:
468     <ul><li> ivo://org.astrogrid.cam/vospace</li></ul>
469     <li> Resolve the IVO identifier in a registry and retrieve the access URL of the service endpoint:
470     <ul><li> http://some.uni.ac.uk/vospace</li></ul>
471     <li> Append "nodes/" and the path part of the VOSpace identifier:
472     <ul><li>http://some.uni.ac.uk/vospace/nodes/container-6/siap-out-1.vot?foo=bar
473     </li></ul>
474     </li></ul>
475     </p><p>
476     Note that any fragment identifier in the identifier SHOULD be removed
477     when resolving the identifier to a HTTP endpoint, consistent with
478     the implied semantics of URI fragments <a
479     href="fragref">[see here]</a>.
480     </p>
481    
482     <br/>
483     <h2><a name="sec3">3. VOSpace data model</a></h2>
484     <h3><a name="sec3_1">3.1 Nodes and node types</a></h3>
485     <p>We refer to the arrangement of data accessible through one particular VOSpace service as "a VOSpace".
486     </p><p>
487     Each data object within a VOSpace SHALL be represented as a node that is identified by a URI.
488     </p><p>
489     There are different types of nodes and the type of a VOSpace node determines how the VOSpace service stores and interprets the node data.
490     </p><p>
491     The types are arranged in a hierarchy (see Fig. 2), with more detailed types inheriting the structure of more generic types.
492     </p>
493    
494     <p>
495     <center>
496     <font size="-1">
497     <img src="vospace-node-hierarchy.png" width="600"/> <br />
498     <blockquote>
499     <strong>Figure 2. Node hierarchy</strong>
500     This shows the inheritance structure for the different types of nodes
501     in VOSpace.
502     </blockquote>
503     </font>
504     </center>
505     </p>
506    
507     <p>
508     The following types (and representations) are defined:
509     </p><ul>
510     <li> <i>Node</i> is the most basic type
511     <li> <i>ContainerNode</i> describes a data item that can contain other data items
512     <li> <i>DataNode</i> describes a data item stored in the VOSpace
513     <li> <i>UnstructuredDataNode</i> describes a data item for which the VOSpace does not understand the data format
514     <li> <i>StructuredDataNode</i> describes a data item for which the space understands the format and may make transformations that preserve the meaning of the data.
515     <li> <i>LinkNode</i> describes a node that points to another node.
516     </ul><p>
517     When data is stored and retrieved from an <i>UnstructuredDataNode</i>, the bit pattern read back SHALL be identical to that written.
518     </p><p>
519     When data is stored and retrieved from a <i>StructuredDataNode</i>, 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.
520     </p><p>
521     A Node representation SHALL have the following elements:
522     </p><ul>
523     <li> <i>uri</i>: the vos:// identifier for the node, URI-encoded
524     according to <a href="#ref3">RFC2396</a>
525     <li> <i>properties</i>: a set of metadata properties for the node
526     <li> <i>capabilities</i>: a third-party interface to a data object
527     </ul>
528    
529     <p>
530     In addition, a <i>DataNode</i> representation SHALL have the following elements:
531     </p><ul>
532     <li> <i>accepts</i>: a list of the views (data formats) that the node can accept
533     <li> <i>provides</i>: a list of the views (data formats) that the node can provide
534     <li> <i>busy</i>: a boolean flag to indicate that the data associated with the node cannot be accessed
535     </ul>
536     <p>
537     The <i>busy</i> flag is used to indicate that an internal operation is in progress, and the node data is not available.
538     </i>
539     <p>
540     A <i>ContainerNode</i> representation SHALL have the following
541     elements, in addition to those it inherits from the <i>Node</i>
542     representation:
543     </p><ul>
544     <li> <i>nodes</i>: a list of the direct children, if applicable,
545     that the container has. Each child is represented as a <i>node</i>
546     subelement containing its vos:// identifier, URI-encoded according
547     to <a href="#ref3">RFC2396</a>
548     </ul>
549     <p>
550     A <i>LinkNode</i> representation SHALL have the following elements, in addition to those it inherits from the <i>Node</i> representation:
551     </p><ul>
552     <li> <i>target</i>: the target URI, URI-encoded according to <a
553     href="#ref3">RFC2396</a>
554     </ul>
555     <p>
556     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.
557     </p><p>
558     The properties of a <i>LinkNode</i> do not propagate to the target of
559     the <i>LinkNode</i>, i.e., a property attached to a <i>LinkNode</i>
560     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 <i>LinkNode</i> pointing to the resource in question and then adds the annotations as properties of the LinkNode.
561     </p><p>
562     Both the <i>ContainerNode</i> and the <i>LinkNode</i> SHALL have no data bytes associated with them.
563     </p><p>
564     The set of node types defined by this standard is closed; new types may be introduced only via new versions of the standard.
565     </p><p>
566     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.
567     </p><p>
568     Note: This does not require all services to support all of the Node
569     types, just that it can process an XML request containing any of the
570     types. If the service receives a request for a type that it does not
571     support, the service SHOULD return a <i>TypeNotSupported</i> fault. The
572     service SHALL NOT throw an XML parser error if it receives a request
573     for a type that it does not support.
574     </p>
575    
576     <h3><a name="sec3_2">3.2 Properties</a></h3>
577     <p><i>Properties</i> are simple string-based metadata properties associated with a node. </p>
578     <p>
579     Individual <i>Properties</i> 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 <i>Properties</i>, or a single <i>Property</i> containing a URI or URL pointing to an external resource that contains the additional metadata.
580     </p><p>
581     A <i>Property</i> representation SHALL have the following elements:
582     <ul>
583     <li> <i>uri</i>: the <i>Property</i> identifier
584     <li> <i>value</i>: the string value of the <i>Property</i>
585     <li> <i>readOnly</i>: a boolean flag to indicate that the <i>Property</i> cannot be changed by the client
586     </ul>
587     <p>
588     Properties may be set by the client or the service.
589     </p>
590    
591     <h4><a name="sec3_2_1">3.2.1 Property values</a></h4>
592     <p>Unless they have special meaning to the service or client,
593     <i>Properties</i> are treated as simple string values.</p>
594    
595     <p>When a <i>Property</i> can take multiple values, e.g., a list of
596     groups which can access a particular resource, these SHOULD be
597     comma-separated, unless the property description
598     defines a specific delimiter.
599     </p>
600    
601     <p>Some <i>Properties</i> 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 <i>Properties</i> of a node. Any <i>Properties</i> that it does not understand can simply be stored as text strings.
602     </p>
603    
604     <h4><a name="sec3_2_2">3.2.2 Property identifiers</a></h4>
605     <p>Every new type of <i>Property</i> SHALL require a unique URI to identify the <i>Property</i> and its meaning.
606     </p><p>
607     The rules for the <i>Property</i> identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
608     </p>
609     <ul>
610     <li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my­namespace
611     <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
612     </ul><p>
613     The current VOSpace schema defines <i>Property</i> identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
614     </p><ul>
615     <li> A <i>Property</i> URI can be a simple URN, e.g. urn:my­property
616     </ul><p>
617     This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
618     </p><p>
619     For a production system, any new Properties SHOULD have unique URIs that can be resolved into to a description of the Property.
620     </p><p>
621     Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
622     </p><ul>
623     <li> ivo://my­registry/vospace/properties#my­property
624     </ul><p>
625     Using an IVO registry URI to identify Properties has two main advantages :
626     </p><ul>
627     <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
628     <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
629     </ul>
630    
631     <h4><a name="sec3_2_3">3.2.3 Property descriptions</a></h4>
632     <p>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.
633     </p><p>
634     A Property description SHOULD describe the data type and meaning of a Property.
635     </p><p>
636     A PropertyDescription SHOULD have the following members :
637     </p><ul>
638     <li> <i>uri</i>: the formal URI of the Property
639     <li> <i>DisplayName</i>: A display name for the Property
640     <li> <i>Description</i>: A text block describing the meaning and validation rules of the <i>Property</i>
641     </ul><p>
642     A <i>PropertyDescription</i> MAY have the following OPTIONAL members :
643     </p><ul>
644     <li> <i>UCD</i>: the Universal Content Descriptor (in the UCD1+ scheme) for the <i>Property</i>
645     <li> <i>Unit</i>: the unit of measurement of the Property
646     </ul>
647     <p>
648     The information in a Property description can be used to generate a UI for displaying and modifying the different types of Properties.
649     </p><p>
650     Note that at the time of writing, the schema for registering PropertyDescriptions in the IVO registry has not been finalized.
651     </p>
652    
653     <h5><a name="sec3_2_3_1">3.2.3.1 UI display name</a></h5>
654     <p>
655     If a client is unable to resolve a Property identifier into a description, then it may just display the identifier as a text string:
656     </p><ul>
657     <li> urn:modified­date
658     </ul><p>
659     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:
660     </p><ul>
661     <li> Last modification date of the node data
662     </ul>
663     <h5><a name="sec3_2_3_2">3.2.3.2 Property editors</a></h5>
664     <p>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.
665     </p><p>
666     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.
667     </p><p>
668     In the current version of the specification the rules for editing Properties are as follows:
669     </p><ul>
670     <li> A service MAY impose validation rules on the values of specific types of Properties
671     <li> If a client attempts to set a Property to an invalid value, then the service MAY reject the change
672     <li> Where possible, the validation rules for a type of Property SHOULD be defined in the Property description
673     </ul><p>
674     Future versions of the VOSpace specification may extend the PropertyDescription to include more specific machine readable validation rules for a Property type.
675     </p><p>
676     Note that at the time of writing, the schema for registering validation rules in PropertyDescriptions has not been finalized.
677     </p>
678     <h4><a name="sec3_2_4">3.2.4 Standard properties</a></h4>
679     <p>
680     Property URIs and PropertyDescriptions for the core set of Properties
681     are registered under a StandardKeyEnumeration resource [VOStd] in the
682     IVOA registry with the resource identifier ivo://ivoa.net/vospace/core.
683     The following URIs SHOULD be used to represent the service
684     properties:</p><ul>
685     <li> ivo://ivoa.net/vospace/core#title SHALL be used as the
686     property URI denoting a name given to the resource
687     <li> ivo://ivoa.net/vospace/core#creator SHALL be used as the
688     property URI denoting an entity primarily responsible for making the resource
689     <li> ivo://ivoa.net/vospace/core#subject SHALL be used as the
690     property URI denoting the topic of the resource
691     <li> ivo://ivoa.net/vospace/core#description SHALL be used as the
692     property URI denoting an account of the resource
693     <li> ivo://ivoa.net/vospace/core#publisher SHALL be used as the
694     property URI denoting an entity responsible for making the resource available
695     <li> ivo://ivoa.net/vospace/core#contributor SHALL be used as the
696     property URI denoting an entity responsible for making contributions
697     to this resource
698     <li> ivo://ivoa.net/vospace/core#date SHALL be used as the
699     property URI denoting a point or period of time associated with an
700     event in the lifecycle of the resource
701     <li> ivo://ivoa.net/vospace/core#type SHALL be used as the
702     property URI denoting the nature or genre of the resource
703     <li> ivo://ivoa.net/vospace/core#format SHALL be used as the
704     property URI denoting the file format, physical medium, or
705     dimensions of the resource
706     <li> ivo://ivoa.net/vospace/core#identifier SHALL be used as the
707     property URI denoting an unambiguous reference to the resource
708     within a given context
709     <li> ivo://ivoa.net/vospace/core#source SHALL be used as the
710     property URI denoting a related resource from which the described
711     resource is derived
712     <li> ivo://ivoa.net/vospace/core#language SHALL be used as the
713     property URI denoting a language of the resource
714     <li> ivo://ivoa.net/vospace/core#relation SHALL be used as the
715     property URI denoting a related resource
716     <li> ivo://ivoa.net/vospace/core#coverage SHALL be used as the
717     property URI denoting the spatial or temporal topic of the resource,
718     the spatial applicability of the resource, or the jurisdiction under
719     which the resource is relevant
720     <li> ivo://ivoa.net/vospace/core#rights SHALL be used as the
721     property URI denoting information about rights held in and over the resource
722     <li> ivo://ivoa.net/vospace/core#availableSpace SHALL be used as the
723     property URI denoting the amount of space available within a container
724     <li> ivo://ivoa.net/vospace/core#groupread SHALL be used as the
725     property URI denoting the list of groups which can only read this
726     resource (read-only)
727     <li> ivo://ivoa.net/vospace/core#groupwrite SHALL be used as the
728     property URI denoting the list of groups which can read and write to
729     this resource (read-write)
730     <li> ivo://ivoa.net/vospace/core#publicread SHALL be used as the
731     property URI denoting whether this resource is world readable (anon-read-only)
732     <li> ivo://ivoa.net/vospace/core#quota SHALL be used as the
733     property URI denoting the value of a system quota on the resource
734     <li> ivo://ivoa.net/vospace/core#length SHALL be used as the
735     property URI denoting the length or size of a resource
736     <li> ivo://ivoa.net/vospace/core#mtime SHALL be used as the property
737     URI denoting the data modification time
738     <li> ivo://ivoa.net/vospace/core#ctime SHALL be used as the property
739     URI denoting status change (aka metadata modification) time
740     <li> ivo://ivoa.net/vospace/core#btime SHALL be used as the property
741     URI denoting initial creation time
742    
743     </ul>
744     <p>However, this is not intended to be a closed list,
745     different implementations are free to define and use their own
746     Properties. </p>
747    
748     <h3><a name="sec3_3">3.3 Capabilities</a></h3>
749     <p>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.
750     </p><p>
751     A Capability representation SHALL have the following members:
752     </p><ul>
753     <li> uri: the Capability identifier
754     <li> endpoint: the endpoint URL to use for the third-party interface
755     <li> param: a set of parameters for the capability
756     </ul>
757    
758     <h4><a name="sec3_3_1">3.3.1 Example use cases</a></h4>
759     <p>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.
760     </p><p>
761     Another example is a DataNode that provides an iRODS capability so
762     that the data replication for this data object can be handled using
763     the iRODS service API.
764     </p>
765    
766     <h4><a name="sec3_3_2">3.3.2 Capability identifiers</a></h4>
767     <p>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.</p><ul>
768     <li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my-namespace
769     <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.
770     </ul>
771     <p>
772     The VOSpace schema defines Capability identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
773     </p><ul>
774     <li> A Capability URI can be a simple URN, e.g. urn:my-capability
775     </ul><p>
776     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:
777     </p><ul>
778     <li> ivo://my-registry/vospace/capabilities#my-capability
779     </ul>
780     <p>
781     Using an IVO registry URI to identify Capabilities has two main advantages:
782     </p>
783     <ul>
784     <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
785     <li> If the IVO registry URI points to a description registered in the
786     IVO registry, this provides a mechanism to discover how to use the Capability.
787     </ul>
788    
789     <h4><a name="sec3_3_3">3.3.3 Capability descriptions</a></h4>
790     <p>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.
791     </p><p>
792     A CapabilityDescription SHOULD describe the third-party interface and how it should be used in this context. A CapabilityDescription SHOULD have the following members:
793     </p><ul>
794     <li> <i>uri</i>: the formal URI of the Capability
795     <li> <i>DisplayName</i>: a simple display name of the Capability.
796     <li> <i>Description</i>: a text block describing the third-party interface and how it should be used in this context.
797     </ul><p>
798     Note that at the time of writing, the schema for registering CapabilityDescriptions in the IVO registry has not been finalized.
799     </p>
800    
801     <h4><a name="sec3_3_4">3.3.4 UI display name</a></h4>
802     <p>If a client is unable to resolve a Capability identifier into a description then it may just display the identifier as a text string:
803     </p><ul>
804     <li> Access data using urn:edu.sdsc.irods
805     </ul><p>
806     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:
807     </p><ul>
808     <li> Access data using iRODS
809     </ul>
810    
811     <h4><a name="sec3_3_5">3.3.5 Standard capabilities</a></h4>
812     <p>Capability URIs and CapabilityDescriptions for the core set of
813     Capabilities are registered under a StandardKeyEnumeration resource [VOStd] in the
814     IVOA registry with the resource identifier ivo://ivoa.net/vospace/core.. The following URIs SHALL be used to represent the service capabilities:
815     </p><ul>
816     <li> ivo://ivoa.net/vospace/core#vospace-1.0 SHALL be used as the capability URI for a VOSpace 1.0 service
817     <li> ivo://ivoa.net/vospace/core#vospace-1.1 SHALL be used as the capability URI for a VOSpace 1.1 service
818     <li> ivo://ivoa.net/vospace/core#vospace-2.0 SHALL be used as the capability URI for a VOSpace 2.0 service
819     </ul><p>
820     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.
821     </p><p>
822     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.
823     </p><p>
824     Other standard service interfaces will also be registered, e.g.
825     </p><ul>
826     <li> Cone Search
827     <li> SIAP
828     <li> SSAP
829     <li> TAP
830     </ul><p>
831     However, this is not intended to be a closed list and different implementations are free to define and use their own Capabilities.
832     </p>
833    
834     <h3><a name="sec3_4">3.4 Views</a></h3>
835     <p>A View describes the data formats and contents available for importing or exporting data to or from a VOSpace node.
836     </p><p>
837     The metadata for a DataNode contains two lists of Views.
838     </p><ul>
839     <li> <i>accepts</i> is a list of Views that the service can accept for importing data into the Node
840     <li> <i>provides</i> is a list of Views that the service can provide for exporting data from Node
841     </ul><p>
842     A View representation SHALL have the following members:
843     </p><ul>
844     <li> <i>uri</i>: the View identifier
845     <li> <i>original</i>: an optional boolean flag to indicate that the View preserves the original bit pattern of the data
846     <li> <i>param</i>: a set of name-value pairs that can be used to
847     specify additional arguments for the View
848     </ul>
849    
850     <h4><a name="sec3_4_1">3.4.1 Example use cases</a></h4>
851     <b>Simple file store</b>
852     <p>
853     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.
854     </p><p>
855     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
856     View for a Node.
857     </p><p>
858     For example:
859     </p><ul>
860     <li> A client imports a file into the service, specifying a View to describe the file contents
861     <li> The service stores the data as a binary file and keeps a record of the View
862     <li> The service can then use the View supplied by the client to describe the data to other clients
863     </ul><p>
864     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.
865     </p>
866    
867     <h5><a name="sec3_4_1_1">3.4.1.1 Database store</a></h5>
868     <p>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.
869     </p><p>
870     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.
871     </p><p>
872     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.
873     </p><p>
874     In order to support this, the service needs to be able to tell the client what Views of the data are available.
875     </p><p>
876     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'.
877     </p><p>
878     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.
879     </p><p>
880     So our example service may want to offer the following Views of a database table:
881     </p><ul>
882     <li> Table contents as FITS
883     <li> Table contents as VOTable
884    
885     <li> Table contents as zip containing FITS
886     <li> Table contents as zip containing VOTable
887    
888     <li> Table contents as tar.gz containing FITS
889     <li> Table contents as tar.gz containing VOTable
890    
891     <li> Table metadata as FITS
892     <li> Table metadata as VOTable
893     </ul><p>
894     The service would publish this information as a list of Views in the provides section of the metadata for each Node.
895     </p><p>
896     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.
897     </p>
898    
899     <h4><a name="sec3_4_2">3.4.2 View identifiers</a></h4>
900     <p>Every new type of View SHALL require a unique URI to identify the View and its content.
901     </p><p>
902     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.
903     </p><ul>
904     <li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my­namespace
905     <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
906     </ul><p>
907     The current VOSpace schema defines View identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
908     </p><ul>
909     <li> A View URI can be a simple URN, e.g. urn:my­view
910     </ul><p>
911     This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
912     </p><p>
913     For a production system, any new Views SHOULD have unique URIs that can be resolved into to a description of the View.
914     </p><p>
915     Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
916     </p><ul>
917     <li> ivo://my­registry/vospace/views#my­view
918     </ul><p>
919     Using an IVO registry URI to identify Views has two main advantages :
920     </p><ul>
921     <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
922     <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
923     </ul>
924    
925     <h4><a name="sec3_4_3">3.4.3 View descriptions</a></h4>
926     <p>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. </p>
927    
928     <p>A ViewDescription SHOULD describe the data format and/or content of the view.</p>
929    
930     <p>A ViewDescription SHOULD have the following members :
931     </p><ul>
932     <li> <i>Uri</i>: the formal URI of the View
933     <li> <i>DisplayName</i>: A simple text display name of the View
934     <li> <i>Description</i>: Text block describing the data format and content of the View
935     </ul>
936     <p>A ViewDescription MAY have the following optional members:</p>
937     <ul>
938     <li> MimeType : the standard MIME type of the View, if applicable
939 major.brian 2655 <li> Parameters : a list of required and option parameters the view accepts, if applicable
940 major.brian 2654 </ul><p>
941     However, at the time of writing, the schema for registering
942     ViewDescriptions in the IVO registry has not been finalized.</p>
943    
944     <h5><a name="sec3_4_3_1">3.4.3.1 UI display name</a></h5>
945     <p>If a client is unable to resolve a View identifier into a description, then it MAY just display the identifier as a text string: </p>
946     <ul>
947     <li> Download as urn:table.meta.fits
948     </ul><p>
949     If the client can resolve the View identifier into a description, then the client MAY use the
950     information in the description to display a human readable name and description of the View:
951     </p><ul>
952     <li> Download table metadata as FITS header
953     </ul>
954     <h5><a name="sec3_4_3_2">3.4.3.2 MIME types</a></h5>
955     <p>If a VOSpace service provides HTTP access to the data contained in
956     a Node, then if the ViewDescription contains a MimeType field, this
957     SHOULD be included in the appropriate header field of the HTTP
958     response. </p>
959    
960     <h4><a name="sec3_4_4">3.4.4 Default views</a></h4>
961     <p>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:
962     </p><ul>
963     <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
964     <li> ivo://ivoa.net/vospace/core#binaryview SHALL be used as the view URI to import or export data as a binary file
965     <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
966     </ul>
967    
968     <h5><a name="sec3_4_4_1">3.4.4.1 Default import view</a></h5>
969     <p>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.
970     </p><p>
971     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.
972     </p><p>
973     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.
974     </p>
975     <h5><a name="sec3_4_4_1">3.4.4.2 Default export view</a></h5>
976     <p>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.
977     </p><p>
978     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
979     within the service.
980     </p><p>
981     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.
982     </p>
983     <h4><a name="sec3_4_5">3.4.5 Container views</a></h4>
984 major.brian 2655 <p>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.
985 major.brian 2654 </p><p>
986     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.</p>
987     <h3><a name="sec3_5">3.5 Protocols</a></h3>
988     <p>A Protocol describes the parameters required to perform a data transfer using a particular protocol.
989     </p><p>
990     A Protocol representation SHALL have the following members:
991     </p><ul>
992     <li> <i>uri</i>: the Protocol identifier
993     <li> <i>endpoint</i>: the endpoint URL to use for the data transfer
994     additional arguments required for the transfer
995     </ul>
996 major.brian 2655 <p>A protocol representation MAY have the following members:
997     </p><ul>
998     <li> <i>param</i>: A list of name-value pairs that specify any
999     additional arguments requried for the transfer
1000     <li> <i>authType</i> The requested type of authentication method
1001     to be used
1002     </ul>
1003     <p>Note: <i>endpoint</i> will only contain a value after the response
1004     from the service is received.
1005     </p>
1006 major.brian 2654 <h4><a name="sec3_2_3_1">3.5.1 Protocol identifiers</a></h4>
1007     <p>Every new type of Protocol requires a unique URI to identify the Protocol and how to use it. </p>
1008    
1009     <p>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 </p><ul>
1010    
1011     <li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my­namespace
1012     <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
1013     </ul><p>
1014     The current VOSpace schema defines Protocol identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
1015     </p><ul>
1016     <li> A Protocol URI can be a simple URN, e.g. urn:my­protocol
1017     </ul><p>
1018     This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
1019     </p><p>
1020     For a production system, any new Protocols SHOULD have unique URIs that can be resolved into to a description of the Protocol.
1021     </p><p>
1022     Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry :
1023     </p><ul>
1024     <li> ivo://my­registry/vospace/protocols#my­protocol
1025     </ul><p>
1026     Using an IVO registry URI to identify Protocols has two main advantages:
1027     </p><ul>
1028     <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
1029     <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
1030     </ul>
1031    
1032     <h4><a name="sec3_5_2">3.5.2 Protocol descriptions</a></h4>
1033     <p>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. </p>
1034    
1035     <p>A ProtocolDescription SHOULD describe the underlying transport protocol, and how it should be used in this context. </p>
1036    
1037     <p>A ProtocolDescription SHOULD have the following members:</p>
1038     <ul>
1039     <li> <i>uri</i>: the formal URI of the Protocol
1040     <li> <i>DisplayName</i>: A simple display name of the Protocol
1041     <li> <i>Description</i>: Text block describing describing the underlying transport protocol, and how it should be used in this context
1042     </ul><p>
1043     However, at the time of writing, the schema for registering ProtocolDescriptions in the IVO registry has not been finalized.
1044     </p>
1045     <h5><a name="sec3_5_2_1">3.5.2.1 UI display name</a></h5>
1046     <p>If a client is unable to resolve a Protocol identifier into a description, then it MAY just display the identifier as a text string:
1047     </p><ul>
1048     <li> Download using urn:my­protocol
1049     </ul><p>
1050     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:
1051     </p><ul>
1052     <li> Download using standard HTTP GET
1053     </ul>
1054 major.brian 2655 <h4><a name="sec3_5_3">3.5.3 Standard protocols and authentication types</a></h4>
1055 major.brian 2654 <p>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:</p>
1056     <ul>
1057     <li> ivo://ivoa.net/vospace/core#httpget SHALL be used as the protocol URI for a HTTP GET transfer
1058     <li> ivo://ivoa.net/vospace/core#httpput SHALL be used as the protocol URI for a HTTP PUT transfer
1059     </ul><p>
1060 major.brian 2655 <p>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:</p>
1061     <ul>
1062     <li> ivo://ivoa.net/vospace/core#anon SHALL be used as the authentication type URI for no client authentication
1063     <li> ivo://ivoa.net/vospace/core#httpauth SHALL be used as the authentication type URI for HTTP userid password authentication
1064     <li> ivo://ivoa.net/vospace/core#x509 SHALL be used as the authentication type URI for X.509 certificate authentication
1065     <li> ivo://ivoa.net/vospace/core#cookie SHALL be used as the authentication type URI for session-based cookie authentication
1066 major.brian 2689 <li> ivo://ivoa.net/vospace/core#oauth SHALL be used as the authentication type URI for OAuth authentication
1067 major.brian 2655 </ul><p>
1068 major.brian 2654 However, this is not intended to be a closed list, different
1069     implementations are free to define and use their own transfer
1070 major.brian 2655 Protocols and authentication types.</p>
1071 major.brian 2654
1072     <h4><a name="sec3_5_4">3.5.4 Custom protocols</a></h4>
1073     <p>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. </p>
1074    
1075     <h5><a name="sec3_5_4_1">3.5.4.1 SRB gateway</a></h5>
1076     <p>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.
1077     </p><p>
1078     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.
1079     </p><p>
1080     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.
1081     </p><p>
1082     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.
1083     </p><p>
1084     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.
1085     </p><p>
1086     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. </p><p>
1087     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.
1088     </p><p>
1089     The two implementations would then be able use the common Protocol URI
1090     to negotiate data transfers using the SRB transport protocol.
1091     </p>
1092    
1093     <h5><a name="sec3_5_4_2">3.5.4.2 Local NFS transfers</a></h5>
1094     <p>Another example of a custom Protocol use case would to transfer data using the local NFS file system within an institute.
1095     </p><p>
1096     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.
1097     </p><p>
1098     In this case, the local system administrators could register a custom ProtocolDescription which described how to transfer data using their local NFS file system.
1099     </p><ul>
1100     <li> ivo://my.institute/vospace/protocols#internal­nfs
1101     </ul><p>
1102     Data transfers using this Protocol would be done using file:// URLs pointing to locations within the local NFS file system:
1103     </p><ul>
1104     <li> file:///net/host/path/file
1105     </ul><p>
1106     These URLs would only have meaning to services and applications located within the local network, and would not be usable from outside the network.
1107     </p><p>
1108     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.
1109     </p><p>
1110     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.
1111     </p><p>
1112     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.
1113     </p><p>
1114     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.
1115     </p><p>
1116     The two different Protocol URIs and ProtocolDescriptions describe how to use the same underlying transport protocol (NFS) in different contexts.
1117     </p><p>
1118     Enabling different groups to define, register and use their own custom
1119     Protocols in this way means that systems can be configured to use the
1120     best available transport protocols for transferring data, without
1121     conflicting with other systems who may be using similar a transport
1122     protocol in a different context.
1123     </p>
1124     <h3><a name="sec3_6">3.6 Transfers</a></h3>
1125     <p>A Transfer describes the details of a data transfer to or from a
1126     space.
1127     </p><p>
1128     A UWS Job representation [UWS] of a Transfer SHALL have the following parameters:
1129     </p><ul>
1130     <li> <i>target</i>: denotes the VOSpace node to/from which data is to be transferred
1131     <li> <i>direction</i>: denotes the direction of a data transfer
1132     <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.</ul>
1133     <li> <i>view</i>: denotes the requested View
1134     <ul><li> For the transfer to be valid, the specified View must match
1135     one of those listed in the accepts or provides list of the Node.
1136     <li>For an internal data transfer, this parameter is not required.</ul>
1137     <li> <i>protocol</i>: denotes the transfer protocol(s) to use
1138     <ul><li> A transfer may contain more than one protocol with different
1139     Protocol URIs.
1140     <li> For an internal data transfer, this parameter is not required.
1141     </ul>
1142     <li> <i>keepBytes</i>: denotes whether the source object is to be kept
1143     in an internal data transfer, i.e. distinguishes between a move and a copy
1144     <ul><li> For an external data transfer, this parameter is not required.</ul>
1145     </ul>
1146     <p>This representation will be used as a child of the <i>jobInfo</i>
1147     element in a UWS Job representation.</p>
1148    
1149    
1150     <p>The representation of the results of a Transfer SHALL have the following members:
1151     </p><ul>
1152     <li> <i>target</i>: denotes the VOSpace node to/from which data is to be transferred
1153     <li> <i>direction</i>: denotes the direction of a data transfer
1154     <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.</ul>
1155     <li> <i>view</i>: A View specifying the requested View
1156     <ul><li> For the transfer to be valid, the specified View must match
1157     one of those listed in the accepts or provides list of the Node
1158     <li>For an internal data transfer, this parameter is not required.</ul>
1159     <li> <i>protocol</i>: one or more Protocols specifying the transfer protocols to use
1160     <ul><li> A Transfer may contain more than one Protocol element with different Protocol URIs
1161     <li> A Transfer may contain more than one Protocol element with the
1162     same Protocol URI with different endpoints
1163     <li>For an internal data transfer, this parameter is not required.</ul></ul>
1164    
1165    
1166    
1167     <h4><a name="sec3_6_1">3.6.1 Service-initiated transfers</a></h4>
1168     <p>Two of the external data transfers (pullToVoSpace and pushFromVoSpace) rely on the server performing the data transfer itself.
1169     </p><p>
1170     The client constructs a Job request containing details of the View and one or more Protocol elements with valid endpoint addresses.
1171     </p><p>
1172     The service MAY ignore Protocols with URIs that it does not recognize.
1173     </p><p>
1174     If the server is unable to handle any of the requested Protocols in a Transfer request, then it SHALL respond with a fault.
1175     </p><p>
1176     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.
1177     </p><p>
1178     The service selects the first Protocol it wants to use from the list and attempts to transfer the data using the Protocol endpoint.
1179     </p><p>
1180     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.
1181     </p><p>
1182     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.
1183     </p><p>
1184     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.
1185     </p><p>
1186     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.
1187     </p><p>
1188     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.
1189     </p><p>
1190     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.
1191     </p>
1192     <h4><a name="sec3_6_2">3.6.2 Client-initiated transfers</a></h4>
1193     <p>Two of the VOSpace external transfer methods rely on an external actor performing the data transfer outside the scope of the service call.
1194     </p><p>
1195     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.
1196     </p><p>
1197     In effect, the client is sending a list of Protocols that it (the client) wants to use for the transfer.
1198     </p><p>
1199     The service MAY ignore Protocols with URIs that it does not recognize.
1200     </p><p>
1201 major.brian 2655 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.
1202 major.brian 2654 </p><p>
1203 major.brian 2655 If available, the service may choose to consult the authType in the Protocols to construct correct endpoints.
1204     </p><p>
1205 major.brian 2654 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.
1206     </p><p>
1207     In effect, the server is responding with the subset of the requested Protocols that it (the server) is prepared to offer.
1208     </p><p>
1209     If the server is unable to accept any of the requested Protocols, then it SHALL respond with a fault.
1210     </p><p>
1211     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.
1212     </p><p>
1213     The agent MAY ignore Protocols URIs that it does not recognize.
1214     </p><p>
1215     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.
1216     </p><p>
1217     If the first attempt fails, the agent MAY choose another Protocol from the list and re-try the transfer using that Protocol endpoint.
1218     </p><p>
1219     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.
1220     </p><p>
1221     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.
1222     </p><p>
1223     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.
1224     </p><p>
1225     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.
1226     </p><p>
1227     If none of the Protocol options succeed, then the transfer SHALL be
1228     considered to have failed and the status will be updated. </p>
1229    
1230     <h3><a name="sec3_7">3.7 Searches</a></h3>
1231     <p>A Search describes the details of data objects in the space which
1232     meet specified search criteria, i.e. that are the results of a
1233     submitted search request.</p>
1234     <p>
1235     A UWS Job representation of a Search SHALL have the following parameters:
1236     </p><ul>
1237     <li> <i>uri</i>: An OPTIONAL identifier indicating from which item to
1238     continue a search
1239     <li> <i>limit</i>: An OPTIONAL limit indicating the maximum number of results in the response
1240     <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</ul>
1241     <li> <i>detail</i>: The level of detail in the results
1242     <ul><li> min : The list contains the minimum detail for each Node with all optional parts removed - the node type should be returned
1243     <ul><li> e.g. &lt;node uri="vos://service/name" xsi:type="Node"/></ul>
1244     <li> max : The list contains the maximum detail for each Node, including any xsi:type specific extensions
1245     <li> properties : The list contains a basic node element with a list of properties for each Node with no xsi:type specific extensions. </ul>
1246     <li> <i>matches</i>: An OPTIONAL search string consisting of
1247     properties and values to match against and joined in conjunction (and) or disjunction (or).
1248     <ul><li>Each property-value pair consists of the uri identifying a
1249     particular property and a regular expression against which the
1250     property values are to be matched: 'uri' = 'regex'
1251     <li> The match pairs can be combined in conjunction and/or disjunction
1252     using 'and' and 'or' respectively. For example: "(property1 =
1253     'value1' and property2 = 'value2') or property3 = 'value3'".
1254     <li> The regex syntax SHALL comply with POSIX conventions.</ul>
1255     <li> <i>node </i>: An OPTIONAL URI(s) identifying the starting node
1256     for a search, i.e., the <i>matches</i> constraints are applied to this
1257     node and its children</ul>
1258     <p>This representation will be used as a child of the <i>jobInfo</i>
1259     element in a UWS Job representation. For example:</p>
1260     <pre>
1261     &lt;uws:jobInfo>
1262     &lt;vos:search>
1263     &lt;vos:detail>properties&lt;/vos:detail>
1264     &lt;vos:matches>ivo://ivoa.net/vospace/core#description='galax'&lt;/vos:matches>
1265     &lt;vos:search>
1266     &lt;uws:jobInfo>
1267     </pre>
1268    
1269    
1270     <p>The representation of the results of a Search SHALL have the
1271     following members:</p>
1272     <ul><li> <i>nodes</i>: A list containing zero or more Nodes of appropriate
1273     detail identifying the target URIs meeting the search criteria </ul>
1274     </ul>
1275    
1276     <h3><a name="sec3_8">3.8 REST bindings</a></h3>
1277     <p>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. </p>
1278     </p>
1279     <table>
1280     <tr>
1281     <td>/properties</td><td>the properties employed in the space</td></tr>
1282     <tr><td>/views</td><td>the views employed in the space</td></tr>
1283     <tr><td>/protocols</td><td>the protocols employed in the space</td></tr>
1284     <tr><td>/searches</td><td>the searches of the space</td></tr>
1285     <tr><td>/nodes/(node-path)</td><td>a Node under the nodes of the space</td></tr>
1286     <tr><td>/transfers</td><td>the transfers for the space</td></tr>
1287     <tr><td>/transfers/(job-id)/results/transferDetails</td><td>the transfer details for
1288     synchronous jobs</td></tr>
1289     </table>
1290     <p>
1291     The service implementor is free to choose the names given in
1292     parentheses above; the other names are part of the VOSpace 2.0
1293     standard.
1294     </p><p>
1295     The endpoint /sync is also defined to receive HTTP POST requests of
1296     synchronous transfer jobs. This should respond with a redirect to the transfer
1297     details for synchronous jobs resource: http://rest-endpoint/transfers/(jobid)/results/transferDetails. Synchronous transfers are
1298     limited to pushToVoSpace and pullFromVoSpace operations only where the
1299     client is requesting endpoint URLs where it can read or write data.
1300     </p><p>
1301 major.brian 2655 As an optimization, the /sync endpoint should support parameter-based
1302     HTTP POST transfer requests. Instead of returning a redirect to the transfer details,
1303     the parameter-based request to /sync returns the transferDetails document itself.
1304     As a further optimzation, if the parameter name value pair REQUEST=redirect is supplied,
1305 major.brian 2689 the /sync endpoint should issue a redirect to the first transfer endpoint that would be
1306 major.brian 2655 contained in the transfer details. In the case of an error with the optimized
1307     transfers, clients may wish to fall back to the HTTP POST to /sync and step through
1308     the entire transfer negotiation.
1309     </p><p>
1310 major.brian 2654 In addition, the following Nodes, appearing as part of a
1311     node-path, are reserved:
1312     </p>
1313     <ul>
1314     <li> .auto indicates that the service should auto-generate an endpoint
1315     URI to replace this placeholder (Note: that this is an OPTIONAL
1316     feature of a service)
1317     <li> .null indicates an endpoint that discards all data
1318     written to it and provides no data when read from, i.e. a bit
1319     bucket
1320     </ul>
1321     <p>
1322     The standardID for the service is:
1323     ivo://ivoa.net/std/VOSpace/v2.0. Available resources will then just be
1324     ivo://ivoa.net/std/VOSpace/v2.0#&lt;resourceName>, e.g., ivo://ivoa.net/std/VOSpace/v2.0#nodes.
1325     </p>
1326     <br/>
1327     <h2><a name="sec4">4 Access Control</a></h2>
1328 major.brian 2655 <p>
1329     VOSpace implementations may support any of the following authentication methods:
1330     <ul>
1331     <li>no authentication (anonymous clients)</li>
1332     <li>digital signatures with X.509 client certificates</li>
1333     <li>user ID and password HTTP authentication</li>
1334     <li>cookies</li>
1335 major.brian 2689 <li>OAuth (http://oauth.net)</li>
1336 major.brian 2655 </ul>
1337     When a client is requesting a transfer from the service, the authentication type (authType) may be supplied along side the list of transfer protocols.
1338     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
1339     encounter situations when the URL for data transfer will depend on the authentication type the client wished to use.
1340 major.brian 2654 </p><p>
1341     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.
1342     </p><p>
1343     A human-readable description of the implemented access policy must be declared in the registry metadata for the space.
1344     </p><p>
1345     These are the most probable access policies:
1346     </p><ul>
1347     <li> No access control is asserted. Any client can create, read, write and delete nodes anonymously
1348     <li> No authorization is required, but clients must authenticate an identity (for logging purposes) in each request to the space
1349     <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
1350     <li> Nodes are considered to be owned by the user who created them. Only the owner can operate on a node
1351     </ul><p>
1352     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. </p><p>
1353     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. </p>
1354     <br/>
1355     <h2><a name="sec4">5 Web service operations</a></h2>
1356 major.brian 2655 <p>A VOSpace 2.1 service SHALL be a REST service with the following operations:
1357 major.brian 2654 </p><p>
1358     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.
1359     </p><p>
1360     Note: When representing a Fault, the exact specified fault name SHALL
1361     be used. If this is followed by some details, the fault SHALL be
1362     separated from the subsequent characters by whitespace.
1363     </p>
1364     <p>
1365     Note: If the service is able to detect an internal system failure
1366     (associated with an HTTP 500 status code) then it should indicate this
1367     as described below if possible.
1368     </p>
1369     <h3><a name="sec5_1">5.1 Service metadata</a></h3>
1370     <p>These operations return comprehensive lists of service-level
1371     metadata, e.g. all protocols supported by the service. Individual
1372     nodes within a service, however, may not necessarily support all of
1373     these, i.e. only container nodes may support archive formats such as
1374     zip or tar.
1375     </p>
1376     <h4><a name="sec5_1_1">5.1.1 getProtocols</a></h4>
1377     <p>Get a list of the transfer Protocols supported by the space
1378     service</p>
1379     <h5><a name="sec5_1_1_1">5.1.1.1 Request</a></h5>
1380     <ul><li>A HTTP GET to http://rest-endpoint/protocols</ul>
1381     <h5><a name="sec5_1_1_2">5.1.1.2 Response</a></h5>
1382     <ul><li> A HTTP 200 status code
1383     <li> A Protocols representation giving:
1384     <ul><li> accepts: A list of Protocols that the service SHALL accept
1385     <ul><li> In this context 'accepting a protocol' means that the service SHALL act as a client for the protocol
1386     <li> e.g. 'accepting httpget' means the service can read data from an external HTTP web server </ul>
1387     <li> provides: A list of Protocols that the service SHALL provide
1388     <ul><li> In this context 'providing a protocol' means that the service SHALL act as a server for the protocol
1389     <li> e.g. 'providing httpget' means the service can act as a http web server </ul>
1390     </ul>
1391     </ul>
1392     <h5><a name="sec5_1_1_3">5.1.1.3 Faults</a></h5>
1393     <ul>
1394     <li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1395     </ul>
1396     <!-- 5.1.1.4 Example -->
1397     <div class="exampleOuter">
1398     <div class="exampleHeader">Example: getProtocols</div>
1399     <div class="exampleWrapper">
1400     <pre>> <b>curl -v http://localhost:8000/vospace-2.0/protocols</b></pre>
1401     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1402     <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
1403     > GET /protocols HTTP/1.1
1404     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1405     > Host: localhost:8000
1406     > Accept: */*
1407     >
1408     < HTTP/1.1 200 OK
1409     < Date: Tue, 09 Mar 2010 04:59:12 GMT
1410     < Content-Length: 309
1411     < Content-Type: text/html
1412     < Allow: GET, HEAD, POST, PUT
1413     < Server: CherryPy/3.1.2
1414     <
1415     &lt;protocols xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
1416     &lt;accepts>
1417     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
1418     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpput"/>
1419     &lt;/accepts>
1420     &lt;provides>
1421     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
1422     &lt;protocol uri="ivo://ivoa.net/vospace/core#httpput"/>
1423     &lt;/provides>
1424     &lt;/protocols>
1425     * Connection #0 to host localhost left intact
1426     * Closing connection #0</pre>
1427     </div></div>
1428     <h4><a name="sec5_1_2">5.1.2 getViews</a></h4>
1429     <p>Get a list of the <i>Views</i> and data formats supported by the
1430     space service</p>
1431     <h5><a name="sec5_1_2_1">5.1.2.1 Request</a></h5>
1432     <ul><li> A HTTP GET to http://rest-endpoint/views
1433     </ul>
1434     <h5><a name="sec5_1_2_2">5.1.2.2 Response</a></h5>
1435     <ul><li> A HTTP 200 status code
1436     <li> A Views representation giving:
1437     <ul><li> <i>accepts</i>: A list of Views that the service SHALL accept
1438     <ul><li> In this context 'accepting a view' means that the service SHALL receive input data in this format
1439     <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 </ul>
1440     <li><i>provides</i>: A list of Views that the service SHALL provide
1441     <ul><li> In this context 'providing a view' means that the service SHALL produce output data in this format
1442     <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
1443     </ul></ul>
1444     </ul>
1445     <h5><a name="sec5_1_2_3">5.1.2.3 Faults</a></h5>
1446     <ul>
1447     <li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1448     </ul>
1449     <!-- 5.1.2.4 Example -->
1450     <div class="exampleOuter">
1451     <div class="exampleHeader">Example: getViews</div>
1452     <div class="exampleWrapper">
1453     <pre>
1454     > <b>curl -v "http://localhost:8000/views"</b></pre>
1455     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1456     <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
1457     > GET /views HTTP/1.1
1458     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1459     > Host: localhost:8000
1460     > Accept: */*
1461     >
1462     < HTTP/1.1 200 OK
1463     < Date: Tue, 09 Mar 2010 19:36:17 GMT
1464     < Content-Length: 181
1465     < Content-Type: text/html
1466     < Allow: GET, HEAD, POST, PUT
1467     < Server: CherryPy/3.1.2
1468     <
1469     &lt;views xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
1470     &lt;accepts>
1471     &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/>
1472     &lt;/accepts>
1473     &lt;provides>
1474     &lt;view uri="ivo://ivoa.net/vospace/core#defaultview"/>
1475     &lt;/provides>
1476     &lt;/views>
1477     * Connection #0 to host localhost left intact
1478     * Closing connection #0
1479     </pre>
1480     </div></div>
1481     <h4><a name="sec5_1_3">5.1.3 getProperties</a></h4>
1482     <h5><a name="sec5_1_3_1">5.1.3.1 Request</a></h5>
1483     <ul><li> A HTTP GET to http://rest-endpoint/properties
1484     </ul>
1485     <h5><a name="sec5_1_3_2">5.1.3.2 Response</a></h5>
1486     <ul><li> A HTTP 200 status code
1487     <li> A Properties representation including:
1488     <ul><li> <i>accepts</i>: 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.
1489     <li> <i>provides</i>: A list of identifiers for the Properties that the service SHALL provide
1490     <li> <i>contains</i>: A list of identifiers for all the Properties currently used by Nodes within the service
1491     </ul>
1492     </ul>
1493     <h5><a name="sec5_1_3_3">5.1.3.3 Faults</a></h5>
1494     <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1495     </ul>
1496     <!-- 5.1.3.4 Example -->
1497     <div class="exampleOuter">
1498     <div class="exampleHeader">Example: getProperties</div>
1499     <div class="exampleWrapper">
1500     <pre>
1501     > <b>curl -v "http://localhost:8000/properties"</b></pre>
1502     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1503     <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
1504     > GET /properties HTTP/1.1
1505     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1506     > Host: localhost:8000
1507     > Accept: */*
1508     >
1509     < HTTP/1.1 200 OK
1510     < Date: Tue, 09 Mar 2010 19:43:23 GMT
1511     < Content-Length: 644
1512     < Content-Type: text/html
1513     < Allow: GET, HEAD, POST, PUT
1514     < Server: CherryPy/3.1.2
1515     <
1516     &lt;properties xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
1517     &lt;accepts>
1518     &lt;property uri="ivo://ivoa.net/vospace/core#title"/>
1519     &lt;property uri="ivo://ivoa.net/vospace/core#creator"/>
1520     &lt;property uri="ivo://ivoa.net/vospace/core#description"/>
1521     &lt;/accepts>
1522     &lt;provides>
1523     &lt;property uri="ivo://ivoa.net/vospace/core#availableSpace"/>
1524     &lt;property uri="ivo://ivoa.net/vospace/core#httpput"/>
1525     &lt;/provides>
1526     &lt;contains>
1527     &lt;property uri="ivo://ivoa.net/vospace/core#availableSpace"/>
1528     &lt;property uri="ivo://ivoa.net/vospace/core#title"/>
1529     &lt;property uri="ivo://ivoa.net/vospace/core#creator"/>
1530     &lt;property uri="ivo://ivoa.net/vospace/core#description"/>
1531     &lt;/contains>
1532     &lt;/properties>
1533     * Connection #0 to host localhost left intact
1534     * Closing connection #0
1535     </pre>
1536     </div></div>
1537     <h3><a name="sec5_2">5.2 Creating and manipulating data nodes</a></h3>
1538    
1539     <h4><a name="sec5_2_1">5.2.1 createNode</h4>
1540     <p>Create a new node at a specified location</p>
1541     <h5><a name="sec5_2_1_1">5.2.1.1 Request</a></h5>
1542     <ul><li> A HTTP PUT of a node representation to the node URL:
1543     <ul><li> <i>node</i>: A template Node (as defined in Section 3.1) for the node to be created
1544     </ul></ul><p>
1545     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.
1546     </p><p>
1547     If the Node xsi:type is not specified then a generic node of type Node is implied.
1548     </p><p>
1549     The permitted values of xsi:type are:
1550     </p><ul>
1551     <li> vos:Node
1552     <li> vos:DataNode
1553     <li> vos:UnstructuredDataNode
1554     <li> vos:StructuredDataNode
1555     <li> vos:ContainerNode
1556     <li> vos:LinkNode
1557     </ul><p>
1558     When creating a new Node the service MAY substitute a valid subtype, i.e. If xsi:type is
1559     set to vos:DataNode then this may be implemented as a DataNode, StructuredDataNode
1560     or an UnstructuredDataNode.
1561     </p><p>
1562     The properties of the new Node can be set by adding Properties to the template.
1563     Attempting to set a Property that the service considers to be 'readOnly' SHALL cause a
1564     PermissionDenied fault.
1565     The accepts and provides lists of Views for the Node cannot be set using this method.
1566     </p><p>
1567     The capabilities list for the Node cannot be set using this method.
1568     </p>
1569     <h5><a name="sec5_2_1_2">5.2.1.2 Response</a></h5>
1570     <ul><li> A HTTP 201 status code
1571     <li> A node representation including
1572     <ul><li> <i>node</i>: details of the new Node
1573     </ul></ul><p>
1574     The <i>accepts</i> list of Views for the Node SHALL be filled in by the service based on service
1575     capabilities.
1576     </p><p>
1577     The <i>provides</i> list of Views for the Node MAY not be filled in until some data has been
1578     imported into the Node.
1579     </p><p>
1580     The <i>capabilities</i> list for the Node MAY not be filled in until some data has been imported into the Node.
1581     </p>
1582     </ul>
1583     <h5><a name="sec5_2_1_3">5.2.1.3 Faults</a></h5>
1584     <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1585     <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
1586     <li> The service SHALL throw a HTTP 400 status code including an InvalidURI fault in the entity body if the requested URI is invalid
1587     <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
1588     <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
1589     <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.
1590     <ul><li> For example, given the URI path /a/b/c, the service must
1591     throw a HTTP 404 status code including a ContainerNotFound fault in
1592     the entity body if either /a or /a/b do not exist. </ul>
1593     <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.
1594     <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.
1595     </ul>
1596     </ul>
1597     <!-- 5.2.1.4 Example -->
1598     <div class="exampleOuter">
1599     <div class="exampleHeader">Example: createNode</div>
1600     <div class="exampleWrapper">
1601     <p>The node to be created (newNode.xml) is:</p>
1602     <pre>
1603     &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="vos:UnstructuredDataNode"
1604     xmlns="http://www.ivoa.net/xml/VOSpace/v2.0" uri="vos://nvo.caltech!vospace/mydata1">
1605     &lt;properties>
1606     &lt;property uri="ivo://ivoa.net/vospace/core#description">My important results&lt;/property>
1607     &lt;/properties>
1608     &lt;accepts/>
1609     &lt;provides/>
1610     &lt;capabilities/>
1611     &lt;/node>
1612     </pre>
1613     <pre>
1614     > <b>curl -v -X PUT -d @newNode.xml "http://localhost:8000/nodes/mydata1"</b></pre></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);"><pre>
1615     * Connected to localhost (127.0.0.1) port 8000 (#0)
1616     > PUT /nodes/mydata1 HTTP/1.1
1617     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1618     > Host: localhost:8000
1619     > Accept: */*
1620     > Content-Length: 267
1621     > Content-Type: application/x-www-form-urlencoded
1622     >
1623     < HTTP/1.1 200 Created
1624     < Date: Wed, 10 Mar 2010 00:10:27 GMT
1625     < Content-Length: 323
1626     < Content-Type: text/html
1627     < Allow: GET, HEAD, POST, PUT
1628     < Server: CherryPy/3.1.2
1629     <
1630     * Connection #0 to host localhost left intact
1631     * Closing connection #0
1632     &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1633     xmlns="http://www.ivoa.net/xml/VOSpace/v2.0" xsi:type="vos:UnstructuredDataNode"
1634     uri="vos://nvo.caltech!vospace/mydata1">
1635     &lt;properties>
1636     &lt;property uri="ivo://ivoa.net/vospace/core#description">My important results&lt;/property>
1637     &lt;/properties>
1638     &lt;accepts>
1639     &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/>
1640     &lt;/accepts>
1641     &lt;provides/>
1642     &lt;capabilities/>
1643     &lt;/node>
1644     </pre>
1645     </div></div>
1646     <h4><a name="sec5_2_2">5.2.2 moveNode</h4>
1647     <p>Move a node within a VOSpace service.
1648     </p><p>
1649     Note that this does not cover moving data between two separate VOSpace services.
1650     </p><p>
1651     Moving nodes between separate VOSpace services SHOULD be handled by the client, using the import, export and delete methods.
1652     </p><p>
1653     When the source is a ContainerNode, all its children (the contents of the container) SHALL also be moved to the new destination.
1654     </p><p>
1655     When the destination is an existing ContainerNode, the source SHALL be placed under it (i.e. within the container).
1656     </p>
1657     <p>The <i>Node</i> type cannot be changed using this method.</p>
1658    
1659     <h5><a name="sec5_2_2_1">5.2.2.1 Request</a></h5>
1660     <ul><li> A HTTP POST of a Job representation for the transfer (see
1661     section 3.6) to http://rest-endpoint/transfers.
1662     </ul><p>
1663     .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.
1664     </p>
1665     <h5><a name="sec5_2_2_2">5.2.2.2 Response</a></h5>
1666     <ul><li>The initial response is a HTTP 303 status code with the
1667     Location header keyword assigned to the created job.</li></ul>
1668     <p>If an autogenerated URI for the destination was specified in the
1669     request then its value SHALL be specified as a result in the Results
1670     List for the completed transfer with the id of "destination":
1671     </p>
1672     <pre>
1673     &lt;uws:job>
1674     ...
1675     &lt;uws:jobInfo>
1676     &lt;vos:direction>vos://nvo.caltech!vospace/mjg/.auto&lt;/vos:direction>
1677     ...
1678     &lt;uws:results>
1679     &lt;uws:result id="destination">vos://nvo.caltech!vospace/mjg/abc123&lt;/uws:result>
1680     &lt;/uws:results>
1681     ...
1682     &lt;/uws:job>
1683     </pre>
1684     <h5><a name="sec5_2_2_3">5.2.2.3 Faults</a></h5>
1685     <p>For all faults, the service shall set the PHASE to "ERROR" in the Job
1686     representation. The &lt;errorSummary&gt; element in the Job representation
1687     shall be set to the appropriate value for the fault type and the
1688     appropriate fault representation (see section 5.5) provided at the error URI:
1689     http://rest-endpoint/transfers/(jobid)/error.</p>
1690     <table>
1691     <tr><th align="left">Fault description</th><th
1692     align="left">errorSummary</th><th align="left">Fault representation</th></tr>
1693     <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
1694     <tr><td>User does not have permissions to perform the
1695     operation</td><td>Permission Denied</td><td>PermissionDenied</td></tr>
1696     <tr><td>Source node does not exist</td><td>Node Not Found</td><td>NodeNotFound</td></tr>
1697     <tr><td>Destination node already exists and it is not a
1698     ContainerNode</td><td>Duplicate Node</td><td>DuplicateNode</td></tr>
1699     <tr><td>A specified URI is invalid</td><td>Invalid
1700     URI</td><td>InvalidURI</td></tr>
1701     </table>
1702     <!-- 5.2.2.4 Example -->
1703     <div class="exampleOuter">
1704     <div class="exampleHeader">Example: moveNode</div>
1705     <div class="exampleWrapper">
1706     <p>The Job to be submitted (newJob.xml) is:</p>
1707     <pre>
1708     &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0" >
1709     &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
1710     &lt;vos:direction>vos://nvo.caltech!vospace/mydata2&lt;/vos:direction>
1711     &lt;vos:keepBytes>false&lt;/vos:keepBytes>
1712     &lt;/vos:transfer>
1713     </pre>
1714    
1715     <pre>
1716     > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"</b>
1717     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1718     <pre>
1719     * Connected to localhost (127.0.0.1) port 8000 (#0)
1720     > POST /transfers HTTP/1.1
1721     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1722     > Host: localhost:8000
1723     > Accept: */*
1724     > Content-Length: 762
1725     > Content-Type: application/x-www-form-urlencoded
1726     >
1727     < HTTP/1.1 303 See Other
1728     < Content-Length: 174
1729     < Server: CherryPy/3.1.2
1730     < Location: http://localhost:8080/transfers/ec200b5ff77641fb841978a85d1f7245
1731     < Allow: GET, HEAD, POST, PUT
1732     < Date: Thu, 11 Mar 2010 19:54:00 GMT
1733     < Content-Type: text/html
1734     <
1735     * Connection #0 to host localhost left intact
1736     * Closing connection #0
1737     This resource can be found at <a href='http://localhost:8000/transfers/ec200b5ff77641fb841978a85d1f7245'>http://localhost:8000/transfers/ec200b5ff77641fb841978a85d1f7245</a>.
1738     </pre></div>
1739     <div class="exampleWrapper">
1740     <p>The status of the job can now be polled at the job location:</p>
1741     <pre>
1742     > <b>curl -v "http://localhost:8000/transfers/ec200b5ff77641fb841978a85d1f7245"</b></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1743     <pre>
1744     * Connected to localhost (127.0.0.1) port 8000 (#0)
1745     > GET /transfers/ccfd4ba0dd9f4406b2039c4358ba8ef3 HTTP/1.1
1746     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1747     > Host: localhost:8000
1748     > Accept: */*
1749     >
1750     < HTTP/1.1 200 OK
1751     < Date: Thu, 11 Mar 2010 19:54:02 GMT
1752     < Content-Length: 802
1753     < Content-Type: text/html
1754     < Allow: GET, HEAD, POST, PUT
1755     < Server: CherryPy/3.1.2
1756     <
1757     &lt;uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
1758     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1759     xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0"
1760     xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd ">
1761     &lt;uws:jobId>ec200b5ff77641fb841978a85d1f7245&lt;/uws:jobId>
1762     &lt;uws:ownerId xsi:nil="true"/>
1763     &lt;uws:phase>EXECUTING&lt;/uws:phase>
1764     &lt;uws:startTime>2010-03-11T19:54:00.433058&lt;/uws:startTime>
1765     &lt;uws:endTime xsi:nil="true"/>
1766     &lt;uws:executionDuration>0&lt;/uws:executionDuration>
1767     &lt;uws:destruction xsi:nil="true"/>
1768     &lt;uws:jobInfo>
1769     &lt;vos:transfer>
1770     &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
1771     &lt;vos:direction>vos://nvo.caltech!vospace/mydata2&lt;/vos:direction>
1772     &lt;vos:keepBytes>false&lt;/vos:keepBytes>
1773     &lt;/vos:transfer>
1774     &lt;/uws:jobInfo>
1775     &lt;uws:results/>
1776     * Connection #0 to host localhost left intact
1777     * Closing connection #0
1778     &lt;/uws:job>
1779     </pre>
1780     </div></div>
1781    
1782     <h4><a name="sec5_2_3">5.2.3 copyNode</h4>
1783     <p>Copy a node with a VOSpace service.
1784     </p><p>
1785     Note that this does not cover copying data between two separate VOSpace services.
1786     </p><p>
1787     Copying nodes between separate VOSpace services SHOULD be handled by the client, using the import and export methods.
1788     </p><p>
1789     When the source is a ContainerNode, all its children (the full contents of the container) SHALL get copied, i.e. this is a deep recursive copy.
1790     </p><p>
1791     When the destination is an existing ContainerNode, the copy SHALL be placed under it (i.e. within the container).
1792     </p>
1793     <p>The <i>Node</i> type cannot be changed using this method.</p>
1794     <h5><a name="sec5_2_3_1">5.2.3.1 Request</a></h5>
1795     <ul><li> A HTTP POST of a Job representation for the transfer (see
1796     section 3.6) to http://rest-endpoint/transfers.</ul>
1797     <p>
1798     .auto is the reserved URI to indicate an auto-generated 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.
1799     </p>
1800     <h5><a name="sec5_2_3_2">5.2.3.2 Response</a></h5>
1801     <ul><li>The initial response is a HTTP 303 status code with the
1802     Location header keyword assigned to the created job.</li></ul>
1803     <p>If an autogenerated URI for the destination was specified in the
1804     request then its value SHALL be specified as a result in the Results
1805     List for the completed transfer with the id of "destination":
1806     </p>
1807     <pre>
1808     &lt;uws:job>
1809     ...
1810     &lt;uws:jobInfo>
1811     &lt;vos:direction>vos://nvo.caltech!vospace/mjg/.auto&lt;/vos:direction>
1812     ...
1813     &lt;uws:results>
1814     &lt;uws:result id="destination">vos://nvo.caltech!vospace/mjg/abc123&lt;/uws:result>
1815     &lt;/uws:results>
1816     ...
1817     &lt;/uws:job>
1818     </pre>
1819     <h5><a name="sec5_2_3_3">5.2.3.3 Faults</a></h5>
1820     <p>For all faults, the service shall set the PHASE to "ERROR" in the Job
1821     representation. The &lt;errorSummary&gt; element in the Job representation
1822     shall be set to the appropriate value for the fault type and the
1823     appropriate fault representation (see section 5.5) provided at the error URI:
1824     http://rest-endpoint/transfers/(jobid)/error.</p>
1825     <table>
1826     <tr><th align="left">Fault description</th><th
1827     align="left">errorSummary</th><th align="left">Fault representation</th></tr>
1828     <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
1829     <tr><td>User does not have permissions to perform the
1830     operation</td><td>Permission Denied</td><td>PermissionDenied</td></tr>
1831     <tr><td>Source node does not exist</td><td>Node Not Found</td><td>NodeNotFound</td></tr>
1832     <tr><td>Destination node already exists and it is not a
1833     ContainerNode</td><td>Duplicate Node</td><td>DuplicateNode</td></tr>
1834     <tr><td>A specified URI is invalid</td><td>Invalid
1835     URI</td><td>InvalidURI</td></tr>
1836     </table>
1837    
1838     <!-- 5.2.3.4 Example -->
1839     <div class="exampleOuter">
1840     <div class="exampleHeader">Example: copyNode</div>
1841     <div class="exampleWrapper">
1842     <p>The Job to be submitted (newJob.xml) is:</p>
1843     <pre>
1844     &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0">
1845     &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
1846     &lt;vos:direction>vos://nvo.caltech!vospace/mydir/.auto&lt;/vos:direction>
1847     &lt;vos:keepBytes>true&lt;/vos:keepBytes>
1848     &lt;/vos:transfer>
1849     </pre>
1850    
1851     <pre>
1852     > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"</b>
1853     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1854     <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
1855     > POST /transfers HTTP/1.1
1856     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1857     > Host: localhost:8000
1858     > Accept: */*
1859     > Content-Length: 765
1860     > Content-Type: application/x-www-form-urlencoded
1861     >
1862     < HTTP/1.1 303 See Other
1863     < Content-Length: 174
1864     < Server: CherryPy/3.1.2
1865     < Location: http://localhost:8080/transfers/6fbb28afec94417ba256d705f5e1f966
1866     < Allow: GET, HEAD, POST, PUT
1867     < Date: Thu, 11 Mar 2010 21:28:19 GMT
1868     < Content-Type: text/html
1869     <
1870     * Connection #0 to host localhost left intact
1871     * Closing connection #0
1872     This resource can be found at <a href='http://localhost:8000/transfers/6fbb28afec94417ba256d705f5e1f966'>http://localhost:8000/transfers/6fbb28afec94417ba256d705f5e1f966</a>.
1873     </pre></div>
1874     <div class="exampleWrapper">
1875    
1876     <p>The status of the job can now be polled at the job location:</p>
1877     <pre>
1878     > <b>curl -v "http://localhost:8000/transfers/63fa39fb18f244c18c991ed2f96d26cd"</b></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);"><pre>
1879     * Connected to localhost (127.0.0.1) port 8000 (#0)
1880     > GET /transfers/63fa39fb18f244c18c991ed2f96d26cd HTTP/1.1
1881     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1882     > Host: localhost:8000
1883     > Accept: */*
1884     >
1885     < HTTP/1.1 200 OK
1886     < Date: Thu, 11 Mar 2010 21:28:21 GMT
1887     < Content-Length: 950
1888     < Content-Type: text/html
1889     < Allow: GET, HEAD, POST, PUT
1890     < Server: CherryPy/3.1.2
1891     <
1892     &lt;uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
1893     xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1894     xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd ">
1895     &lt;uws:jobId>6fbb28afec94417ba256d705f5e1f966&lt;/uws:jobId>
1896     &lt;uws:ownerId xsi:nil="true"/>
1897     &lt;uws:phase>COMPLETED&lt;/uws:phase>
1898     &lt;uws:startTime>2010-03-11T21:28:19.200324&lt;/uws:startTime>
1899     &lt;uws:endTime>2010-03-11T21:28:19.200529&lt;/uws:endTime>
1900     &lt;uws:executionDuration>0&lt;/uws:executionDuration>
1901     &lt;uws:destruction xsi:nil="true"/>
1902     &lt;uws:jobInfo>
1903     &lt;vos:transfer>
1904     &lt;vos:keepBytes>true&lt;/vos:keepBytes>
1905     &lt;vos:direction>vos://nvo.caltech!vospace/mydir/.auto&lt;/vos:direction>
1906     &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
1907     &lt;/vos:transfer>
1908     &lt;uws:jobInfo>
1909     &lt;uws:results>
1910     &lt;uws:result id="destination" xlink:href="vos://nvo.caltech!vospace/mydir/ef9ce281f5bd4bff92c8991580cddff4"/>
1911     &lt;/uws:results>
1912     * Connection #0 to host localhost left intact
1913     * Closing connection #0
1914     &lt;/uws:job>
1915     </pre></div></div>
1916    
1917     <h4><a name="sec5_2_4">5.2.4 deleteNode</h4>
1918     <p>Delete a node.</p>
1919    
1920     <p>When the target is a ContainerNode, all its children (the contents of the container) SHALL also be deleted.</p>
1921    
1922     <p>Note that the same operation can also be achieved with a moveNode
1923     (see 5.2.2) with a .null node as the direction (destination node).</p>
1924    
1925     <h5><a name="sec5_2_4_1">5.2.4.1 Request</a></h5>
1926     <ul> <li> A HTTP DELETE to the URL of an existing node
1927     </ul>
1928     <h5><a name="sec5_2_4_2">5.2.4.2 Response</a></h5>
1929     <ul><li> A HTTP 204 status code
1930     </ul>
1931     <h5><a name="sec5_2_4_3">5.2.4.3 Faults</a></h5>
1932     <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
1933     <li> The service SHALL throw a HTTP 401 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
1934     <li> The service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if the target node does not exist
1935     <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
1936     <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.</ul>
1937     <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.
1938     <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.</ul>
1939     <li> If the target node in the URI path does not exist, the service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body.
1940     <ul><li> For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if /a/b/c does not exist.
1941     </ul>
1942     </ul>
1943    
1944     <!-- 5.2.4.4 Example -->
1945     <div class="exampleOuter">
1946     <div class="exampleHeader">Example: deleteNode</div>
1947     <div class="exampleWrapper">
1948     <pre>
1949     > <b>curl -v -X DELETE "http://localhost:8000/nodes/mydata1"</b></pre>
1950     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1951     <pre>
1952     * Connected to localhost (127.0.0.1) port 8000 (#0)
1953     > DELETE /nodes/mydata1 HTTP/1.1
1954     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1955     > Host: localhost:8000
1956     > Accept: */*
1957     >
1958     < HTTP/1.1 200 OK
1959     < Date: Thu, 11 Mar 2010 22:08:22 GMT
1960     < Content-Length: 0
1961     < Content-Type: text/html
1962     < Allow: DELETE, GET, HEAD, POST, PUT
1963     < Server: CherryPy/3.1.2
1964     <
1965     * Connection #0 to host localhost left intact
1966     * Closing connection #0
1967     </pre>
1968     </div></div>
1969    
1970     <h3><a name="sec5_3">5.3 Accessing metadata</a></h3>
1971    
1972     <h4><a name="sec5_3_1">5.3.1 getNode</h4>
1973     <p>Get the details for a specific Node.</p>
1974     <h5><a name="sec5_3_1_1">5.3.1.1 Request</a></h5>
1975     <ul><li> A HTTP GET to the URL of an existing node
1976     http://rest-endpoint/nodes/path
1977     </li></ul>
1978     <p>This can take the optional parameters to control the size of the response:</p>
1979     <ul>
1980     <li><i>detail</i> with values of:
1981     <ul><li>min: the returned record for the node contains minimum
1982     detail with all optional parts removed - the node type should be
1983     returned
1984     <ul><li>e.g. &lt;Node uri="vos://service/name" xsi:type="Node"/></ul>
1985     <li>max: the returned record for the node contains the maximum
1986     detail, including any xsi:type specific extensions
1987     <li>properties: the returned record for the node contains the
1988     basic node element with a list of properties but no xsi:type
1989     specific extensions
1990     </ul>
1991     <li><i>uri</i> with a value of a VOSpace identifier, URI-encoded
1992     according to RFC2396
1993     <li><i>limit</i> with an integer value indicating the maximum number of results in the response.
1994     <ul><li>No limit indicates a request for an unpaged list. However the
1995     server MAY still impose its own limit on the size of an individual
1996     response, splitting the results into more than one page if required/ </ul>
1997     </ul>
1998    
1999     <p>
2000     The list of supported protocols for a node can be retrieved with:</p>
2001     <ul>
2002     <li> A HTTP POST of an empty protocol representation to the URL of an
2003     existing node http://rest-endpoint/nodes/path
2004     </ul>
2005     <h5><a name="sec5_3_1_2">5.3.1.2 Response</a></h5>
2006     <ul><li> A HTTP 200 status code and a Node representation in the entity-body
2007     </ul><p>
2008     When no parameters are present in the request, the full expanded
2009     record for the node SHALL be returned, including any xsi:type specific
2010     extensions; otherwise the appropriate form for the specified value of
2011     the "detail" parameter SHALL be returned.
2012     </p>
2013     <p>When the node is a container, the returned record will also contain
2014     a list of direct children nodes in the container (as &lt;node>
2015     subelements under the &lt; nodes> element).</p>
2016     <p>If a "uri" and "offset" are specified in the request then the returned
2017     list will consist of the subset of children which begins at the node
2018     matching the specified value of the "uri" parameter and with
2019     cardinality matching the specified value of the "offset" parameter
2020     drawn from an ordered sequence of all children. The ordering is
2021     determined by the server but results must always be drawn from the
2022     same ordered sequence.
2023     <h5><a name="sec5_3_1_3">5.3.1.3 Faults</a></h5>
2024     <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
2025     <li> The service SHALL throw a HTTP 401 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
2026     <li> The service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if the target Node does not exist
2027     </ul>
2028    
2029     <!-- 5.3.1.4 Example -->
2030     <div class="exampleOuter">
2031     <div class="exampleHeader">Example: getNode</div>
2032     <div class="exampleWrapper">
2033     <pre>
2034     > <b>curl -v "http://localhost:8000/nodes/mydir?detail=min&uri=vos://nvo.caltech!vospace/mydir/ngc3401"</b></pre>
2035     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2036     <pre>
2037     * Connected to localhost (127.0.0.1) port 8000 (#0)
2038     > GET /nodes/mydir?detail=min&uri=vos://nvo.caltech!vospace/mydir/ngc3401 HTTP/1.1
2039     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2040     > Host: localhost:8000
2041     > Accept: */*
2042     >
2043     < HTTP/1.1 200 OK
2044     < Date: Fri, 12 Mar 2010 04:05:39 GMT
2045     < Content-Length: 593
2046     < Content-Type: text/html
2047     < Allow: DELETE, GET, HEAD, POST, PUT
2048     < Server: CherryPy/3.1.2
2049     <
2050     &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2051     xsi:type="vos:ContainerNode" uri="vos://nvo.caltech!vospace/mydir"
2052     xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
2053     &lt;properties>
2054     &lt;property uri="ivo://ivoa.net/vospace/core#description">My award winning images&lt;/property>
2055     &lt;/properties>
2056     &lt;accepts>
2057     &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/>
2058     &lt;/accepts>
2059     &lt;provides>
2060     &lt;view uri="ivo://ivoa/net/vospace/core#defaultview"/>
2061     &lt;/provides>
2062     &lt;capabilities/>
2063     &lt;nodes>
2064     &lt;node uri="vos://nvo.caltech!vospace/mydir/ngc4323"/>
2065     &lt;node uri="vos://nvo.caltech!vospace/mydir/ngc5796"/>
2066     &lt;node uri="vos://nvo.caltech!vospace/mydir/ngc6801"/>
2067     &lt;/nodes>
2068     &lt;/node>
2069     * Connection #0 to host localhost left intact
2070     * Closing connection #0
2071     </pre>
2072     </div></div>
2073     <h4><a name="sec5_3_2">5.3.2 setNode</h4>
2074     <p>Set the property values for a specific Node</p>
2075    
2076     <h5><a name="sec5_3_2_1">5.3.2.1 Request</a></h5>
2077     <ul><li> A HTTP POST of a Node representation to the URL of an existing node http://rest-endpoint/nodes/path including:
2078     <ul><li> node: A Node containing the Node uri and a list of the Properties to set (as defined in section 3.1)
2079     </ul></ul><p>
2080     This will add or update the node properties including any xsi:type specific elements.
2081     </p><p>
2082     The operation is the union of existing values and new ones.
2083     </p><p>
2084     <li> An empty value sets the value to blank.
2085     <li> To delete a Property, set the xsi:nil attribute to true
2086     </p><p>
2087     This method cannot be used to modify the Node type.
2088     </p><p>
2089     This method cannot be used to modify the accepts or provides list of Views for the Node.
2090     </p>
2091     <p>This method cannot be used to create children of a container Node.</p>
2092     <h5><a name="sec5_3_2_2">5.3.2.2 Response</a></h5>
2093     <ul<li> A HTTP 200 status code and a Node representation in the entity-body
2094     </ul><p>
2095     The full expanded record for the node SHALL be returned, including any xsi:type specific extensions.
2096     </p>
2097     <h5><a name="sec5_3_2_3">5.3.2.3 Faults</a></h5>
2098     <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
2099     <li> The service SHALL throw a HTTP 401 status code including a PermissionDenied fault in the entity-body if the request attempts to modify a read-only Property
2100     <li> The service SHALL throw a HTTP 401 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
2101     <li> The service SHALL throw a HTTP 404 status code including a
2102     NodeNotFound fault in the entity-body if the target Node does not
2103     exist
2104     <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
2105     <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.</ul>
2106     <li> The service SHALL throw a HTTP 400 status code including an InvalidArgument fault in the entity-body if a specified property value is invalid
2107     </ul>
2108    
2109     <!-- 5.3.2.4 Example -->
2110     <div class="exampleOuter">
2111     <div class="exampleHeader">Example: setNode</div>
2112     <div class="exampleWrapper">
2113     <p>The updated node (newNode.xml) is:</p>
2114     <pre>
2115     &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2116     xsi:type="vos:UnstructuredDataNode"
2117     uri="vos://nvo.caltech!vospace/mydata1"
2118     xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
2119     &lt;properties>
2120     &lt;property uri="ivo://ivoa.net/vospace/core#date">2010-03-12&lt;/property>
2121     &lt;/properties>
2122     &lt;accepts/>
2123     &lt;provides/>
2124     &lt;capabilities/>
2125     &lt;/node>
2126     </pre>
2127     <pre>
2128     > <b>curl -v -X POST -d @newNode.xml "http://localhost:8000/nodes/mydata1"</b>
2129     </pre></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2130     <pre>
2131     * Connected to localhost (127.0.0.1) port 8000 (#0)
2132     > POST /nodes/mydata1 HTTP/1.1
2133     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2134     > Host: localhost:8000
2135     > Accept: */*
2136     > Content-Length: 309
2137     > Content-Type: application/x-www-form-urlencoded
2138     >
2139     < HTTP/1.1 200 OK
2140     < Date: Fri, 12 Mar 2010 18:49:25 GMT
2141     < Content-Length: 445
2142     < Content-Type: text/html
2143     < Allow: DELETE, GET, HEAD, POST, PUT
2144     < Server: CherryPy/3.1.2
2145     <
2146     &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2147     xsi:type="vos:UnstructuredDataNode" uri="vos://nvo.caltech!vospace/mydata1"
2148     xmlns="http://www.ivoa.net/xml/VOSpace/v2.0" busy="false">
2149     &lt;properties>
2150     &lt;property uri="ivo://ivoa.net/vospace/core#description">My important results&lt;/property>
2151     &lt;property uri="ivo://ivoa.net/vospace/core#date">2010-03-12&lt;/property>
2152     &lt;/properties>
2153     &lt;accepts>
2154     &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/>
2155     &lt;/accepts>
2156     &lt;provides/>
2157     &lt;capabilities/>
2158     &lt;/node>
2159     * Connection #0 to host localhost left intact
2160     * Closing connection #0
2161     </pre></div></div>
2162    
2163     <h4><a name="sec5_3_3">5.3.3 findNodes</h4>
2164     <p>Find nodes whose properties match the specified values.
2165     </p><p>
2166     This operation is OPTIONAL.
2167     </p>
2168     <h5><a name="sec5_3_3_1">5.3.3.1 Request</a></h5>
2169     <ul><li> A HTTP POST of a Job representation of a Search (see section
2170     3.7) to http://rest-endpoint/searches
2171     </ul>
2172     <p>
2173     A null value of the "matches" parameter implies a full listing of the space.
2174     </p>
2175     </ul>
2176     <h5><a name="sec5_3_3_2">5.3.3.2 Response</a></h5>
2177     <ul><li>The initial response is a HTTP 303 status code with the
2178     Location header keyword assigned to the created job.
2179     </li></ul>
2180     <p>The search results representation can be retrieved directly from the
2181     link reported in the Results List, available from the results endpoint -
2182     http://rest-endpoint/searches/(jobid)/results -, the standard UWS location
2183     under the results endpoint - http://rest-endpoint/searches/(jobid)/results/searchDetails - (which may well just be a redirect to the
2184     former link), or as part of the full Job representation from
2185     http://rest-endpoint/searches/(jobid). The result element in the
2186     Results List SHALL have an id of "searchDetails":</p>
2187     <pre>
2188     &lt;uws:job>
2189     ...
2190     &lt;uws:results>
2191     &lt;uws:result id="searchDetails" xlink:href="http://rest-endpoint/searches/(jobid)/results/listing1"/>
2192     &lt;/uws:results>
2193     ...
2194     &lt;/uws:job>
2195     </pre>
2196    
2197     <h5><a name="sec5_3_3_3">5.3.3.3 Faults</a></h5>
2198     <p>For all faults, the service shall set the PHASE to "ERROR" in the Job
2199     representation. The &lt;errorSummary&gt; element in the Job representation
2200     shall be set to the appropriate value for the fault type and the
2201     appropriate fault representation (see section 5.5) provided at the error URI:
2202     http://rest-endpoint/transfers/(jobid)/error.</p>
2203     <table>
2204     <tr><th align="left">Fault description</th><th
2205     align="left">errorSummary</th><th align="left">Fault representation</th></tr>
2206     <tr><td>Operation not supported</td><td>Operation Not Supported</td><td>OperationNotSupported</td></tr>
2207     <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
2208     <tr><td>User does not have permissions to perform the
2209     operation</td><td>Permission
2210     Denied</td><td>PermissionDenied</td></tr>
2211     <tr><td>A particular property is specified and does not exist in the
2212     space</td><td>Property Not Found</td><td>PropertyNotFound</td></tr>
2213     </table>
2214    
2215     <!-- 5.3.3.4 Example -->
2216    
2217     <div class="exampleOuter">
2218     <div class="exampleHeader">Example: findNodes</div>
2219     <div class="exampleWrapper">
2220     <p>The Job to be submitted (newJob.xml) is:</p>
2221     <pre>&lt;vos:search xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0">
2222     &lt;vos:detail>properties&lt;/vos:detail>
2223     &lt;vos:matches>ivo://ivoa.net/vospace/core#description='galax'&lt;/vos:matches>
2224     &lt;vos:search>
2225     </pre>
2226     <pre>
2227     > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/searches"</b></pre>
2228     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2229     <pre>
2230     * Connected to localhost (127.0.0.1) port 8000 (#0)
2231     > POST /searches HTTP/1.1
2232     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2233     > Host: localhost:8000
2234     > Accept: */*
2235     > Content-Length: 684
2236     > Content-Type: application/x-www-form-urlencoded
2237     >
2238     < HTTP/1.1 303 See Other
2239     < Content-Length: 172
2240     < Server: CherryPy/3.1.2
2241     < Location: http://localhost:8080/searches/8c5b0f78cd5a44af8694f10da1b92060
2242     < Allow: DELETE, GET, HEAD, POST, PUT
2243     < Date: Fri, 12 Mar 2010 19:50:12 GMT
2244     < Content-Type: text/html
2245     <
2246     * Connection #0 to host localhost left intact
2247     * Closing connection #0
2248     This resource can be found at <a href='http://localhost:8080/searches/8c5b0f78cd5a44af8694f10da1b92060'>http://localhost:8080/searches/8c5b0f78cd5a44af8694f10da1b92060</a>
2249     </pre></div>
2250     <div class="exampleWrapper">
2251     <p>The status of the job can now be polled at the job location:</p>
2252     <pre>
2253     > <b>curl -v "http://localhost:8000/searches/8c6e7bc53ee848638cda35817e47da65"</b></pre></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2254     <pre>
2255     * Connected to localhost (127.0.0.1) port 8000 (#0)
2256     > GET /searches/8c6e7bc53ee848638cda35817e47da65 HTTP/1.1
2257     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2258     > Host: localhost:8000
2259     > Accept: */*
2260     >
2261     < HTTP/1.1 200 OK
2262     < Date: Fri, 12 Mar 2010 19:51:24 GMT
2263     < Content-Length: 891
2264     < Content-Type: text/html
2265     < Allow: DELETE, GET, HEAD, POST, PUT
2266     < Server: CherryPy/3.1.2
2267     <
2268     &lt;uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
2269     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd ">
2270     &lt;uws:jobId>8c6e7bc53ee848638cda35817e47da65&lt;</uws:jobId>
2271     &lt;uws:ownerId xsi:nil="true"/>
2272     &lt;uws:phase>COMPLETED&lt;/uws:phase>
2273     &lt;uws:startTime>2010-03-12T19:50:56.552278&lt;/uws:startTime>
2274     &lt;uws:endTime>2010-03-12T19:50:56.562416&lt;/uws:endTime>
2275     &lt;uws:executionDuration>0&lt;/uws:executionDuration>
2276     &lt;uws:destruction xsi:nil="true"/>
2277     &lt;uws:jobInfo>
2278     &lt;vos:search>
2279     &lt;vos:detail>properties&lt;/vos:detail>
2280     &lt;vos:matches>ivo://ivoa.net/vospace/core#description='galax'&lt;/vos:matches>
2281     &lt;vos:search>
2282     &lt;uws:jobInfo>
2283     &lt;uws:results>
2284     &lt;uws:result id="searchDetails" xlink:href="http://localhost:8000/searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1"/>
2285     &lt;/uws:results>
2286     &lt;/uws:job>
2287     * Connection #0 to host localhost left intact
2288     * Closing connection #0
2289     </pre></div>
2290     <div class="exampleWrapper">
2291     <p>Once the Job has completed, the result can be obtained from the URL
2292     reported in the result element:</p>
2293     <pre>
2294     > <b>curl -v "http://localhost:8000/searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1"</b></pre>
2295     </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2296     <pre>
2297     * Connected to localhost (127.0.0.1) port 8000 (#0)
2298     > GET /searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1 HTTP/1.1
2299     > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2300     > Host: localhost:8000
2301     > Accept: */*
2302     >
2303     < HTTP/1.1 200 OK
2304     < Date: Fri, 12 Mar 2010 20:29:25 GMT
2305     < Content-Length: 586
2306     < Content-Type: text/html
2307     < Allow: DELETE, GET, HEAD, POST, PUT
2308     < Server: CherryPy/3.1.2
2309     <
2310     &lt;nodes xmlns="http://www.ivoa.net/xml/VOSpace/v2.0"
2311     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2312     &lt;node uri="vos://nvo.caltech!vospace/mydir/img1" xsi:type="vos:UnstructuredDataNode">
2313     &lt;properties>
2314     &lt;property uri="ivo://ivoa.net/vospace/core#description">This is an R-band image of the galaxy NGC 3276&lt;/property>
2315     &lt;/properties>
2316     &lt;/node>
2317     &lt;node uri="vos://nvo.caltech!vospace/mydir/img5" xsi:type="vos:StructuredDataNode">
2318     &lt;properties>
2319     &lt;property uri="ivo://ivoa.net/vospace/core#description">This is a Chandra mosaic of the Fornax cluster of galaxies&lt;/property>
2320     &lt;/properties>
2321     &lt;/node>
2322     &lt;/nodes>
2323     * Connection #0 to host localhost left intact
2324     * Closing connection #0
2325     </pre></div></div>
2326    
2327     <h3><a name="sec5_4">5.4 Transferring data</a></h3>
2328     <p>Two modes are supported for external data transfers: a simple HTTP GET to
2329     retrieve data from a service (pullFromVoSpace) and a more general mechanism which
2330     employs a UWS-based approach [UWS] for submitting general data
2331     transfer requests (see section 3.6). In the latter, four directions
2332     are specified in which external data transfers can happen:
2333     <ul>
2334     <li> sending data to a service (pushToVoSpace)
2335     <li> importing data into a service (pullToVoSpace)
2336     <li> reading data from a service (pullFromVoSpace)
2337     <li> sending data from a service (pushFromVoSpace)
2338     </ul>
2339    
2340     <p>A transfer job is created by a HTTP POST of an appropriate Job
2341     representation to the transfers endpoint of the service: http://rest-endpoint/transfers</p>
2342     <p>The service returns the jobid of the transfer and it can then
2343     be initiated with a HTTP POST of the single parameter "PHASE=RUN" to
2344     the appropriate job endpoint:
2345     http://rest-endpoint/transfers/(jobid)/phase. Alternatively the
2346     transfer can also be run immediately on creation by adding a
2347     "PHASE=RUN" to the initial Job representation.</p>
2348     <p>The status of any transfer can be obtained by polling the phase
2349     endpoint for a particular transfer, i.e. a HTTP GET to
2350     http://rest-endpoint/transfers/(jobid)/phase.</p>
2351     <p>Once a transfer has completed, any results can be obtained by
2352     following the link in the Results List available from
2353     the results endpoint for that transfer, i.e. with a HTTP GET to
2354     http://rest-endpoint/transfers/(jobid)/results. This pertains
2355     particularly to the transfer methods in which data is sent to or
2356     read from a service-negotiated URL (pushToVoSpace and pullFromVoSpace).</p>
2357     <p>A transfer can also be aborted at any stage with a HTTP POST of
2358     the parameter "PHASE=ABORT" to the endpoint:
2359     http://rest-endpoint/transfers/(jobid)/phase</p>
2360     <p>More specific details for each of the four directions are given below.</p>
2361    
2362    
2363     <h4><a name="sec5_4_1">5.4.1 pushToVoSpace</h4>
2364     <p>Request a list of URLs to send data to a VOSpace node.
2365     </p><p>
2366     This method asks the server for a list of one or more URLs that the client can use to send data to.
2367     </p><p>
2368     The data transfer is initiated by the client, after it has received the response from the VOSpace service.
2369     </p><p>
2370     The primary use case for this method is client that wants to send some data directly to a VOSpace service.
2371     </p>
2372     <p>
2373     This operation is OPTIONAL.
2374     </p>
2375     <h5><a name="sec5_4_1_1">5.4.1.1 Request</a></h5>
2376     <ul<li> A HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers
2377     </ul><p>
2378     If a Node already exists at the target URI, then the data SHALL be imported into the existing Node and the Node properties SHALL be cleared unless the node is a ContainerNode.
2379     </p><p>
2380     If there is no Node at the target URI, then the service SHALL create a new Node using the uri and the default xsi:type for the space.
2381     </p><p>
2382     The transfer representation contains details of the View and a list of the Protocols that the client wants to use.
2383     </p><p>
2384     The list of Protocols SHOULD not contain endpoint addresses, the service will supply the endpoint addresses in the response.
2385     </p><p>
2386     The service SHALL ignore any of the requested protocols that it does not understand or is unable to support.
2387     </p><p>
2388     .auto is the reserved URI to indicate an auto-generated 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.
2389     </p>
2390 major.brian 2655 <p>
2391 major.brian 2689 A transfer may also be initiated with an HTTP POST of a Job representation of the transfer to http://rest-endpoint/sync in three different ways:
2392 major.brian 2655 <ul>
2393     <li>By posting the job representation to /sync. The service SHALL respond with a redirect to the job containing the transfer results.</li>
2394     <li>By doing a parameter-based post to /sync. The service may respond with the transfer details directly. (Optional. Example below)</li>
2395     <li>By doing a parameter-based post to /sync with additional parameter REQUEST=redirect. The service may respond with a redirect to a preferred transfer endpoint. (Optional.
2396 major.brian 2689 (Note that, because the client wishes to PUT data, the redirect cannot simply be followed, but needs to be read explicitly and reinitiated as a PUT)</li>
2397 major.brian 2655 </ul>
2398     </p>
2399 major.brian 2654 <h5><a name="sec5_4_1_2">5.4.1.2 Response</a></h5>
2400     <ul><li>The initial response is a HTTP 303 status code with the
2401     Location header keyword assigned to the created job.
2402     </ul><p>
2403     The service SHALL select which of the requested Protocols it is
2404     willing to provide and fill in the operational details for each one in
2405     the transfer result representation - this SHOULD normally include specifying the destination URL of the transfer protocol endpoint.
2406     </p><p>
2407     The transfer result SHOULD not include any Protocols that it is unable to support.
2408     </p>
2409     <p>
2410     The transfer results representation can be retrieved directly from the
2411     link reported in the Results List, available either from the results endpoint
2412     - http://rest-endpoint/transfers/(jobid)/results - or as part of the
2413     full Job representation for the completed transfer available from
2414     http://rest-endpoint/transfers/(jobid). The result
2415     element in the Results List SHALL have an id of
2416     "transferDetails":</p>
2417     <pre>
2418     &lt;uws:job>
2419     ...
2420     &lt;uws:results>
2421     &lt;uws:result id="transferDetails" xlink:href="http://rest-endpoint/transfers/(jobid)/results/details1"/>
2422     &lt;/uws:results>
2423     ...
2424     &lt;/uws:job>
2425     </pre>
2426     <p>For the alternate convenience mode:</p>
2427     <ul><li>A HTTP 303 status code with the Location
2428     header keyword ass